> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fortressproductivity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST reference

> Primary REST conventions and generated API reference.

The REST API contract is generated from the API route definitions and rendered in the Reference tab's REST API section.

Most product endpoints live under `/v1/`.

```text theme={"theme":"github-dark"}
Production: https://api.fortressproductivity.com/v1
Local:      http://localhost:3000/v1
```

## Authentication

| Caller           | Auth mode                                        |
| ---------------- | ------------------------------------------------ |
| Human web app    | Session cookie                                   |
| Agent            | `Authorization: Bearer ft_...`                   |
| OAuth MCP client | OAuth 2.1 flow, then agent-scoped internal token |

Human routes can fall back to the first workspace in local development. Agent routes resolve the workspace from the bearer token.

## List response envelope

Every list endpoint returns the same envelope:

```json theme={"theme":"github-dark"}
{
  "items": [],
  "total": 0,
  "filters": {},
  "hidden_count": 0
}
```

Only `items` is always present. Other fields appear when the endpoint has that metadata.

## Example agent completion

```http theme={"theme":"github-dark"}
POST /v1/actions/act_123/complete HTTP/1.1
Authorization: Bearer ft_example
Content-Type: application/json

{
  "result_summary": "Reviewed the queue and closed the stale PR notification.",
  "links": [
    {
      "title": "Closed PR",
      "url": "https://github.com/example/repo/pull/412"
    }
  ]
}
```

## Error envelope

Errors use a stable JSON envelope:

```json theme={"theme":"github-dark"}
{
  "code": "CAP_EXCEEDED",
  "message": "Free plan limit reached",
  "issues": [],
  "details": {}
}
```

Branch on `code` and structured `details` when building clients.

## OpenAPI contract

Every Fortress REST endpoint is described by a single OpenAPI 3.1 document generated directly from the route definitions. Use it to:

* Generate typed clients in any language.
* Validate requests and responses in your own code.
* Power editor tooling and API explorers.

### Fetch the live contract

`GET /openapi.json` returns the contract for the running server, including request schemas, response schemas, and auth metadata.

```bash theme={"theme":"github-dark"}
curl https://api.fortressproductivity.com/openapi.json
```

The same document is published as a static artifact alongside this site, so the **REST API** section in the Reference tab stays in lockstep with the deployed routes.