# HTTP API

> Authentication, errors, limits and every route of the Galerne HTTP API, generated from the tool registry.

The API lives at `https://api.galerne.cloud`. Every project route starts with `/p/<project>`, where `<project>` is the project slug. Bodies and responses are JSON unless a route says otherwise. This page is generated from the tool registry; the same routes are in [openapi.json](/docs/openapi.json).

## Authentication

Send a project token in the `Authorization` header. The `x-galerne-secret` header works too, for platforms that reserve `Authorization`.

```bash
curl https://api.galerne.cloud/p/acme/v1/schema \
  -H "Authorization: Bearer gal_…"
```

Tokens start with `gal_`. Each token has scopes: `read:published` (published content only), `read` (drafts and branches too), `write`, or `admin`. A higher scope includes the lower ones. See [agents and permissions](/docs/agents.md) for roles and agent rules.

Reads of published content work without a token on `POST /v1/query`, `GET /v1/query`, `GET /v1/schema` and media files, unless the project turns public reads off in its settings. Anonymous readers are limited to 600 requests per minute per IP address.

## Errors

Every error has the same shape. Validation errors list the field path and the rule, so a program or an agent can fix the input and retry.

```json
{
  "error": {
    "code": "validation",
    "message": "cannot publish: 1 validation error",
    "errors": [
      {
        "path": "title",
        "rule": "required",
        "message": "required"
      }
    ]
  }
}
```

| Status | Codes | Meaning |
|---|---|---|
| 400 | `invalid`, `invalid_input` | The input does not match the tool schema, or a value is not allowed |
| 401 | `unauthorized` | No token where one is needed, or the token is invalid, expired or revoked |
| 402 | `limit`, `paused`, `feature` | A plan limit is reached, writes are paused, or the feature is on a higher plan |
| 403 | `forbidden` | The role, scope or agent rules do not allow it; the message says which |
| 404 | `not_found` | Unknown project, document, branch, media or route |
| 409 | `conflict`, `exists`, `referenced` | Promotion conflicts, a newer revision, an id taken, or a document still referenced |
| 413 | `too_large` | The body is over the limit for that route |
| 422 | `validation` | Field values break the schema rules |
| 429 | `rate_limited` | Over the rate limit of the token; retry after the `retry-after` seconds |

## Limits per request

- Bodies: 10 MB, media uploads 200 MB, imports 100 MB and 100,000 documents.
- Rate limits are per minute: 600 for project tokens and people, 120 by default for agents (set per agent).
- `query` returns at most 1,000 documents per call; use `offset` to page.

## Routes from the tool registry

Path parameters in braces. Query string parameters are the tool inputs; numbers, booleans and JSON values are parsed. For `POST`, `PUT` and `PATCH`, the JSON body holds the inputs. `POST` routes that create something answer `201`.

