> ## Documentation Index
> Fetch the complete documentation index at: https://help.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the Workspaces API

> Use a Workspaces API key, check supported routes, and fix common API errors.

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:

```text theme={null}
/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`:

```bash theme={null}
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.                                                                                                                                                                                 |

<Card title="Create an API key" icon="key" href="/workspaces/agents/api-keys" arrow="true">
  Create a separate key for each script or agent and revoke it when the tool no longer needs access.
</Card>

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