docs menu

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.

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 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"
      }
    ]
  }
}
StatusCodesMeaning
400invalid, invalid_inputThe input does not match the tool schema, or a value is not allowed
401unauthorizedNo token where one is needed, or the token is invalid, expired or revoked
402limit, paused, featureA plan limit is reached, writes are paused, or the feature is on a higher plan
403forbiddenThe role, scope or agent rules do not allow it; the message says which
404not_foundUnknown project, document, branch, media or route
409conflict, exists, referencedPromotion conflicts, a newer revision, an id taken, or a document still referenced
413too_largeThe body is over the limit for that route
422validationField values break the schema rules
429rate_limitedOver 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.

MethodPathTool
GET/p/<project>/v1/schemaget_schema
GET/p/<project>/v1/guidelinesget_guidelines
POST/p/<project>/v1/queryquery
GET/p/<project>/v1/docs/{id}get_doc
GET/p/<project>/v1/docslist_docs
GET/p/<project>/v1/searchsearch
GET/p/<project>/v1/docs/{id}/historyget_history
GET/p/<project>/v1/brancheslist_branches
GET/p/<project>/v1/docs/{id}/referencesget_references
POST/p/<project>/v1/checkcheck
POST/p/<project>/v1/branchescreate_branch
POST/p/<project>/v1/docscreate_doc
PATCH/p/<project>/v1/docs/{id}patch_doc
POST/p/<project>/v1/docs/{id}/publishpublish_doc
POST/p/<project>/v1/docs/{id}/unpublishunpublish_doc
DELETE/p/<project>/v1/docs/{id}delete_doc
POST/p/<project>/v1/docs/{id}/restorerestore_version
POST/p/<project>/v1/media/importupload_media
GET/p/<project>/v1/medialist_media
GET/p/<project>/v1/media/{id}/infoget_media
PATCH/p/<project>/v1/media/{id}update_media
GET/p/<project>/v1/branches/{branch}/changesbranch_changes
POST/p/<project>/v1/branches/{branch}/reviewrequest_review
POST/p/<project>/v1/branches/{branch}/decisionapprove
POST/p/<project>/v1/commentscomment
GET/p/<project>/v1/commentslist_comments
POST/p/<project>/v1/branches/{branch}/promotepromote
POST/p/<project>/v1/branches/{branch}/updateupdate_from_main
DELETE/p/<project>/v1/branches/{branch}close_branch
POST/p/<project>/v1/docs/{id}/scheduleschedule
GET/p/<project>/v1/scheduleslist_schedules
DELETE/p/<project>/v1/schedules/{schedule}cancel_schedule
POST/p/<project>/v1/schema/diffpropose_schema_change
PUT/p/<project>/v1/schemadeploy_schema
GET/p/<project>/v1/auditget_audit_log
GET/p/<project>/v1/accessibilityaccessibility_report
PATCH/p/<project>/v1/branches/{branch}update_branch
POST/p/<project>/v1/promotions/{promotionId}/rollbackrollback_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/cacheget_cache_settings
PUT/p/<project>/v1/cacheset_cache_settings
POST/p/<project>/v1/import/fromimport_from
POST/p/<project>/v1/export/toexport_to
GET/p/<project>/v1/docs/{id}/analyticsget_analytics
POST/p/<project>/v1/sitecreate_site
DELETE/p/<project>/v1/sitedelete_site
POST/p/<project>/v1/site/refreshrefresh_site
GET/p/<project>/v1/code/fileslist_files
GET/p/<project>/v1/code/fileread_file
POST/p/<project>/v1/code/commitswrite_files
GET/p/<project>/v1/code/branchescode_branches
GET/p/<project>/v1/code/changescode_changes
GET/p/<project>/v1/site/buildsbuild_status
GET/p/<project>/v1/site/builds/{deploymentId}/logsbuild_logs
GET/p/<project>/v1/site/previewpreview_url
POST/p/<project>/v1/code/reviewrequest_code_review
POST/p/<project>/v1/code/promotepromote_code
POST/p/<project>/v1/code/mirrorsset_mirror
GET/p/<project>/v1/code/mirrorslist_mirrors
POST/p/<project>/v1/code/git-accessgit_access
POST/p/<project>/v1/code/themeupdate_theme
GET/p/<project>/v1/site/componentslist_components
PATCH/p/<project>/v1/site/settingsupdate_site_settings
POST/p/<project>/v1/site/envsite_env
GET/p/<project>/v1/site/analyticssite_analytics
PUT/p/<project>/v1/site/analyticsset_site_analytics
GET/p/<project>/v1/sourceslist_sources
GET/p/<project>/v1/sources/runssource_runs
GET/p/<project>/v1/sources/{name}get_source
POST/p/<project>/v1/sourcescreate_source
PATCH/p/<project>/v1/sources/{name}update_source
DELETE/p/<project>/v1/sources/{name}delete_source
POST/p/<project>/v1/sources/{name}/syncsync_source

Other routes#

MethodPathWhat it does
GET/p/<project>/v1/toolsThe 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/mediaUploads 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/configThe deployed galerne.config.ts, as JSON. ?branch= returns the one a branch uses.
GET/p/<project>/v1/export?branch=mainPlain 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.csvEvery audit log entry as CSV, newest first (Business, admin scope). See audit log.
GET/p/<project>/v1/eventsRecent events, newest first (?limit=, ?before=). See event stream.
GET/p/<project>/v1/events/streamServer-Sent Events of every event (Pro and up), filtered with ?types=. Resume with Last-Event-ID or ?since=.
POST/p/<project>/v1/sources/<name>/hookRuns a data source now. Authenticated with the source's hook secret. See data sources.
GET/p/<project>/v1/billingPlan, subscription, usage charges and invoices (admins). See billing.
POST/p/<project>/v1/billing/checkoutStarts a Mollie checkout for Pro or Business, monthly or yearly.
POST/p/<project>/v1/billing/planChanges between Pro and Business.
POST/p/<project>/v1/billing/intervalChanges between monthly and yearly, from the next period.
POST/p/<project>/v1/billing/cancelCancels at the end of the paid period.
POST/p/<project>/v1/billing/resumeUndoes a cancel before the period ends.
GET/p/<project>/v1/billing/invoicesInvoices of the project.
GET/p/<project>/v1/billing/invoices/<id>One invoice as a printable HTML page.
POST/p/<project>/mcpThe MCP server (streamable HTTP). See agents.
GET/p/<project>/llms.txtIndex of published documents for agents, when turned on. See site settings.
GET/p/<project>/md/<id>.mdA published document as Markdown, when turned on.
GET/overlay.jsThe 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/webhookMollie'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.jsonThe OpenAPI document of the API.
GET/The API name and links to the docs and the OpenAPI document.
GET/healthzAnswers 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.

RouteUse
GET /.well-known/oauth-authorization-serverAuthorization server metadata
GET /.well-known/openid-configurationThe same metadata, for clients that look there
GET /.well-known/oauth-protected-resource/p/<project>/mcpProtected resource metadata of a project MCP server
GET /p/<project>/mcp/.well-known/oauth-protected-resourceThe same, at the path some clients try first
POST /oauth/registerClient registration (RFC 7591)
POST /oauth/tokenCode exchange and refresh
POST /oauth/revokeToken revocation

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