API reference

RunMat Server exposes versioned HTTP APIs for identity context, organizations, projects, files and versions, event streams, packages, usage, and remote execution. The deployment's generated OpenAPI document is authoritative for exact paths and schemas.

Send credentials through the documented authorization header over HTTPS. Resource operations are organization- and project-scoped. Use request or idempotency identifiers for retried mutations where the endpoint supports them, and retain the returned trace identifier when reporting a failure.

Clients must handle structured errors, pagination, rate limits, conditional or version-aware writes, and reconnectable event streams. Machine-readable codes form the stable error contract; human-readable text supports diagnosis. Large objects use the upload-session and commit flow returned by Server.

API compatibility follows the versioned public contract. Internal crate and database changes remain implementation details. Generate clients from the OpenAPI artifact associated with your deployed Server version.

Request conventions

The generated OpenAPI document defines paths, methods, schemas, operation IDs, and security. Send Authorization: Bearer <token-or-api-key>. Preserve or record the response request/trace ID. Use JSON for ordinary control requests and streaming bodies or signed URLs for large content.

List endpoints use explicit pagination. Clients retain the returned cursor and treat display order as presentation state. Conditional or version-aware writes include the current etag or version where required. Mutations that advertise idempotency accept one stable key for the logical attempt, reused across network retries.

Resource groups

• Auth: login resolution, current identity/preferences, API keys, SSO, and SCIM where enabled.
• Organizations/projects: memberships, project lifecycle, roles, and policy context.
• Filesystem/data: metadata, ranged reads, writes, upload sessions, versions, snapshots, storage summaries, and dataset manifests.
• Events: cursor-based Server-Sent Events for project and organization signals.
• Packages: namespace, publication, version, and resolution operations.
• Execution: optional remote targets, run submission/status/cancel, worker coordination, logs, and artifacts.
• Usage/admin: plan-dependent usage, billing, and restricted administrative operations.

Error contract

Errors return a stable code and human message, with validation details and request/trace identity when available. Use the HTTP status and stable code in client logic. Messages can change.

{
  "error": {
    "code": "project_write_conflict",
    "message": "The file changed since the supplied version.",
    "details": { "path": "/analysis.m" },
    "requestId": "req_…"
  }
}

Typical mappings are 400 malformed input, 401 invalid authentication, 403 denied policy, 404 absent scoped resource, 409 version/idempotency conflict, 413 body too large, 422 semantic validation, 429 rate limit, and 5xx server/dependency failure. SSE delivers stream errors as documented event payloads before close when possible.

Client implementation

Generate types from the matching deployment OpenAPI artifact and wrap transport concerns centrally: base URL, bearer credentials, retries, idempotency, pagination, request IDs, and structured errors. Retry connection failures, 429, and selected 5xx responses only when the method and idempotency contract allow it. An ambiguous timeout on an unkeyed mutation requires reconciliation before another attempt.