Accounts and workspaces

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

These endpoints are served under the public /v1 prefix.

Authentication

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

curl https://api.persistence.dev/v1/workspaces \
  --header "X-API-Key: $PERSISTENCE_API_KEY"

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

Endpoints

List workspaces

GET /v1/workspaces — page through the workspaces the key can access.

Create workspace

POST /v1/workspaces — create a workspace.

Update workspace

PUT /v1/workspaces/{workspaceId} — change a workspace name or scope.

Delete workspace

DELETE /v1/workspaces/{workspaceId} — delete a workspace.

Create API key

POST /v1/{workspaceId}/developer/api-keys — issue a scoped API key.

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.

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.

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.

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

Errors

Errors return a code and an error message.

{
  "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.

API reference

Agents

Calls