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

# Accounts and workspaces

> Manage Persistence workspaces and create the API keys your integrations use.

A workspace is the container for your Persistence resources. Agents, phone numbers, contact lists, and API keys all belong to a workspace. Use these endpoints to manage workspaces and to create the API keys that authenticate the rest of the API.

## Base URL

```
https://api.persistence.dev
```

<Note>
  These endpoints are served under the public `/v1` prefix.
</Note>

## Authentication

Every request requires an existing workspace API key in the `X-API-Key` header.

```bash theme={null}
curl https://api.persistence.dev/v1/workspaces \
  --header "X-API-Key: $PERSISTENCE_API_KEY"
```

<Warning>
  Treat API keys as secrets. Send them only from server-side code and never commit them to source control.
</Warning>

## Endpoints

<CardGroup cols={1}>
  <Card title="List workspaces" icon="list" href="/api-reference/accounts/list-workspaces">
    `GET /v1/workspaces` — page through the workspaces the key can access.
  </Card>

  <Card title="Create workspace" icon="plus" href="/api-reference/accounts/create-workspace">
    `POST /v1/workspaces` — create a workspace.
  </Card>

  <Card title="Update workspace" icon="pencil" href="/api-reference/accounts/update-workspace">
    `PUT /v1/workspaces/{workspaceId}` — change a workspace name or scope.
  </Card>

  <Card title="Delete workspace" icon="trash-2" href="/api-reference/accounts/delete-workspace">
    `DELETE /v1/workspaces/{workspaceId}` — delete a workspace.
  </Card>

  <Card title="Create API key" icon="key" href="/api-reference/accounts/create-api-key">
    `POST /v1/{workspaceId}/developer/api-keys` — issue a scoped API key.
  </Card>
</CardGroup>

## Workspace fields

`POST /v1/workspaces` and `PUT /v1/workspaces/{workspaceId}` accept the same body.

| Field   | Type   | Description      |
| ------- | ------ | ---------------- |
| `name`  | string | Workspace name.  |
| `scope` | string | Workspace scope. |

A workspace returned by the API includes these fields.

| Field   | Type   | Description                                             |
| ------- | ------ | ------------------------------------------------------- |
| `id`    | string | Workspace ID, used as the `workspaceId` path parameter. |
| `name`  | string | Workspace name.                                         |
| `scope` | string | Workspace scope.                                        |
| `path`  | string | Workspace path.                                         |
| `meta`  | object | Additional workspace metadata.                          |

<Note>
  `PUT /v1/workspaces/{workspaceId}` replaces the workspace fields rather than patching individual values. Send the complete set of fields you want the workspace to have.
</Note>

## Pagination and sorting

`GET /v1/workspaces` accepts these query parameters.

| Parameter    | Type    | Description                            |
| ------------ | ------- | -------------------------------------- |
| `page`       | integer | Page number.                           |
| `perPage`    | integer | Items per page.                        |
| `column`     | string  | Sort column. Only `name` is supported. |
| `order`      | string  | Sort order, `asc` or `desc`.           |
| `searchText` | string  | Filter workspaces by text.             |

The response wraps the results in a paged object containing `items`, `page`, `perPage`, `totalCount`, `column`, `order`, and `searchText`.

## API key fields

`POST /v1/{workspaceId}/developer/api-keys` accepts these fields.

| Field            | Type            | Description                                     |
| ---------------- | --------------- | ----------------------------------------------- |
| `name`           | string          | Required. Name for the key.                     |
| `scopes`         | array of string | Required. Permission scopes granted to the key. |
| `description`    | string          | Description of the key.                         |
| `expiresAt`      | string          | Expiry timestamp for the key.                   |
| `revokeExisting` | boolean         | Revoke existing keys when creating this one.    |

The created key is returned with `id`, `name`, `description`, `key`, `scopes`, `status`, `spaceName`, `createdBy`, `createdAt`, `updatedAt`, `expiresAt`, and `lastUsedAt`. The `status` field is either `active` or `revoked`.

<Warning>
  The `key` value is returned only in the creation response. Store it securely at that point, because it cannot be retrieved again.
</Warning>

## Errors

Errors return a `code` and an `error` message.

```json theme={null}
{
  "code": "not_found",
  "error": "workspace not found"
}
```

| Status | Meaning                                                  |
| ------ | -------------------------------------------------------- |
| `400`  | The request body or a path parameter is invalid.         |
| `401`  | The `X-API-Key` header is missing or invalid.            |
| `403`  | The key is not permitted to perform the operation.       |
| `404`  | The workspace does not exist.                            |
| `409`  | The workspace or API key conflicts with an existing one. |