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.
Routes
Section titled “Routes”| 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.
Headers
Section titled “Headers”| 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 |
Status codes
Section titled “Status codes”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.
Where the TypeScript server differs
Section titled “Where the TypeScript server differs”| 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.