# API

The API lives at `https://zpxforge.com/api/v1`. The full specification (OpenAPI) is at
[`/api/v1/docs`](/api/v1/docs).

## Authentication

Today the API uses the **browser session** (an `httpOnly` cookie). Requests that change data must come
from the site itself (`Origin` header).

The CLI uses a personal token authorized in the browser for supported endpoints. Customers record decisions in their verified web sessions.

## Endpoints

| Method and path | What it does |
|---|---|
| `GET /v1/health` | Platform health (database, Redis, worker) |
| `GET /v1/me` | The person, their companies and pending invitations |
| `GET /v1/roles` | Available roles |
| `POST /v1/orgs` | Register a company |
| `GET /v1/orgs/{company}` | Company, your role and your permissions |
| `GET /v1/orgs/{company}/members` | Members |
| `PATCH /v1/orgs/{company}/members/{id}` | Change a member's role |
| `POST /v1/orgs/{company}/invitations` | Invite by email |
| `GET /v1/orgs/{company}/projects` | Projects |
| `POST /v1/orgs/{company}/projects` | Create a project |
| `PUT /v1/orgs/{company}/projects/{p}/roles/{id}` | A person's role within a project |
| `GET /v1/orgs/{company}/github` | GitHub installations and repos |
| `POST /v1/orgs/{company}/projects/{p}/repos` | Connect a repo to the project |
| `POST /v1/orgs/{company}/projects/{p}/repos/{id}/protect` | Protect `develop` and `main` |
| `GET /v1/orgs/{company}/audit` | Audit log (admins only) |

## Errors

```json
{ "detail": "Tu rol no permite esta acción", "code": "forbidden" }
```

Error messages are in Spanish for now; rely on `code` and the HTTP status.

| HTTP status | Meaning |
|---|---|
| `401` | You need to sign in |
| `403` | No permission, inactive company or origin not allowed |
| `404` | It does not exist or you do not belong to that company |
| `409` | Conflict (for example, the last admin) |
| `429` | Too many attempts |
