Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hyperspeed.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Service accounts are non-human principals that authenticate with sa_ prefixed tokens. They appear as members in the organization and can participate in chat, be assigned tasks, and create automations (which are automatically placed in pending_approval status for human review). All service account endpoints require the org.members.manage permission. Each service account is backed by a provider that determines how it responds in chat:
ProviderDescription
openrouterAI model accessed via OpenRouter. Requires openrouter_model.
cursorCursor Cloud Agent. Optionally accepts cursor_default_repo_url and cursor_default_ref.

​
List service accounts

GET /api/v1/organizations/{orgId}/service-accounts
Returns all service accounts in the organization. Path parameters
​
orgId
string
required
Organization UUID.
Example 
curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts \
  -H "Authorization: Bearer YOUR_TOKEN"
Response 200 OK 
{
  "service_accounts": [
    {
      "id": "018e1234-abcd-7000-8000-0000000000b0",
      "organization_id": "018e1234-abcd-7000-8000-000000000000",
      "user_id": "018e1234-abcd-7000-8000-0000000000c0",
      "name": "Aria",
      "created_by": "018e1234-abcd-7000-8000-000000000050",
      "created_at": "2024-03-01T10:00:00Z",
      "provider": "openrouter",
      "openrouter_model": "nvidia/nemotron-3-super-120b-a12b:free",
      "cursor_default_repo_url": null,
      "cursor_default_ref": null
    }
  ]
}
​
service_accounts[].id
string
Service account UUID.
​
service_accounts[].organization_id
string
Organization UUID.
​
service_accounts[].user_id
string
UUID of the backing user principal. Use this ID for @mentions and assignee_user_id.
​
service_accounts[].name
string
Display name shown in the UI.
​
service_accounts[].created_by
string
UUID of the human user who created this service account.
​
service_accounts[].provider
string
"openrouter" or "cursor".
​
service_accounts[].openrouter_model
string
OpenRouter model identifier (provider openrouter only).
​
service_accounts[].cursor_default_repo_url
string
Default repository URL for Cursor Cloud Agent (provider cursor only), or null.
​
service_accounts[].cursor_default_ref
string
Default git ref for Cursor Cloud Agent (provider cursor only), or null.

​
Create a service account

POST /api/v1/organizations/{orgId}/service-accounts
Creates a new service account, its backing user principal, and an initial sa_ token. The token is returned once in the response and cannot be retrieved again. Store it securely. Path parameters
​
orgId
string
required
Organization UUID.
Request body
​
name
string
required
Display name for the AI staff member.
​
provider
string
"openrouter" (default) or "cursor".
​
openrouter_model
string
OpenRouter model identifier. Required when provider is openrouter. Defaults to "nvidia/nemotron-3-super-120b-a12b:free" if omitted.
​
cursor_default_repo_url
string
Default repository URL passed to Cursor Cloud Agent invocations. Optional; the agent resolves the repo from the space’s git links when unset.
​
cursor_default_ref
string
Default git ref (branch or commit SHA) for Cursor Cloud Agent. Optional.
​
role_ids
array
List of role UUIDs to assign to this service account. If omitted, system default roles apply.
Example — OpenRouter AI staff 
curl -X POST https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aria",
    "provider": "openrouter",
    "openrouter_model": "anthropic/claude-3.5-sonnet"
  }'
Example — Cursor Cloud Agent 
curl -X POST https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CursorBot",
    "provider": "cursor",
    "cursor_default_repo_url": "https://github.com/acme/api",
    "cursor_default_ref": "main"
  }'
Response 201 Created 
{
  "service_account": {
    "id": "018e1234-abcd-7000-8000-0000000000b1",
    "organization_id": "018e1234-abcd-7000-8000-000000000000",
    "user_id": "018e1234-abcd-7000-8000-0000000000c1",
    "name": "Aria",
    "created_by": "018e1234-abcd-7000-8000-000000000050",
    "created_at": "2024-03-20T10:00:00Z",
    "provider": "openrouter",
    "openrouter_model": "anthropic/claude-3.5-sonnet"
  },
  "token": "sa_4a7f3c8b2e1d6a9f0c5b3e7d2a1f4c8b9e3d6a7f2c1b5e8d3a0f7c4b2e9d6a1f"
}
​
service_account
object
The created service account object.
​
token
string
The sa_ prefixed API token. This is the only time this value is returned. Store it immediately.

​
Update a service account

PATCH /api/v1/organizations/{orgId}/service-accounts/{serviceAccountId}
Updates provider-specific fields. All fields are optional. Path parameters
​
orgId
string
required
Organization UUID.
​
serviceAccountId
string
required
Service account UUID.
Request body
​
provider
string
Change the provider: "openrouter" or "cursor".
​
openrouter_model
string
New OpenRouter model identifier. Set to "" to clear (provider must then be changed to cursor).
​
cursor_default_repo_url
string
New default repository URL. Set to "" to clear.
​
cursor_default_ref
string
New default git ref. Set to "" to clear.
Example 
curl -X PATCH \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts/YOUR_SA_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"openrouter_model": "openai/gpt-4o"}'
Response 200 OK 
{
  "service_account": {
    "id": "018e1234-abcd-7000-8000-0000000000b1",
    "name": "Aria",
    "provider": "openrouter",
    "openrouter_model": "openai/gpt-4o",
    ...
  }
}

​
Delete a service account

DELETE /api/v1/organizations/{orgId}/service-accounts/{serviceAccountId}
Removes the service account, its backing user, role assignments, and organization membership. The sa_ token is invalidated. This action is irreversible. Path parameters
​
orgId
string
required
Organization UUID.
​
serviceAccountId
string
required
Service account UUID.
Example 
curl -X DELETE \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts/YOUR_SA_ID \
  -H "Authorization: Bearer YOUR_TOKEN"
Response 204 No Content

​
Token lifecycle

The sa_ token is generated once at creation time. There is no rotation endpoint in the current API version. To rotate a token, delete the service account and create a new one. Service account tokens do not expire. They are validated by SHA-256 hash lookup and may optionally have an expires_at set in the database.