# Make your first API request

Source: https://www.supervisible.com/developers/api-guide

Create an API key, check its workspace and read your projects.


Use the REST API for scripts and integrations. To connect an assistant instead, [get started with MCP](https://www.supervisible.com/developers/mcp/get-started.md).

## 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:

```bash
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

```bash
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):

```json
{
  "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](https://www.supervisible.com/developers/me/get-me.md).

## Read your projects

```bash
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:

```json
{
  "data": []
}
```

Use the returned project IDs in subsequent requests. Increase `offset` by 20 to read the next page. The [project reference](https://www.supervisible.com/developers/projects/get-projects.md) 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

| Status | Next step                                                             |
| ------ | --------------------------------------------------------------------- |
| 401    | Check that the key is valid and included in the Authorization header. |
| 403    | Check the key's scopes and its creator's current permissions.         |
| 404    | Confirm the record ID and that it belongs to an accessible workspace. |
| 409    | Read the current record and update your request.                      |
| 429    | Wait before retrying; follow Retry-After when supplied.               |

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

## Next steps

Browse the [API reference](https://www.supervisible.com/developers/index.md), download the [OpenAPI document](https://www.supervisible.com/openapi/public-api-v1.json), or use [developer Markdown](https://www.supervisible.com/developers.md). For access rules, see [permissions and data](https://www.supervisible.com/developers/mcp/permissions.md).