# REST API

> The planned GoForma REST API, with the same data and permissions as the client MCP server.

# REST API

> **Status: planned, not live.** Endpoints below are the agreed design and may change before launch. Use the [client MCP server](/ai/mcp/) today.

## Design

- **Base address:** `https://mcp.goforma.com/v1`, served next to the MCP server, so one sign-in covers both.
- **Auth:** OAuth 2.0 authorisation code with PKCE, on the same sign-in as the MCP server. Scopes are the same as MCP: `read`, `act`, `finance:read`. If your client sends an RFC 8707 `resource`, use `https://mcp.goforma.com/v1`. A token issued for the MCP server (`…/mcp`) is not accepted by the API.
- **Data:** JSON. Deadlines and post carry stable ids for deduplication. Errors are RFC 9457 problem details (`application/problem+json`), and a missing permission returns 403 with `required_scopes`. Rate limit: 120 requests a minute per person.
- **Reference:** an OpenAPI 3.1 file will be published at `/openapi.json` on this site.

## Planned endpoints

| Method and path | Scope | Returns or does |
|---|---|---|
| `GET /v1/me` | read | The signed-in person |
| `GET /v1/companies` | read | Companies this person can see |
| `GET /v1/company` | read | The active company's profile |
| `GET /v1/deadlines` | read | Upcoming deadlines |
| `GET /v1/filings`, `GET /v1/filings/{id}` | read | Filing status, or one filing |
| `GET /v1/mail?since=&limit=` | read | Post received, newest first |
| `GET /v1/onboarding` | read | Onboarding progress |
| `GET /v1/verification` | read | Identity check status |
| `GET /v1/accountant` | read | Your accountant and how to book a call |
| `POST /v1/requests` | act | Sends a request to your GoForma team |
| `POST /v1/deadlines/{id}/chase` | act | Asks for an update on a deadline |
| `GET /v1/finance/snapshot`, `GET /v1/finance/invoices` | finance:read | Figures from FreeAgent |

Never in the API: filing with HMRC or Companies House, payments or card details, FreeAgent writes.