API reference | CloudRaker documentation

Base URL

Every call goes to the one gateway base:

https://api.cloudraker.com

The API returns opaque string ids. 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 an organization API key. Create the key 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 app shows the plaintext value once, when you create the key. You cannot retrieve it again. Store it in a safe place. The API also accepts session JWTs from the web app, but use API keys for integrations.

API keys carry no per-user membership. A key cannot satisfy a route gated on a specific person’s fine-grained resource grant. Use keys 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`	A transient upstream outage during key validation. Retry.

GET /health is the only unauthenticated endpoint you 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 space belongs to a space-type template. List, read, and archive spaces, and manage types.

Files

Space-scoped storage. Register a file to get a presigned upload URL. Upload the bytes, then poll until the file is 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 runs semantic search over a space’s indexed files. It returns 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.
The gateway enforces fine-grained per-resource permissions. Missing space:read returns 404, which hides existence. 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.

The Developer guide covers authentication, the file-upload flow, and reacting to events. Browse each endpoint in the sidebar, with parameters, schemas, and a runnable example.