API reference | CloudRaker documentation

The CloudRaker API is a thin, multi-tenant gateway. It authenticates your request, resolves it to a single tenant, authorizes the action, and dispatches to the domain services behind it. Every authenticated call is implicitly scoped to the organization that owns your token — you never pass a tenant id yourself.

Base URL

Use the production base for live traffic:

https://api.cloudraker.com

Staging and development have their own bases — see Environments. Ids returned by this API are opaque strings; see Versioning and compatibility for what can change without warning.

Authentication

Every request carries a bearer token in the Authorization header. The developer credential is a organization API key, created in the app under Admin > API keys — see the API keys guide.

An API key is an org-level machine credential: it resolves to your organization and can call any org-wide or admin route. The plaintext value is shown once when you create the key and is never retrievable again — store it somewhere safe. Session JWTs issued by the web app are also accepted, but API keys are the integration story.

API keys carry no per-user membership, so routes gated on a specific person’s fine-grained resource grant can’t be satisfied by a key. Keys are for server-to-server, org-wide automation.

Auth responses

Status	Meaning
`401 unauthorized` / `invalid_token`	Missing, malformed, or invalid token.
`404 org not found`	The token’s identity has no organization.
`503 auth_unavailable`	Transient upstream outage validating the key — retry.

GET /health is the only unauthenticated endpoint you’ll normally touch.

Endpoint groups

Me & home

GET /me, preferences, and the GET /home dashboard for the current user.

Spaces & space-types

Spaces are the primary tenant container; each belongs to a space-type template. List, read, archive spaces and manage types.

Files

Space-scoped storage. Register a file to get a presigned upload URL, upload the bytes, then poll until it’s processed.

Actions & runs

Install actions from the catalog, then dispatch a run in a space and fetch its result, outputs, and audit trail.

Playbooks & runs

Agentic multi-step runs with approvals, a live timeline, run controls, and a WebSocket ticket for streaming.

Objects

Org-level data-object definitions plus space-scoped objects with a 14-operand filter, sort, offset paging, and saved views.

Ontology

Entity/relation knowledge graph — ingest files into namespaces and search entities across a space or the whole org.

GET /spaces/{spaceId}/search — semantic search over a space’s indexed files, returning grounded page/bbox/timecode hits.

Authorization

Check your own permissions, manage grants, and manage groups (teams).

Organization & users

Admin housekeeping — organization details, logo, templates, users, memberships, roles, and API keys.

Process

One-call ingestion: upload files, run actions, and receive signed webhooks in a single multipart request.

How scoping and authorization work

One organization = one tenant. Your token’s org determines which data you reach; there is no cross-tenant access.
Per-resource permissions are enforced at the gateway via fine-grained, per-resource permissions. Missing space:read returns 404 (existence is hidden), missing space:contribute returns 403. Org admins bypass space checks.
Errors are JSON { "error": "<snake_case_code>" }. Pagination is per-group — see each endpoint for its limit/offset/cursor shape.

Building an integration? The Developer guide covers authentication, the file-upload flow, and reacting to events. Browse every endpoint — parameters, schemas, and a runnable example — in the sidebar.