Use the Workspaces API

Send a Workspaces API key as a Bearer token for agent and automation requests. Check the served OpenAPI file before you call a route. Send requests to the instance’s public API origin. Hosted Workspaces and the default container setup use the app origin. A Cloudflare self-hosted deployment uses its separate public API origin, not the Access-protected app origin.

Check supported API routes

Each instance lists its current API routes at:

/v1/openapi.yaml

Use only the routes in that file. Product plans and design files may list routes that the instance does not support.

Check an API key

Set the public API origin. Load the key into WORKSPACES_API_KEY with a secret manager or another method that does not save it in shell history. Then call /v1/me:

export WORKSPACES_ORIGIN="https://your-workspaces-host.example"

curl --fail-with-body \
  --header "Authorization: Bearer ${WORKSPACES_API_KEY}" \
  "${WORKSPACES_ORIGIN}/v1/me"

A valid key returns the owner’s user ID, auth_type: api_key, and current organization memberships. The owner name, email, and provider are null for an API-key request. A missing, malformed, or revoked key returns 401. Do not put a real key in shell history, a ticket, a log, or a document.

Send a request

Follow the method, request body, headers, and response schema in /v1/openapi.yaml. Include these headers when the operation requires them:

Authorization: Bearer <key> authenticates the request.
Content-Type: application/json tells Workspaces that the request body is JSON.
If-Match: <version> prevents a body change, restore, or delete when the document has a newer body version. It does not protect title-only or path-only changes.

Handle common errors

Status	Meaning	Recovery
`400`	The request uses a reserved path or breaks another rule for that operation.	Read the returned error code and correct the request.
`401`	Authentication is missing or invalid.	Check the Bearer header or create a new API key.
`403`	The key can view the resource but cannot make the requested change, or organization billing blocks writes.	Check the key owner’s access and the organization’s plan status.
`404`	The route or resource is unavailable to this key. Workspaces hides private resources from people who cannot view them.	Confirm the route against the served OpenAPI file and check the workspace ID.
`409`	The request conflicts with the current workspace, such as when another file uses the requested path.	Read the current resource, change the request, and try again.
`410`	The operator took down the workspace and purged its content.	Stop retrying and ask the workspace owner or instance operator for help.
`412`	`If-Match` names an older document version.	Read the latest version, apply the intended change to it, and retry with the new version.
`413`	An artifact is larger than 100 MiB, or a personal workspace or organization has reached its artifact quota.	For `artifact_too_large`, publish a smaller file. For `quota_exceeded`, stop retrying: retained history counts, and only a workspace owner permanently deleting a whole workspace frees storage. Do not delete without the owner’s approval.
`422`	The request body or field value is invalid.	Compare the request with the served schema and correct the named fields.
`429`	The instance rate-limited the request.	Wait for the number of seconds in `Retry-After`, then retry.

Create an API key

Create a separate key for each script or agent and revoke it when the tool no longer needs access.

Reviewed July 21, 2026. Maintained by the Plannotator documentation team.

Start

Accounts and organizations

Sharing and access

Documents and collaboration

Agents and developer access

Plans, billing, and seats

Self-hosting and updates

Security and privacy

Troubleshooting

Check supported API routes

Check an API key

Send a request

Handle common errors

Create an API key

​Check supported API routes

​Check an API key

​Send a request

​Handle common errors

Create an API key

Check supported API routes

Check an API key

Send a request

Handle common errors