HTTP API
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.
Authentication#
Send a project token in the Authorization header. The x-galerne-secret header works too, for platforms that reserve Authorization.
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 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.
{
"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).
queryreturns at most 1,000 documents per call; useoffsetto 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 |
| GET | /p/<project>/v1/guidelines | get_guidelines |
| POST | /p/<project>/v1/query | query |
| GET | /p/<project>/v1/docs/{id} | get_doc |
| GET | /p/<project>/v1/docs | list_docs |
| GET | /p/<project>/v1/search | search |
| GET | /p/<project>/v1/docs/{id}/history | get_history |
| GET | /p/<project>/v1/branches | list_branches |
| GET | /p/<project>/v1/docs/{id}/references | get_references |
| POST | /p/<project>/v1/check | check |
| POST | /p/<project>/v1/branches | create_branch |
| POST | /p/<project>/v1/docs | create_doc |
| PATCH | /p/<project>/v1/docs/{id} | patch_doc |
| POST | /p/<project>/v1/docs/{id}/publish | publish_doc |
| POST | /p/<project>/v1/docs/{id}/unpublish | unpublish_doc |
| DELETE | /p/<project>/v1/docs/{id} | delete_doc |
| POST | /p/<project>/v1/docs/{id}/restore | restore_version |
| POST | /p/<project>/v1/media/import | upload_media |
| GET | /p/<project>/v1/media | list_media |
| GET | /p/<project>/v1/media/{id}/info | get_media |
| PATCH | /p/<project>/v1/media/{id} | update_media |
| GET | /p/<project>/v1/branches/{branch}/changes | branch_changes |
| POST | /p/<project>/v1/branches/{branch}/review | request_review |
| POST | /p/<project>/v1/branches/{branch}/decision | approve |
| POST | /p/<project>/v1/comments | comment |
| GET | /p/<project>/v1/comments | list_comments |
| POST | /p/<project>/v1/branches/{branch}/promote | promote |
| POST | /p/<project>/v1/branches/{branch}/update | update_from_main |
| DELETE | /p/<project>/v1/branches/{branch} | close_branch |
| POST | /p/<project>/v1/docs/{id}/schedule | schedule |
| GET | /p/<project>/v1/schedules | list_schedules |
| DELETE | /p/<project>/v1/schedules/{schedule} | cancel_schedule |
| POST | /p/<project>/v1/schema/diff | propose_schema_change |
| PUT | /p/<project>/v1/schema | deploy_schema |
| GET | /p/<project>/v1/audit | get_audit_log |
| GET | /p/<project>/v1/accessibility | accessibility_report |
| PATCH | /p/<project>/v1/branches/{branch} | update_branch |
| POST | /p/<project>/v1/promotions/{promotionId}/rollback | rollback_promotion |
| PATCH | /p/<project>/v1/comments/{id} | update_comment |
| DELETE | /p/<project>/v1/comments/{id} | delete_comment |
| DELETE | /p/<project>/v1/media/{id} | delete_media |
| PUT | /p/<project>/v1/media/{id} | replace_media |
| GET | /p/<project>/v1/cache | get_cache_settings |
| PUT | /p/<project>/v1/cache | set_cache_settings |
| POST | /p/<project>/v1/import/from | import_from |
| POST | /p/<project>/v1/export/to | export_to |
| GET | /p/<project>/v1/docs/{id}/analytics | get_analytics |
| POST | /p/<project>/v1/site | create_site |
| DELETE | /p/<project>/v1/site | delete_site |
| POST | /p/<project>/v1/site/refresh | refresh_site |
| GET | /p/<project>/v1/code/files | list_files |
| GET | /p/<project>/v1/code/file | read_file |
| POST | /p/<project>/v1/code/commits | write_files |
| GET | /p/<project>/v1/code/branches | code_branches |
| GET | /p/<project>/v1/code/changes | code_changes |
| GET | /p/<project>/v1/site/builds | build_status |
| GET | /p/<project>/v1/site/builds/{deploymentId}/logs | build_logs |
| GET | /p/<project>/v1/site/preview | preview_url |
| POST | /p/<project>/v1/code/review | request_code_review |
| POST | /p/<project>/v1/code/promote | promote_code |
| POST | /p/<project>/v1/code/mirrors | set_mirror |
| GET | /p/<project>/v1/code/mirrors | list_mirrors |
| POST | /p/<project>/v1/code/git-access | git_access |
| POST | /p/<project>/v1/code/theme | update_theme |
| GET | /p/<project>/v1/site/components | list_components |
| PATCH | /p/<project>/v1/site/settings | update_site_settings |
| POST | /p/<project>/v1/site/env | site_env |
| GET | /p/<project>/v1/site/analytics | site_analytics |
| PUT | /p/<project>/v1/site/analytics | set_site_analytics |
| GET | /p/<project>/v1/sources | list_sources |
| GET | /p/<project>/v1/sources/runs | source_runs |
| GET | /p/<project>/v1/sources/{name} | get_source |
| POST | /p/<project>/v1/sources | create_source |
| PATCH | /p/<project>/v1/sources/{name} | update_source |
| DELETE | /p/<project>/v1/sources/{name} | delete_source |
| POST | /p/<project>/v1/sources/{name}/sync | 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. |
| 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. |
| POST | /p/<project>/v1/import?branch=<branch>[&dryRun=1] | Imports NDJSON doc lines onto a branch and returns a report. See import lines. |
| GET | /p/<project>/v1/audit.csv | Every audit log entry as CSV, newest first (Business, admin scope). See audit log. |
| GET | /p/<project>/v1/events | Recent events, newest first (?limit=, ?before=). See event stream. |
| 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. |
| GET | /p/<project>/v1/billing | Plan, subscription, usage charges and invoices (admins). See billing. |
| 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. |
| GET | /p/<project>/llms.txt | Index of published documents for agents, when turned on. See site settings. |
| GET | /p/<project>/md/<id>.md | A published document as Markdown, when turned on. |
| GET | /overlay.js | The visual editing overlay. See visual editing. |
| GET | /scim/v2/… | SCIM 2.0 users, with a gal_scim_ token. See SSO and SCIM. |
| 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. |
| 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.