Make your first API request

Use the REST API for scripts and integrations. To connect an assistant instead, get started with MCP.

Create an API key

Open Settings → API in Supervisible. Create a key with the read:projects scope for this quickstart.

The key uses its creator's current workspace permissions. Scopes limit what it can do further. Store the key in your secret manager; keep it out of browser code and source control.

Set your key

In your terminal, replace the placeholder with your key:

export SUPERVISIBLE_API_KEY='your-api-key'

Use this variable in the requests below. All requests use the base URL https://app.supervisible.com/api/v1.

Check your workspace

curl --fail-with-body \
  -H "Authorization: Bearer $SUPERVISIBLE_API_KEY" \
  https://app.supervisible.com/api/v1/me

A successful request returns HTTP 200 with your key's identity. For example, the response contains these fields (other fields omitted; IDs are illustrative):

{
  "data": {
    "keyName": "Project reporting",
    "organizationId": "11111111-1111-4111-8111-111111111111",
    "actorUserId": "22222222-2222-4222-8222-222222222222",
    "scopes": ["read:projects"]
  }
}

Check that organizationId and actorUserId identify the workspace and member you intended. The full response also includes the key ID and the member's current permissions. See the identity reference.

Read your projects

curl --fail-with-body \
  -H "Authorization: Bearer $SUPERVISIBLE_API_KEY" \
  'https://app.supervisible.com/api/v1/projects?limit=20&offset=0'

The response contains a data array of accessible projects. If none match, it returns:

{
  "data": []
}

Use the returned project IDs in subsequent requests. Increase offset by 20 to read the next page. The project reference lists response fields and filters for narrowing the results.

Make changes

Each endpoint documents its required scope, request body and response. Read the record first. Where a preview is supported, review the proposed change before applying it. Endpoints without a preview apply changes directly.

After a timeout, read the record again before retrying a write. For imports, check each row's outcome before retrying failed rows.

Resolve an error

The response body provides the error code and message. Revoke unused keys in Settings → API.

Next steps

Browse the API reference, download the OpenAPI document, or use developer Markdown. For access rules, see permissions and data.