Skip to main content
Every Pascal API answers in JSON, errors included, so an agent can branch on a code instead of parsing a page. This page covers the Scene API (/api/...), the hosted MCP server (/api/mcp) and the Pascal API (/api/v1).

Error bodies

Every Pascal API error carries the same four fields: a type (invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, rate_limit_error or api_error), a machine-readable code, a message for people and a doc_url. Where they sit depends on the API, so existing clients keep working. The Scene API keeps its error code as a string and adds the fields beside it, with a hint when there is a known fix:
The Pascal API uses the OpenAI error shape: the fields, plus param, under error; its codes are listed under Pascal API errors. The MCP server answers protocol errors as JSON-RPC errors, with the fields in error.data (error.code stays the JSON-RPC number), and tool failures as tool results.

Unknown routes

A path under /api that no route serves answers 404 in the same envelope as the Pascal API, instead of an HTML page:
Its Link header points at the API catalog and the OpenAPI document. A page request for a missing path with Accept: text/markdown gets a Markdown 404 that links the docs, /llms.txt and the sitemap.

Authentication challenges

A request without a valid credential answers 401 with a WWW-Authenticate challenge that points at the protected resource metadata (RFC 9728) and names the scopes an authorization request must carry: the resource’s own, plus offline_access, which every registered client requests:
The Pascal API (/api/v1) takes API keys only. Its challenge points at its own resource metadata, which names no authorization server. /api, /api/v1 and any path under /api/v1 answer 401 with a challenge when no credential is sent. A connection holding scene:read alone can call the read-only tools; scene:write covers the tools that change a project. Each tool’s scope is published at /.well-known/mcp.

Rate limits

Every response the Scene API and the MCP server count carries the IETF rate-limit fields: RateLimit-Policy names each window and its quota, RateLimit its remaining requests and the seconds until it resets.
Each request counts against every window listed. Over a limit, the answer is 429 with Retry-After in seconds and nothing ran, so the same request is safe to send again once that time has passed. The budget per address and credential exists because many people can reach Pascal from one address: every Claude user arrives from Anthropic’s egress range.

Versioning and deprecation

The Scene API is versioned in its OpenAPI document (info.version) and the Pascal API in its path (/api/v1). Within a version, Pascal adds fields, endpoints, tools and error codes without notice; clients should ignore what they don’t recognise. Removing or renaming a field, changing its meaning, or removing an endpoint happens only through deprecation:
  1. The endpoint is marked deprecated: true in the OpenAPI document, and every response from it carries a Deprecation header (RFC 9745) with the date it was deprecated, a Link with rel="deprecation" to this section, and a Link with rel="successor-version" to its replacement.
  2. When a removal date is set, responses also carry a Sunset header (RFC 8594) with that date, and the change is announced in the changelog.
  3. After the sunset date the endpoint may answer 410 Gone or be removed.
Currently deprecated: Neither has a sunset date yet.

Request ids

Pascal API and MCP answers carry a Request-Id header. Quote it when you contact support.