HTTP routes and .NET client reference

All paths below are relative to the current discovered endpoint. After pairing and handshake, send the session token as Authorization: Bearer <accessToken>. Requests and responses use JSON with camelCase field names.

Live contract and schemas

With host.status, read GET /api/v1/openapi.json for the running Core's methods and GET /api/v1/schemas/{name} for a named DTO. In .NET use GetOpenApiAsync and GetSchemaAsync. GET /api/v1/examples/{name} / GetExampleAsync exposes supported named examples.

The route table is checked against the repository's public ApiSurface.Endpoints and ApiClientCoverage.Methods. Request and response names identify public Contracts types; query parameters and full field definitions are described by the live OpenAPI and named schemas. Generate or validate non-.NET payloads against that running contract. PowerShell testing shows how to retrieve it.

Route table

GetFileLocationsAsync lists approved logical folder IDs, names, operation rights and flags for the current project. Machine paths are excluded. Folder approval, rebinding and revocation belong to the trusted Core Settings window; settings.write, project.write and runtime scopes cannot modify those local approvals. Catalog IDs beginning Core.Files. require the project's separate folder permissions when executed.

GetFileDirectoryAsync(locationId) requires project.files plus the location's local List and inspect permission. It supplies bounded relative file/folder metadata for path selection, including empty folders, with no content or absolute paths. Subfolder permissions, truncation and permission-revision checks remain enforced.

— means no typed body/schema. public, session, pipe ticket and stream-specific describe authorization stages, not grantable scopes. Comma-separated permissions are required together; command lookup authorizes the specific command family, not every scope shown as an alternative.

202 accepts work; inspect the returned operation/run until completion. 101 is a WebSocket upgrade. The retired layout routes return editor_layout_local; store layout in your client. Named Pipe bootstrap is an internal local-launch path with only status access and is not a substitute for external-client pairing.

Read coherent state

GetCompleteSnapshotAsync follows snapshot pages while pinning Host/project identity, revision and cursor. Resource lists use pageToken, pageSize and optional search where supported. Encode path segments and query values; do not treat a resource's display name as its ID.

Ordinary project.read responses omit content-bearing configuration. Additional project.configuration.read can be required for definitions and editor forms; protected fields remain redacted. Dynamic options require catalog.read, project.configuration.read and settings.read together. Context file operations require project.files.

Project revision, plugin resource version, local settings version and runtime observations are distinct. Read the relevant version before a write. A runtime variable observation is not an edit to its saved default.

Operations, recovery and limits

WaitForOperationAsync waits for a terminal file outcome or waiting_for_interaction. An authorized interaction responder must claim/respond where required; this is not implicit permission to approve passwords or trust. WaitForRunAsync waits for a run's terminal state. Cancelling a wait does not cancel Core work.

The default .NET client bounds responses to 2 MiB and HTTP calls to 15 seconds. Core also enforces endpoint/body/page/stream limits and rate limits; handle explicit refusal instead of interpreting a truncated observation as complete state.

Handle revision_conflict, schema_changed, stale identity, incompatible contracts, revoked/expired access and unknown command outcomes separately. See partial edits, command recovery, streams and installation cooperation.