| Method | Path | Tool |
|---|---|---|
| GET | `/p/<project>/v1/schema` | [`get_schema`](/docs/tools.md#get_schema) |
| GET | `/p/<project>/v1/guidelines` | [`get_guidelines`](/docs/tools.md#get_guidelines) |
| POST | `/p/<project>/v1/query` | [`query`](/docs/tools.md#query) |
| GET | `/p/<project>/v1/docs/{id}` | [`get_doc`](/docs/tools.md#get_doc) |
| GET | `/p/<project>/v1/docs` | [`list_docs`](/docs/tools.md#list_docs) |
| GET | `/p/<project>/v1/search` | [`search`](/docs/tools.md#search) |
| GET | `/p/<project>/v1/docs/{id}/history` | [`get_history`](/docs/tools.md#get_history) |
| GET | `/p/<project>/v1/branches` | [`list_branches`](/docs/tools.md#list_branches) |
| GET | `/p/<project>/v1/docs/{id}/references` | [`get_references`](/docs/tools.md#get_references) |
| POST | `/p/<project>/v1/check` | [`check`](/docs/tools.md#check) |
| POST | `/p/<project>/v1/branches` | [`create_branch`](/docs/tools.md#create_branch) |
| POST | `/p/<project>/v1/docs` | [`create_doc`](/docs/tools.md#create_doc) |
| PATCH | `/p/<project>/v1/docs/{id}` | [`patch_doc`](/docs/tools.md#patch_doc) |
| POST | `/p/<project>/v1/docs/{id}/publish` | [`publish_doc`](/docs/tools.md#publish_doc) |
| POST | `/p/<project>/v1/docs/{id}/unpublish` | [`unpublish_doc`](/docs/tools.md#unpublish_doc) |
| DELETE | `/p/<project>/v1/docs/{id}` | [`delete_doc`](/docs/tools.md#delete_doc) |
| POST | `/p/<project>/v1/docs/{id}/restore` | [`restore_version`](/docs/tools.md#restore_version) |
| POST | `/p/<project>/v1/media/import` | [`upload_media`](/docs/tools.md#upload_media) |
| GET | `/p/<project>/v1/media` | [`list_media`](/docs/tools.md#list_media) |
| GET | `/p/<project>/v1/media/{id}/info` | [`get_media`](/docs/tools.md#get_media) |
| PATCH | `/p/<project>/v1/media/{id}` | [`update_media`](/docs/tools.md#update_media) |
| GET | `/p/<project>/v1/branches/{branch}/changes` | [`branch_changes`](/docs/tools.md#branch_changes) |
| POST | `/p/<project>/v1/branches/{branch}/review` | [`request_review`](/docs/tools.md#request_review) |
| POST | `/p/<project>/v1/branches/{branch}/decision` | [`approve`](/docs/tools.md#approve) |
| POST | `/p/<project>/v1/comments` | [`comment`](/docs/tools.md#comment) |
| GET | `/p/<project>/v1/comments` | [`list_comments`](/docs/tools.md#list_comments) |
| POST | `/p/<project>/v1/branches/{branch}/promote` | [`promote`](/docs/tools.md#promote) |
| POST | `/p/<project>/v1/branches/{branch}/update` | [`update_from_main`](/docs/tools.md#update_from_main) |
| DELETE | `/p/<project>/v1/branches/{branch}` | [`close_branch`](/docs/tools.md#close_branch) |
| POST | `/p/<project>/v1/docs/{id}/schedule` | [`schedule`](/docs/tools.md#schedule) |
| GET | `/p/<project>/v1/schedules` | [`list_schedules`](/docs/tools.md#list_schedules) |
| DELETE | `/p/<project>/v1/schedules/{schedule}` | [`cancel_schedule`](/docs/tools.md#cancel_schedule) |
| POST | `/p/<project>/v1/schema/diff` | [`propose_schema_change`](/docs/tools.md#propose_schema_change) |
| PUT | `/p/<project>/v1/schema` | [`deploy_schema`](/docs/tools.md#deploy_schema) |
| GET | `/p/<project>/v1/audit` | [`get_audit_log`](/docs/tools.md#get_audit_log) |
| GET | `/p/<project>/v1/accessibility` | [`accessibility_report`](/docs/tools.md#accessibility_report) |
| PATCH | `/p/<project>/v1/branches/{branch}` | [`update_branch`](/docs/tools.md#update_branch) |
| POST | `/p/<project>/v1/promotions/{promotionId}/rollback` | [`rollback_promotion`](/docs/tools.md#rollback_promotion) |
| PATCH | `/p/<project>/v1/comments/{id}` | [`update_comment`](/docs/tools.md#update_comment) |
| DELETE | `/p/<project>/v1/comments/{id}` | [`delete_comment`](/docs/tools.md#delete_comment) |
| DELETE | `/p/<project>/v1/media/{id}` | [`delete_media`](/docs/tools.md#delete_media) |
| PUT | `/p/<project>/v1/media/{id}` | [`replace_media`](/docs/tools.md#replace_media) |
| GET | `/p/<project>/v1/cache` | [`get_cache_settings`](/docs/tools.md#get_cache_settings) |
| PUT | `/p/<project>/v1/cache` | [`set_cache_settings`](/docs/tools.md#set_cache_settings) |
| POST | `/p/<project>/v1/import/from` | [`import_from`](/docs/tools.md#import_from) |
| POST | `/p/<project>/v1/export/to` | [`export_to`](/docs/tools.md#export_to) |
| GET | `/p/<project>/v1/docs/{id}/analytics` | [`get_analytics`](/docs/tools.md#get_analytics) |
| POST | `/p/<project>/v1/site` | [`create_site`](/docs/tools.md#create_site) |
| DELETE | `/p/<project>/v1/site` | [`delete_site`](/docs/tools.md#delete_site) |
| POST | `/p/<project>/v1/site/refresh` | [`refresh_site`](/docs/tools.md#refresh_site) |
| GET | `/p/<project>/v1/code/files` | [`list_files`](/docs/tools.md#list_files) |
| GET | `/p/<project>/v1/code/file` | [`read_file`](/docs/tools.md#read_file) |
| POST | `/p/<project>/v1/code/commits` | [`write_files`](/docs/tools.md#write_files) |
| GET | `/p/<project>/v1/code/branches` | [`code_branches`](/docs/tools.md#code_branches) |
| GET | `/p/<project>/v1/code/changes` | [`code_changes`](/docs/tools.md#code_changes) |
| GET | `/p/<project>/v1/site/builds` | [`build_status`](/docs/tools.md#build_status) |
| GET | `/p/<project>/v1/site/builds/{deploymentId}/logs` | [`build_logs`](/docs/tools.md#build_logs) |
| GET | `/p/<project>/v1/site/preview` | [`preview_url`](/docs/tools.md#preview_url) |
| POST | `/p/<project>/v1/code/review` | [`request_code_review`](/docs/tools.md#request_code_review) |
| POST | `/p/<project>/v1/code/promote` | [`promote_code`](/docs/tools.md#promote_code) |
| POST | `/p/<project>/v1/code/mirrors` | [`set_mirror`](/docs/tools.md#set_mirror) |
| GET | `/p/<project>/v1/code/mirrors` | [`list_mirrors`](/docs/tools.md#list_mirrors) |
| POST | `/p/<project>/v1/code/git-access` | [`git_access`](/docs/tools.md#git_access) |
| POST | `/p/<project>/v1/code/theme` | [`update_theme`](/docs/tools.md#update_theme) |
| GET | `/p/<project>/v1/site/components` | [`list_components`](/docs/tools.md#list_components) |
| PATCH | `/p/<project>/v1/site/settings` | [`update_site_settings`](/docs/tools.md#update_site_settings) |
| POST | `/p/<project>/v1/site/env` | [`site_env`](/docs/tools.md#site_env) |
| GET | `/p/<project>/v1/site/analytics` | [`site_analytics`](/docs/tools.md#site_analytics) |
| PUT | `/p/<project>/v1/site/analytics` | [`set_site_analytics`](/docs/tools.md#set_site_analytics) |
| GET | `/p/<project>/v1/sources` | [`list_sources`](/docs/tools.md#list_sources) |
| GET | `/p/<project>/v1/sources/runs` | [`source_runs`](/docs/tools.md#source_runs) |
| GET | `/p/<project>/v1/sources/{name}` | [`get_source`](/docs/tools.md#get_source) |
| POST | `/p/<project>/v1/sources` | [`create_source`](/docs/tools.md#create_source) |
| PATCH | `/p/<project>/v1/sources/{name}` | [`update_source`](/docs/tools.md#update_source) |
| DELETE | `/p/<project>/v1/sources/{name}` | [`delete_source`](/docs/tools.md#delete_source) |
| POST | `/p/<project>/v1/sources/{name}/sync` | [`sync_source`](/docs/tools.md#sync_source) |

## Other routes

| Method | Path | What it does |
|---|---|---|
| GET | `/p/<project>/v1/tools` | The tools your token may call, with JSON Schemas and REST routes. |
| POST | `/p/<project>/v1/tools/<name>` | Calls any tool. The body is the tool input. |
| GET | `/p/<project>/v1/query?q=<json>` | Same as the query tool, cacheable. Published content read without a token is cached at the CDN for 60 seconds. |
| POST | `/p/<project>/v1/media` | Uploads a file: raw body, `content-type` header, `?filename=`, `?alt=`, `?title=`; `x-galerne-media-id` keeps an id from another system. See [media](/docs/media.md). |
| GET | `/p/<project>/media/<id>[/<name>]` | Serves a file, with `?w=&h=&fit=&fm=` transforms and Range requests. |
| GET | `/p/<project>/v1/schema/config` | The deployed `galerne.config.ts`, as JSON. `?branch=` returns the one a branch uses. |
| GET | `/p/<project>/v1/export?branch=main` | Plain export as NDJSON. See [export format](/docs/export.md). |
| POST | `/p/<project>/v1/import?branch=<branch>[&dryRun=1]` | Imports NDJSON doc lines onto a branch and returns a report. See [import lines](/docs/export.md#import-lines). |
| GET | `/p/<project>/v1/audit.csv` | Every audit log entry as CSV, newest first (Business, `admin` scope). See [audit log](/docs/agents.md#audit-log). |
| GET | `/p/<project>/v1/events` | Recent events, newest first (`?limit=`, `?before=`). See [event stream](/docs/events.md). |
| GET | `/p/<project>/v1/events/stream` | Server-Sent Events of every event (Pro and up), filtered with `?types=`. Resume with `Last-Event-ID` or `?since=`. |
| POST | `/p/<project>/v1/sources/<name>/hook` | Runs a data source now. Authenticated with the source's hook secret. See [data sources](/docs/sources.md#webhook-trigger). |
| GET | `/p/<project>/v1/billing` | Plan, subscription, usage charges and invoices (admins). See [billing](/docs/billing.md#billing-api). |
| POST | `/p/<project>/v1/billing/checkout` | Starts a Mollie checkout for Pro or Business, monthly or yearly. |
| POST | `/p/<project>/v1/billing/plan` | Changes between Pro and Business. |
| POST | `/p/<project>/v1/billing/interval` | Changes between monthly and yearly, from the next period. |
| POST | `/p/<project>/v1/billing/cancel` | Cancels at the end of the paid period. |
| POST | `/p/<project>/v1/billing/resume` | Undoes a cancel before the period ends. |
| GET | `/p/<project>/v1/billing/invoices` | Invoices of the project. |
| GET | `/p/<project>/v1/billing/invoices/<id>` | One invoice as a printable HTML page. |
| POST | `/p/<project>/mcp` | The MCP server (streamable HTTP). See [agents](/docs/agents.md). |
| GET | `/p/<project>/llms.txt` | Index of published documents for agents, when turned on. See [site settings](/docs/site.md). |
| GET | `/p/<project>/md/<id>.md` | A published document as Markdown, when turned on. |
| GET | `/overlay.js` | The visual editing overlay. See [visual editing](/docs/visual-editing.md). |
| GET | `/scim/v2/…` | SCIM 2.0 users, with a `gal_scim_` token. See [SSO and SCIM](/docs/sso.md). |
| POST | `/billing/mollie/webhook` | Mollie's payment notifications. Takes only a payment id and fetches the payment from Mollie. |
| POST | `/sites/forgejo/<project>` | The push webhook of a managed site's repo, signed per project. Galerne's Forgejo calls it. See [sites and code](/docs/sites.md). |
| GET | `/openapi.json` | The OpenAPI document of the API. |
| GET | `/` | The API name and links to the docs and the OpenAPI document. |
| GET | `/healthz` | Answers `ok` when the API reaches its database. |

## OAuth

MCP clients sign in with OAuth 2.1: dynamic client registration, authorization code with PKCE (S256), and rotating refresh tokens. Access tokens last one hour and refresh tokens 60 days.

| Route | Use |
|---|---|
| `GET /.well-known/oauth-authorization-server` | Authorization server metadata |
| `GET /.well-known/openid-configuration` | The same metadata, for clients that look there |
| `GET /.well-known/oauth-protected-resource/p/<project>/mcp` | Protected resource metadata of a project MCP server |
| `GET /p/<project>/mcp/.well-known/oauth-protected-resource` | The same, at the path some clients try first |
| `POST /oauth/register` | Client registration (RFC 7591) |
| `POST /oauth/token` | Code exchange and refresh |
| `POST /oauth/revoke` | Token revocation |

The consent page is in the studio. There the person picks the project and the agent member the client acts as.
