Skip to content

HTTP contract reference

The language-neutral Arc HTTP contract is the specification: routes, methods, headers, result envelopes, status codes, identity, and validation values. This page lists what Arc for TypeScript serves against it. The status of each difference, and the evidence for it, is in the capability reference.

Path Methods Answer
A command route, such as /api/tasks/registration/register-task POST Command result
<command route>/validate POST Command result after authorization and validation; the handler never runs
A query route, such as /api/tasks/listing/all-tasks GET, and QUERY unless disabled Query result; QUERY responses carry Cache-Control: no-store
An observable query route GET, QUERY, SSE with Accept: text/event-stream, direct WebSocket upgrade Current snapshot, a stream of direct SSE results, or direct WebSocket Data frames
/.cratis/queries/ws WebSocket upgrade Multiplexed WebSocket hub
/.cratis/queries/sse, /.cratis/queries/sse/subscribe, /.cratis/queries/sse/unsubscribe GET, and authenticated POST Multiplexed SSE stream and its caller-bound controls
/.cratis/commands, /.cratis/queries GET Command and query metadata with input JSON Schema
/.cratis/identity-details/schema GET Identity details JSON Schema, or {}
/.cratis/me GET, when an identity details provider exists 401 anonymous, 403 provider denied, 200 identity JSON with display cookie
/.cratis/users, /.cratis/tenants GET [] by default; opt-in development discovery
/.cratis/queries/health GET and QUERY, when enabled Caller-scoped hub health; requires authentication
/openapi.json GET OpenAPI 3.1 document

The catalogs, identity schema, users, tenants, and /openapi.json are anonymous only in Development by default. Elsewhere they run the configured authentication handlers and require an authenticated principal (401 anonymous, 403 missing a configured role). Without authentication they are unmapped; explicitly requiring it without handlers fails startup. See Discovery access for environment detection, roles, and the anonymous opt-out. Methods that reach Arc but are not accepted answer 405 with an Allow header. Route shapes are explained in Endpoint mapping.

introspection.enabled defaults to true. Setting it to false (Node configuration: Cratis:Arc:Introspection:Enabled) leaves /.cratis/commands, /.cratis/queries, and /openapi.json unmapped in every environment, normally returning 404. Identity discovery and in-process openApi() / exportClientManifest are unchanged. See Turn discovery off, including the authentication-warning interaction and TypeScript’s extension of the switch to HTTP OpenAPI.

Header Direction Meaning
X-Correlation-ID (configurable) Request and response Reused when a valid non-zero UUID, otherwise replaced; always returned
X-Allowed-Severity Request 0, 1, or 2 on commands; 3 is capped to 2; ignored on queries
x-cratis-tenant-id (configurable) Request The requested tenant without tenancy.resolve or another configured tenant source
Authorization Request Read only by the authentication handlers you configure
Cache-Control: no-store Response On QUERY responses, discovery responses, and /.cratis/me
Allow Response On 405 answers
Retry-After: 1 Response On observable admission 503 answers

A result is 200 when successful, then 403 for authorization failures, 400 for validation and malformed input, 202 for a pending observable snapshot, and 500 for exceptions, in the contract’s order. 401 answers an anonymous caller on a protected operation when authentication handlers are configured, and any failed authentication. Observable routes also use 408 for a timed-out first-result wait and 503 when a limit is reached.

Area Arc on .NET Arc for TypeScript
X-Allowed-Severity: 3 Runs a command with only error results Treated as Warning; errors block
Anonymous caller on a protected operation 403 401 when handlers are configured
Malformed request message Framework message Malformed request
Redacted exception message Framework message An unexpected error occurred
Invalid GUID query argument 400 malformedRequest with argument details 400 malformedRequest with a generic message
SSE hub Anonymous controls allowed Requires an authenticated principal
Query health Anonymous, cross-caller Opt-in, caller-scoped
Discovery denial body Empty 401/403 on the ASP.NET fixture JSON { error } with the same status
waitForFirstResultTimeout Larger values accepted; unknown booleans ignored At most 120 seconds; unknown booleans rejected

Numeric concept GET arguments bind successfully on both runtimes. Both apply GET sorting and reject invalid sort directions. The suite also pins a host-specific difference that is not a choice of Arc for TypeScript:

Request Arc on .NET 22.45.0 Arc for TypeScript
An unknown path under Express Empty 404 with a correlation header Express’s own HTML 404, without an Arc correlation header

The paired yarn test:conformance suite pins these differences against a .NET host on Cratis.Arc 22.45.0; see How parity is checked.