Resource API

Configuration is written through the resource API, under https://app.usespotlight.ai/api/resources, or under /api/resources on your deployment's address on a self-hosted Spotlight. The Terraform provider calls the same endpoints. The web app shows configuration read-only.

Request and response bodies are JSON with camelCase field names. Errors are application/problem+json.

CredentialsCopy Anchor Link

A request with neither is refused with 401. See Roles and permissions for what each role and scope allows.

OperationsCopy Anchor Link

Every resource kind has these six operations, except where a rule below says otherwise. <plural> is the kind's collection path, from the endpoint catalogue. <holder> is workspaces/{workspaceId} or teams/{teamId}, depending on what holds the kind.

• A read returns every field, with defaults filled in. Create and update return exactly what a read would.
• An update replaces the whole resource. There is no partial update.
• A list returns { "items": [...] }, each item as a read would return it, in address order. A list of a team-held kind covers every team in the workspace.
• An import returns the resource at an address, as a read would.

HeadersCopy Anchor Link

Common fieldsCopy Anchor Link

Every resource representation has these fields besides its own.

AddressesCopy Anchor Link

ErrorsCopy Anchor Link

An error body has these fields.

permission is one of configure, manage-secrets, manage-runners, manage-token-trusts, administer, open-workspaces or plan.

Error pathsCopy Anchor Link

An error's path names the attribute it is about, as the Terraform provider addresses one. An empty path is about the whole resource.

Paths use the API's camelCase field names.

API versionCopy Anchor Link

The version served is 2026-09-23. Within a version, fields and operations are only added, never removed, renamed or given a new meaning.

Endpoint catalogueCopy Anchor Link

All paths are under /api/resources.

Import is the list path followed by /import, except for workspaces.

Rules particular to a kind:

• workspace and team: see the rules of spotlight_workspace and spotlight_team.
• workspace-token: only a person with the administer permission creates, updates or deletes one. An update changes only its description. A delete revokes it.
• workspace-runners: a workspace has at most one, so its list returns zero or one item.
• replay-candidate: has no update. Proposing and withdrawing one need plan, and only someone who may read the station's team sees one. It is not exported.

Each kind's fields are on its own page:

ExportCopy Anchor Link

Both need only permission to read.

The export's files are ordered by path and are the same on every export:

Workspace tokens are not exported.

The hcl string holds, in order, any variable the resource reads, an import block that adopts it, and the resource. files holds the prompt, rubric and skill files it reads. collection is one of workspaces, teams, lines, skills, harness-profiles, integrations, hooks, secrets, token-trusts, runner-trusts, runner-pools or workspace-runners.

Configuration changesCopy Anchor Link

GET /api/workspaces/{slug}/configuration-changes

Returns every create, update and delete of the workspace's configuration, newest first. Only a person with the administer permission may read it; for anyone else the workspace is 404.

Expression checksCopy Anchor Link

POST /api/expressions/check and GET /api/expressions/positions take the same credentials and return the same problems as the resource API. See Check API.