Amp External API

The Amp External API allows integrations to interact with Amp workspace data.

All data access is scoped to the Amp workspace that owns the provided client credentials.

If your workspace has a required custom domain, send API requests to https://YOUR_WORKSPACE_DOMAIN/api/v2 instead of https://ampcode.com/api/v2. Use your workspace domain in the request examples below. For Sign in with Amp OAuth, keep resource=https://ampcode.com/api/v2 in the authorization request.

To use this API, create a External API Application in your workspace. Right now, only machine-to-machine applications can be created; Sign in with Amp applications are not generally available.

For integrations and automations using the Amp product itself, use the Amp CLI or Amp SDK instead.

Download OpenAPI JSON

API Base URL

https://ampcode.com/api/v2

If your workspace has a required custom domain, use its API URL instead, for example https://your-workspace.ampcode.app/api/v2.

Threads

APIs for working with Amp threads.

List Threads

GET /threads

List threads from your workspace, with optional filtering and pagination. An M2M client lists all threads of its workspace, including private and group-shared threads. A Sign in with Amp access token lists only the threads its user can see in the application’s workspace, as the Amp app lists them: their own threads, threads shared with the workspace or by link, and threads shared with them or their groups; this is experimental, requires access from the Amp team, and is limited for now to the Amp team’s own project, to `orderBy=updatedAt` with an `updatedAfter` in the last 25 hours, and to listing without `query`. Threads are listed by time of first sync in ascending order for sorting stability, unless `orderBy` says otherwise.

OAuth Scopes

amp.api:workspace.threads.meta:view

Query Parameters

limit

Maximum number of results to return.

Type integer

Default: 50

cursor

Cursor for pagination to get the next set of results.

Type string

query

Search query to filter threads by content. A Sign in with Amp access token needs the 'amp.api:workspace.threads.contents:view' scope to search.

Type string

project

Only include threads in this project. Accepts a project ID (UUID) or namespace/name (case insensitive). The project must belong to the workspace. Returns 400 if the project is not found in the workspace.

Type value

string · uuid

string

after

Only include threads where the thread's initial sync time is after this date (ISO 8601 format). Not allowed with `orderBy=updatedAt`.

Type string · date-time

before

Only include threads where the thread's initial sync time is before this date (ISO 8601 format). Not allowed with `orderBy=updatedAt`.

Type string · date-time

updatedAfter

Only include threads last updated after this date (ISO 8601 format). Requires `orderBy=updatedAt`.

Type string · date-time

orderBy

Which time to list threads by: firstSyncedAt, the initial sync time (default), which keeps pages stable, or updatedAt, the last update time, to find recently active threads. A thread that is updated while you page by updatedAt moves, so it can appear on two pages or on none; dedupe by `id`.

Type string firstSyncedAt | updatedAt

sort

Sort order for results. ASC = oldest first (default), DESC = newest first.

Type string ASC | DESC

visibility

Only include threads with this sharing setting: private (only the creator, plus anyone it is shared with directly), group_shared (shared with groups), workspace_shared (every workspace member), or public_unlisted (anyone with the link). Use workspace_shared to leave out threads that not every member can read.

Type string private | group_shared | workspace_shared | public_unlisted

userEmail

Only include threads created by the user with this email address. The user must be a current workspace member or have created threads in the workspace, such as a former member. Not allowed with a Sign in with Amp access token; use `userID`.

Type string · email

userID

Only include threads created by the user with this user ID. For an M2M client, the user must be a current workspace member or have created threads in the workspace, such as a former member.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/threads?limit=50' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "nextCursor": "string",
  "threads": [
    {
      "id": "string",
      "title": "string",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "firstSyncedAt": "2026-01-01T00:00:00.000Z",
      "creatorUserID": "string",
      "agentState": {
        "state": "working",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "hostname": "string",
      "mainThreadID": "string",
      "parentThreadID": "string",
      "repositories": [
        {
          "url": "string",
          "dir": "string"
        }
      ],
      "labels": [
        "string"
      ]
    }
  ]
}

Responses

200 The request has succeeded.

Response Body

Content Type application/json

Type object

Response model for thread list operations

nextCursor

string

Pagination cursor for getting the next set of results.

threadsREQUIRED

array

Array of threads matching the query

Items

object

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:workspace.threads.contents:view' scope; a personal access token with the 'amp.api:threads:view' scope always gets it.

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

working: the agent is running a turn. idle: the agent finished its turn and waits for the next message. awaiting_approval: the agent waits for a person to approve a tool call. error: the turn stopped on an error; Amp may retry it on its own.

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

Hostname of the machine running a local CLI or runner executor. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:workspace.threads.contents:view' scope; a personal access token with the 'amp.api:threads:view' scope always gets it.

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

ID of the thread whose execution created this thread (for example a child thread spawned by another thread with create_thread, by Puck, or by a plugin). Unset for threads without a parent, and becomes unset if the parent thread is deleted. A creating thread in another workspace is not returned.

repositories

array

Repositories in which this thread started working. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:workspace.threads.contents:view' scope; a personal access token with the 'amp.api:threads:view' scope always gets it.

Items

object

urlREQUIRED

string

The normalized URL to the repository (e.g., https://github.com/owner/repo). Normalization is not guaranteed (e.g., for obscure or ambiguous SSH Git remote URL formats), so you should inspect for outliers.

dir

string

The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository.

labels

array

Normalized label names attached to the thread, sorted alphabetically. An empty array means the thread has no labels. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:workspace.threads.contents:view' scope; a personal access token with the 'amp.api:threads:view' scope always gets it.

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

urlREQUIRED

string

dir

string

The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository.

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

Example

{
  "nextCursor": "string",
  "threads": [
    {
      "id": "string",
      "title": "string",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "firstSyncedAt": "2026-01-01T00:00:00.000Z",
      "creatorUserID": "string",
      "agentState": {
        "state": "working",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "hostname": "string",
      "mainThreadID": "string",
      "parentThreadID": "string",
      "repositories": [
        {
          "url": "string",
          "dir": "string"
        }
      ],
      "labels": [
        "string"
      ]
    }
  ]
}

400 Invalid query parameters

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing scope(s), or a Sign in with Amp application or user without access

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Create Thread

POST /threads

Start a thread in a project and send its first user message. Requires a personal access token with the amp.api:threads:create scope; M2M and Sign in with Amp tokens cannot create threads. The thread is owned by the token owner and runs in an orb as them: the agent uses their access, credentials, and Amp credits, and is not limited to the token's other scopes. The response returns once the thread is accepted; the agent keeps working after it.

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type object

projectREQUIRED

value

Project to start the thread in. Accepts a project ID (UUID) or namespace/name (case insensitive). The token owner must be able to use the project: their own project, or a project of a workspace they belong to. The thread belongs to the project’s workspace, or to no workspace for a personal project.

string · uuid

string

messageREQUIRED

string

Text of the first user message. The agent starts working on it immediately.

agentMode

string

Agent mode key, such as medium. Must be a mode the token owner can use in the project. Omit for the default mode.

title

string

Thread title. Omit to let Amp generate one from the conversation.

labels

array

Labels to attach to the thread, at most 20. Names are lowercased and must be alphanumeric with hyphens.

Items

string

Example

{
  "project": "00000000-0000-4000-8000-000000000000",
  "message": "Update documentation",
  "agentMode": "string",
  "title": "string",
  "labels": [
    "string"
  ]
}

HTTP Request

curl 'https://ampcode.com/api/v2/threads' \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "project": "00000000-0000-4000-8000-000000000000",
  "message": "Update documentation",
  "agentMode": "string",
  "title": "string",
  "labels": [
    "string"
  ]
}'

HTTP Response

201 Content Type application/json

{
  "thread": {
    "id": "string",
    "url": "string",
    "agentMode": "string"
  }
}

Responses

201 Thread created

Response Body

Content Type application/json

Type object

threadREQUIRED

object

idREQUIRED

string

Unique identifier for the thread.

urlREQUIRED

string · uri

URL of the thread in the Amp web app.

agentModeREQUIRED

string

Agent mode key the thread runs.

Example

{
  "thread": {
    "id": "string",
    "url": "string",
    "agentMode": "string"
  }
}

400 Invalid request body, or an agent mode or label that cannot be used

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

402 The token owner is out of credits

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing amp.api:threads:create, or a workspace policy does not let the token start an orb

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Project not found, or the token owner cannot use it

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

429 The token owner created more than 100 threads in the current minute

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

List User Threads

GET /user/threads

List the threads the token owner created, most recently updated first, as the Amp app's sidebar and the CLI list them: their personal threads and their threads in workspaces they still belong to. Archived and empty threads are left out. Requires a personal access token with the amp.api:threads:view scope; M2M clients list a workspace's threads with `GET /api/v2/threads` instead. Threads that others shared with the token owner are not listed, though the token can read them by ID. Pages are offsets into the list at the time of each request, so a thread that is updated while you page can appear on two pages or on none; dedupe by `id`.

Query Parameters

limit

Maximum number of results to return.

Type integer

Default: 50

cursor

Cursor for pagination to get the next set of results.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/user/threads?limit=50' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "nextCursor": "string",
  "threads": [
    {
      "id": "string",
      "title": "string",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "firstSyncedAt": "2026-01-01T00:00:00.000Z",
      "creatorUserID": "string",
      "agentState": {
        "state": "working",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "hostname": "string",
      "mainThreadID": "string",
      "parentThreadID": "string",
      "repositories": [
        {
          "url": "string",
          "dir": "string"
        }
      ],
      "labels": [
        "string"
      ]
    }
  ]
}

Responses

200 The request has succeeded.

Response Body

Content Type application/json

Type object

Response model for thread list operations

nextCursor

string

Pagination cursor for getting the next set of results.

threadsREQUIRED

array

Array of threads matching the query

Items

object

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

urlREQUIRED

string

dir

string

The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository.

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

urlREQUIRED

string

dir

string

The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository.

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

Example

{
  "nextCursor": "string",
  "threads": [
    {
      "id": "string",
      "title": "string",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "firstSyncedAt": "2026-01-01T00:00:00.000Z",
      "creatorUserID": "string",
      "agentState": {
        "state": "working",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "hostname": "string",
      "mainThreadID": "string",
      "parentThreadID": "string",
      "repositories": [
        {
          "url": "string",
          "dir": "string"
        }
      ],
      "labels": [
        "string"
      ]
    }
  ]
}

400 Invalid query parameters

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized, or the credential is not a personal access token

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing amp.api:threads:view

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Delete Threads

DELETE /threads/{threadID}

Delete a thread by ID.

OAuth Scopes

amp.api:workspace.threads:manage

Path Parameters

threadID REQUIRED

ID of the target thread, with the format "T-...".

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/threads/string' \
  --request DELETE \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

Responses

204 Thread successfully deleted

No content

HTTP 204 responses do not include a response body.

400 Invalid thread ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized - authentication required

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Get Threads Metadata

GET /threads/{threadID}/metadata

Get one thread by ID. Returns the same thread object as the thread list, including its creator (`creatorUserID`) and its agent state (`agentState`), which a client can poll to follow a thread it created. An M2M client reads every thread of its workspace, including private and group-shared threads. A personal access token needs the amp.api:threads:view scope instead of the OAuth scopes, and reads the threads its owner sees in their own thread lists: their personal threads and, in workspaces they belong to, their own threads and threads shared with them. For the orb of a self-hosted orb provider, the thread ID is `T-` followed by the UUID in `ORB_ID` (`amp-<uuid>`).

OAuth Scopes

amp.api:workspace.threads.meta:view

Path Parameters

threadID REQUIRED

ID of the target thread, with the format "T-...".

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/threads/string/metadata' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "id": "string",
  "title": "string",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "firstSyncedAt": "2026-01-01T00:00:00.000Z",
  "creatorUserID": "string",
  "agentState": {
    "state": "working",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "hostname": "string",
  "mainThreadID": "string",
  "parentThreadID": "string",
  "repositories": [
    {
      "url": "string",
      "dir": "string"
    }
  ],
  "labels": [
    "string"
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

urlREQUIRED

string

dir

string

The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository.

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

urlREQUIRED

string

dir

string

The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository.

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

urlREQUIRED

string

dir

string

The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository.

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

idREQUIRED

string

Unique identifier for the thread.

title

string

createdAt

string · date-time

When the thread was created.

updatedAt

string · date-time

When the thread was last updated.

firstSyncedAt

string · date-time

When the thread was first synced.

creatorUserIDREQUIRED

string

User ID of the thread creator.

agentState

object

Last state the thread’s agent reported, which can trail the agent by about 10 seconds. Unset until the agent first reports, so a thread just created has none; keep polling until it is set.

stateREQUIRED

string working | idle | awaiting_approval | error

updatedAtREQUIRED

string · date-time

When the agent reported this state.

hostname

string

mainThreadID

string

ID of the main thread, if this is a sub-thread

parentThreadID

string

repositories

array

Items

object

labels

array

Items

string

subThreads

array

Sub-threads belonging to this thread.

Items

v2.Thread

A conversation thread in Amp

Example

{
  "id": "string",
  "title": "string",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "firstSyncedAt": "2026-01-01T00:00:00.000Z",
  "creatorUserID": "string",
  "agentState": {
    "state": "working",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "hostname": "string",
  "mainThreadID": "string",
  "parentThreadID": "string",
  "repositories": [
    {
      "url": "string",
      "dir": "string"
    }
  ],
  "labels": [
    "string"
  ]
}

400 Invalid thread ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Thread not found, or the credential cannot read it

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

List Threads Messages

GET /threads/{threadID}/messages

Get the messages belonging to a thread, oldest first. An M2M client reads the threads of its workspace. A personal access token needs the amp.api:threads:view scope instead of the OAuth scope, and reads the threads its owner sees in their own thread lists.

OAuth Scopes

amp.api:workspace.threads.contents:view

Path Parameters

threadID REQUIRED

ID of the target thread, with the format "T-...".

Type string

Query Parameters

limit

Maximum number of results to return.

Type integer

Default: 50

cursor

Cursor for pagination to get the next set of results.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/threads/string/messages?limit=50' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "nextCursor": "string",
  "messages": [
    null
  ]
}

Responses

200 The request has succeeded.

Response Body

Content Type application/json

Type object

Response model for thread messages operations.

nextCursor

string

Pagination cursor for getting the next set of results.

messagesREQUIRED

array

Array of message objects in the thread. Each message includes a stable messageID, numeric messageVersion, and createdAt timestamp when available. Other message fields are currently not stable and may change at any time. For scanning purposes, we recommend checking the entire content of each message.

Items

value

Example

{
  "nextCursor": "string",
  "messages": [
    null
  ]
}

400 Invalid thread ID or query parameters

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Thread not found, or the credential cannot read it

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Get Threads Usage

GET /threads/{threadID}/usage

Get usage information for a thread. Thread usage data is only available for threads created less than 180 days ago in Enterprise workspaces, or less than 90 days ago in other workspaces.

OAuth Scopes

amp.api:workspace.threads.meta:view

Path Parameters

threadID REQUIRED

ID of the target thread, with the format "T-...".

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/threads/string/usage' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "threadID": "string",
  "subThreadIDs": [
    "string"
  ],
  "usage": 1,
  "orbUsage": 1,
  "toolUsage": 1,
  "estimatedProviderCostAtListPriceUSD": 1,
  "orbs": [
    {
      "size": null,
      "cpuCount": null,
      "memoryMB": null,
      "runtimeMs": 1,
      "usage": 1
    }
  ],
  "tools": [
    {
      "tool": "string",
      "calls": 1,
      "usage": 1
    }
  ],
  "models": [
    {
      "provider": "string",
      "model": "string",
      "requests": 1,
      "inputTokens": 1,
      "outputTokens": 1,
      "cacheReadInputTokens": 1,
      "cacheCreationInputTokens": 1,
      "usage": 1,
      "estimatedProviderCostAtListPriceUSD": 1
    }
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

Thread usage information

threadIDREQUIRED

string

The thread ID

subThreadIDsREQUIRED

array

Always empty. Kept for compatibility; usage covers only this thread.

Items

string

usageREQUIRED

number

Total thread cost in USD over the thread's whole life, including orb and tool usage. Counts usage paid with any credits, including free or promotional credits and subscriptions, but not the free tier.

orbUsageREQUIRED

number

Orb usage of the thread (USD). Included in usage; not included in models.

toolUsageREQUIRED

number

Tool usage of the thread (USD). Included in usage; not included in models.

estimatedProviderCostAtListPriceUSDREQUIRED

number

EXPERIMENTAL. Estimated USD cost of bring-your-own-key (BYOK) inference in this thread, computed from token usage at the model provider’s public list price at the time of the request. This is what the customer would have paid the provider (for example Anthropic or OpenAI) at list price; it is not billed by Amp and is not included in the usage field. This is only an estimate. Amp cannot see negotiated pricing, discounts, committed-use contracts, or free-tier allowances a customer has with a provider, and the estimate does not include markups or fees charged by AI routers or gateways. Requests sent through an AI router connection (for example OpenRouter) are not estimated at all and contribute 0, because Amp has no list price for router-served models. Requests served through subscription connections (such as ChatGPT or Claude subscriptions) are excluded because they have no per-token provider bill. Requests made before 2026-08-26 are not included. Contact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice.

orbsREQUIRED

array

Orb runtime and usage of the thread by orb size, largest usage first

Items

object

Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total.

sizeREQUIRED

string,null

Orb size, such as "a1.medium", or null when the CPU and memory match no current orb size

cpuCountREQUIRED

number,null

vCPUs of the orb, or null if unknown

memoryMBREQUIRED

number,null

Memory of the orb in MB, or null if unknown

runtimeMsREQUIRED

number

Billed orb runtime in milliseconds, whichever credits paid for it. Runtime paid for by credits that the enclosing usage total excludes, such as personal subscriptions, counts here but not in usage.

usageREQUIRED

number

Orb usage (USD), counted the same way as the enclosing usage total

toolsREQUIRED

array

Tool calls and usage of the thread by tool, largest usage first

Items

object

Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total.

toolREQUIRED

string

Tool name, such as "web_search" or "read_web_page"

callsREQUIRED

number

Number of charged calls, whichever credits paid for them, including calls that cost nothing

usageREQUIRED

number

Tool usage (USD), counted the same way as the enclosing usage total

modelsREQUIRED

array

Per-model usage and cost breakdown for the thread

Items

object

providerREQUIRED

string

Provider identifier for the model usage bucket

modelREQUIRED

string

Model identifier for the model usage bucket

requestsREQUIRED

number

Number of requests for this provider/model

inputTokensREQUIRED

number

Total uncached input tokens for this provider/model

outputTokensREQUIRED

number

Total output tokens for this provider/model

cacheReadInputTokensREQUIRED

number

Total cache-read input tokens for this provider/model

cacheCreationInputTokensREQUIRED

number

Total cache-creation input tokens for this provider/model

usageREQUIRED

number

Total cost in USD for this provider/model

estimatedProviderCostAtListPriceUSDREQUIRED

number

EXPERIMENTAL. Estimated USD cost of bring-your-own-key (BYOK) inference for this provider/model, computed from token usage at the model provider’s public list price at the time of the request. This is what the customer would have paid the provider (for example Anthropic or OpenAI) at list price; it is not billed by Amp and is not included in the usage field. This is only an estimate. Amp cannot see negotiated pricing, discounts, committed-use contracts, or free-tier allowances a customer has with a provider, and the estimate does not include markups or fees charged by AI routers or gateways. Requests sent through an AI router connection (for example OpenRouter) are not estimated at all and contribute 0, because Amp has no list price for router-served models. Requests served through subscription connections (such as ChatGPT or Claude subscriptions) are excluded because they have no per-token provider bill. Requests made before 2026-08-26 are not included. Contact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice.

Example

{
  "threadID": "string",
  "subThreadIDs": [
    "string"
  ],
  "usage": 1,
  "orbUsage": 1,
  "toolUsage": 1,
  "estimatedProviderCostAtListPriceUSD": 1,
  "orbs": [
    {
      "size": null,
      "cpuCount": null,
      "memoryMB": null,
      "runtimeMs": 1,
      "usage": 1
    }
  ],
  "tools": [
    {
      "tool": "string",
      "calls": 1,
      "usage": 1
    }
  ],
  "models": [
    {
      "provider": "string",
      "model": "string",
      "requests": 1,
      "inputTokens": 1,
      "outputTokens": 1,
      "cacheReadInputTokens": 1,
      "cacheCreationInputTokens": 1,
      "usage": 1,
      "estimatedProviderCostAtListPriceUSD": 1
    }
  ]
}

400 Invalid thread ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Thread not found or usage data not available

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Workspace

APIs for workspace-level resources such as members.

List Workspace Members

GET /workspace/members

List all members in the workspace. A Sign in with Amp user sees the member list only when they are a workspace member and the workspace allows members to view the member list.

OAuth Scopes

amp.api:workspace.members:view

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/members' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "members": [
    {
      "id": "string",
      "name": "Example",
      "email": "author@example.com",
      "role": "admin",
      "avatarURL": null
    }
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

Response for workspace members listing

membersREQUIRED

array

All members of the workspace

Items

object

idREQUIRED

string

Unique identifier of the user

nameREQUIRED

string

Full name of the user

emailREQUIRED

string · email

The primary email address of the user

roleREQUIRED

string admin | member

Workspace-level role of the user

avatarURLREQUIRED

string,null · uri

Absolute URL of the user’s profile picture, publicly fetchable without credentials, or null when the user has none

Example

{
  "members": [
    {
      "id": "string",
      "name": "Example",
      "email": "author@example.com",
      "role": "admin",
      "avatarURL": null
    }
  ]
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing scope(s), or the user may not view the member list of this workspace

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Projects

APIs for listing Amp projects.

List Projects

GET /workspace/projects

List projects owned by the workspace selected by the access token. User-owned projects and projects from other workspaces are not included.

OAuth Scopes

amp.api:workspace.projects:view

Query Parameters

limit

Maximum number of results to return.

Type integer

Default: 50

cursor

Cursor for pagination to get the next set of results.

Type string

name

Case-insensitive exact project name to return.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/projects?limit=50' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "nextCursor": "string",
  "projects": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "namespace": "string",
      "owner": {
        "type": "workspace",
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "Example"
      },
      "repository": {
        "mode": "amp-hosted",
        "url": null
      }
    }
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

nextCursor

string

Pagination cursor for getting the next set of results.

projectsREQUIRED

array

Projects owned by the workspace.

Items

object

idREQUIRED

string · uuid

Unique identifier of the project.

nameREQUIRED

string

Project name.

namespaceREQUIRED

string

Project namespace.

ownerREQUIRED

object

typeREQUIRED

string workspace

idREQUIRED

string · uuid

Unique identifier of the workspace that owns the project.

nameREQUIRED

string

Name of the workspace that owns the project.

repositoryREQUIRED

object

modeREQUIRED

string amp-hosted | github | mapped

How Amp connects to or hosts the project repository.

urlREQUIRED

string,null · uri

Credential-free repository URL, or null when no safe public URL is available.

Example

{
  "nextCursor": "string",
  "projects": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "namespace": "string",
      "owner": {
        "type": "workspace",
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "Example"
      },
      "repository": {
        "mode": "amp-hosted",
        "url": null
      }
    }
  ]
}

400 Invalid query parameters

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing token scope or project permission

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

List Workspace Projects

GET /workspaces/{workspaceID}/projects

List projects owned by an explicitly selected workspace. The selector must match the workspace selected by the access token.

OAuth Scopes

amp.api:workspace.projects:view

Path Parameters

workspaceID REQUIRED

ID of the target workspace.

Type string · uuid

Query Parameters

limit

Maximum number of results to return.

Type integer

Default: 50

cursor

Cursor for pagination to get the next set of results.

Type string

name

Case-insensitive exact project name to return.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/workspaces/00000000-0000-4000-8000-000000000000/projects?limit=50' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "nextCursor": "string",
  "projects": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "namespace": "string",
      "owner": {
        "type": "workspace",
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "Example"
      },
      "repository": {
        "mode": "amp-hosted",
        "url": null
      }
    }
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

nextCursor

string

Pagination cursor for getting the next set of results.

projectsREQUIRED

array

Projects owned by the workspace.

Items

object

idREQUIRED

string · uuid

Unique identifier of the project.

nameREQUIRED

string

Project name.

namespaceREQUIRED

string

Project namespace.

ownerREQUIRED

object

typeREQUIRED

string workspace

idREQUIRED

string · uuid

Unique identifier of the workspace that owns the project.

nameREQUIRED

string

Name of the workspace that owns the project.

repositoryREQUIRED

object

modeREQUIRED

string amp-hosted | github | mapped

How Amp connects to or hosts the project repository.

urlREQUIRED

string,null · uri

Credential-free repository URL, or null when no safe public URL is available.

Example

{
  "nextCursor": "string",
  "projects": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "namespace": "string",
      "owner": {
        "type": "workspace",
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "Example"
      },
      "repository": {
        "mode": "amp-hosted",
        "url": null
      }
    }
  ]
}

400 Invalid workspace ID or query parameters

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing token scope or project permission

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Search Repository Commits

GET /workspace/projects/{project}/repository/commits/search

Search commit messages and author names without case sensitivity in history order. At most 2,000 commits are scanned per request; path filters history. Continue with nextCursor to scan further. Cursor pagination pins an immutable commit and binds project and query. Requires current repository access for delegated users, or a workspace-owned repository for M2M clients.

OAuth Scopes

amp.api:workspace.projects:viewamp.git:read

Path Parameters

project REQUIRED

Project ID or @namespace/name. The @ is required.

Type string

Examples "00000000-0000-4000-8000-000000000000""@my-workspace/my-project"

Query Parameters

ref REQUIRED

Branch, tag, or commit; resolved to a commit before searching.

Type string

q REQUIRED

Substring for commits, regex for content, glob for paths.

Type string

path

Repository-relative path prefix.

Type string

limit

Type integer

Default: 25

cursor

Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/projects/00000000-0000-4000-8000-000000000000/repository/commits/search?ref=main&q=string&limit=25' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

# Or use @namespace/name

curl 'https://ampcode.com/api/v2/workspace/projects/@my-workspace/my-project/repository/commits/search?ref=main&q=string&limit=25' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "commit": "string",
  "nextCursor": "string",
  "incomplete": true,
  "matches": [
    {
      "id": "string",
      "message": "Update documentation",
      "authorName": "string",
      "authorEmail": "string",
      "committerName": "string",
      "committerEmail": "string",
      "createdAt": "string"
    }
  ]
}

Responses

200 Search results

Response Body

Content Type application/json

Type object

commitREQUIRED

string

nextCursor

string

incompleteREQUIRED

boolean

matchesREQUIRED

array

Items

object

idREQUIRED

string

messageREQUIRED

string

authorNameREQUIRED

string

authorEmailREQUIRED

string

committerNameREQUIRED

string

committerEmailREQUIRED

string

createdAtREQUIRED

string

Example

{
  "commit": "string",
  "nextCursor": "string",
  "incomplete": true,
  "matches": [
    {
      "id": "string",
      "message": "Update documentation",
      "authorName": "string",
      "authorEmail": "string",
      "committerName": "string",
      "committerEmail": "string",
      "createdAt": "string"
    }
  ]
}

400 Invalid query or cursor

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Missing scope, grant, or repository permission

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Project or ref not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

422 A repository path exceeds the matching work limit

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

502 Repository pagination unavailable

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Search Repository Content

GET /workspace/projects/{project}/repository/content/search

Search repository contents using a regular expression. Maximum 500 collected lines and 50 matches per file. Results can be incomplete even when no next page is available; incomplete is always true. Cursor pagination pins an immutable commit and binds project and query. Requires current repository access for delegated users, or a workspace-owned repository for M2M clients.

OAuth Scopes

amp.api:workspace.projects:viewamp.git:read

Path Parameters

project REQUIRED

Project ID or @namespace/name. The @ is required.

Type string

Examples "00000000-0000-4000-8000-000000000000""@my-workspace/my-project"

Query Parameters

ref REQUIRED

Branch, tag, or commit; resolved to a commit before searching.

Type string

q REQUIRED

Substring for commits, regex for content, glob for paths.

Type string

path

Repository-relative path prefix.

Type string

limit

Type integer

Default: 25

cursor

Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.

Type string

caseSensitive

Type string true | false

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/projects/00000000-0000-4000-8000-000000000000/repository/content/search?ref=main&q=string&limit=25' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

# Or use @namespace/name

curl 'https://ampcode.com/api/v2/workspace/projects/@my-workspace/my-project/repository/content/search?ref=main&q=string&limit=25' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "commit": "string",
  "nextCursor": "string",
  "incomplete": true,
  "matches": [
    {
      "path": "README.md",
      "lines": [
        {
          "lineNumber": 1,
          "text": "string",
          "type": "string"
        }
      ]
    }
  ],
  "hasMore": true
}

Responses

200 Search results

Response Body

Content Type application/json

Type object

commitREQUIRED

string

nextCursor

string

incompleteREQUIRED

boolean

matchesREQUIRED

array

Items

object

pathREQUIRED

string

linesREQUIRED

array

Items

object

lineNumberREQUIRED

number

textREQUIRED

string

typeREQUIRED

string

hasMoreREQUIRED

boolean

Example

{
  "commit": "string",
  "nextCursor": "string",
  "incomplete": true,
  "matches": [
    {
      "path": "README.md",
      "lines": [
        {
          "lineNumber": 1,
          "text": "string",
          "type": "string"
        }
      ]
    }
  ],
  "hasMore": true
}

400 Invalid query or cursor

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Missing scope, grant, or repository permission

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Project or ref not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

422 A repository path exceeds the matching work limit

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

502 Repository pagination unavailable

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Search Repository Paths

GET /workspace/projects/{project}/repository/paths/search

Search repository-relative file paths with case-sensitive matching. Glob syntax: * and ? within one segment, ** across segments; no braces or character classes. At most 20,000 entries or 2,000,000 pattern-character comparisons are scanned per request; continue with nextCursor to scan further. A single path exceeding the comparison budget returns 422. Cursor pagination pins an immutable commit and binds project and query. Requires current repository access for delegated users, or a workspace-owned repository for M2M clients.

OAuth Scopes

amp.api:workspace.projects:viewamp.git:read

Path Parameters

project REQUIRED

Project ID or @namespace/name. The @ is required.

Type string

Examples "00000000-0000-4000-8000-000000000000""@my-workspace/my-project"

Query Parameters

ref REQUIRED

Branch, tag, or commit; resolved to a commit before searching.

Type string

q REQUIRED

Substring for commits, regex for content, glob for paths.

Type string

path

Repository-relative path prefix.

Type string

limit

Type integer

Default: 25

cursor

Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/projects/00000000-0000-4000-8000-000000000000/repository/paths/search?ref=main&q=string&limit=25' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

# Or use @namespace/name

curl 'https://ampcode.com/api/v2/workspace/projects/@my-workspace/my-project/repository/paths/search?ref=main&q=string&limit=25' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "commit": "string",
  "nextCursor": "string",
  "incomplete": true,
  "matches": [
    {
      "path": "README.md",
      "type": "string",
      "mode": "string"
    }
  ]
}

Responses

200 Search results

Response Body

Content Type application/json

Type object

commitREQUIRED

string

nextCursor

string

incompleteREQUIRED

boolean

matchesREQUIRED

array

Items

object

pathREQUIRED

string

typeREQUIRED

string

modeREQUIRED

string

Example

{
  "commit": "string",
  "nextCursor": "string",
  "incomplete": true,
  "matches": [
    {
      "path": "README.md",
      "type": "string",
      "mode": "string"
    }
  ]
}

400 Invalid query or cursor

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Missing scope, grant, or repository permission

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Project or ref not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

422 A repository path exceeds the matching work limit

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

502 Repository pagination unavailable

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Compare Repository Commits

GET /workspace/projects/{project}/repository/diff

Compare a commit to its parent, or compare it against the merge base of an explicit base. All patches and filtered-file records returned by storage are included without additional truncation. Files over 500 KB, files with over 2,000 changed lines, binary files, and lock files have no inline patch. Check filteredFiles and incomplete for omitted patches.

OAuth Scopes

amp.api:workspace.projects:viewamp.git:read

Path Parameters

project REQUIRED

Project ID or @namespace/name. The @ is required.

Type string

Examples "00000000-0000-4000-8000-000000000000""@my-workspace/my-project"

Query Parameters

ref REQUIRED

Commit, branch, or tag to compare.

Type string

base

Optional base; comparison uses merge-base semantics.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/projects/00000000-0000-4000-8000-000000000000/repository/diff?ref=main' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

# Or use @namespace/name

curl 'https://ampcode.com/api/v2/workspace/projects/@my-workspace/my-project/repository/diff?ref=main' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "commit": "string",
  "base": null,
  "comparison": "merge-base",
  "files": [
    {
      "path": "README.md",
      "oldPath": "string",
      "state": "string",
      "additions": 1,
      "deletions": 1,
      "patch": "string"
    }
  ],
  "filteredFiles": [
    {
      "path": "README.md",
      "oldPath": "string",
      "state": "string",
      "rawState": "string",
      "bytes": 1,
      "isEof": true
    }
  ],
  "incomplete": true
}

Responses

200 Diff

Response Body

Content Type application/json

Type object

commitREQUIRED

string

baseREQUIRED

string,null

comparisonREQUIRED

string merge-base | parent

filesREQUIRED

array

Items

object

pathREQUIRED

string

oldPath

string

stateREQUIRED

string

additionsREQUIRED

number

deletionsREQUIRED

number

patchREQUIRED

string

filteredFilesREQUIRED

array

Items

object

pathREQUIRED

string

oldPath

string

stateREQUIRED

string

rawStateREQUIRED

string

bytesREQUIRED

number

isEofREQUIRED

boolean

incompleteREQUIRED

boolean

True when filteredFiles contains changed files without patches.

Example

{
  "commit": "string",
  "base": null,
  "comparison": "merge-base",
  "files": [
    {
      "path": "README.md",
      "oldPath": "string",
      "state": "string",
      "additions": 1,
      "deletions": 1,
      "patch": "string"
    }
  ],
  "filteredFiles": [
    {
      "path": "README.md",
      "oldPath": "string",
      "state": "string",
      "rawState": "string",
      "bytes": 1,
      "isEof": true
    }
  ],
  "incomplete": true
}

400 Invalid query

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Missing scope, grant, or repository permission

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Project or ref not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

List Repository Root

GET /workspace/projects/{project}/repository/contents

Read a file (base64, at most 1 MiB), or list a directory with stable pagination. Path is repository-relative and can span multiple URL segments. Set recursive=true to list the full subtree. Cursors bind the project, path, options, and immutable commit.

OAuth Scopes

amp.api:workspace.projects:viewamp.git:read

Path Parameters

project REQUIRED

Project ID or @namespace/name. The @ is required.

Type string

Examples "00000000-0000-4000-8000-000000000000""@my-workspace/my-project"

Query Parameters

ref REQUIRED

Branch, tag, or commit; resolved to a commit before reading.

Type string

recursive

List all descendants instead of direct children.

Type string true | false

Default: "false"

limit

Type integer

Default: 100

cursor

Opaque continuation cursor. Keep the same project, path, and query. Cursors remain bound to the client. Every request must independently authorize access.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/projects/00000000-0000-4000-8000-000000000000/repository/contents?ref=main&recursive=false&limit=100' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

# Or use @namespace/name

curl 'https://ampcode.com/api/v2/workspace/projects/@my-workspace/my-project/repository/contents?ref=main&recursive=false&limit=100' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "kind": "file",
  "commit": "string",
  "path": "README.md",
  "encoding": "base64",
  "content": "SGVsbG8sIHdvcmxkIQo=",
  "size": 1
}

Responses

200 File or directory contents

Response Body

Content Type application/json

Type value

object

kindREQUIRED

string file

commitREQUIRED

string

pathREQUIRED

string

encodingREQUIRED

string base64

contentREQUIRED

string

sizeREQUIRED

number

object

kindREQUIRED

string directory

commitREQUIRED

string

entriesREQUIRED

array

Items

object

pathREQUIRED

string

typeREQUIRED

string

modeREQUIRED

string

nextCursor

string

Example

{
  "kind": "file",
  "commit": "string",
  "path": "README.md",
  "encoding": "base64",
  "content": "SGVsbG8sIHdvcmxkIQo=",
  "size": 1
}

400 Invalid query, path, or cursor

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Missing scope, grant, or repository permission

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Project, ref, or path not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

413 File exceeds 1 MiB

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

502 Repository pagination unavailable

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Get Repository Contents

GET /workspace/projects/{project}/repository/contents/{path}

OAuth Scopes

amp.api:workspace.projects:viewamp.git:read

Path Parameters

project REQUIRED

Project ID or @namespace/name. The @ is required.

Type string

Examples "00000000-0000-4000-8000-000000000000""@my-workspace/my-project"

path REQUIRED

Type string

Query Parameters

ref REQUIRED

Branch, tag, or commit; resolved to a commit before reading.

Type string

recursive

List all descendants instead of direct children.

Type string true | false

Default: "false"

limit

Type integer

Default: 100

cursor

Opaque continuation cursor. Keep the same project, path, and query. Cursors remain bound to the client. Every request must independently authorize access.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/projects/00000000-0000-4000-8000-000000000000/repository/contents/README.md?ref=main&recursive=false&limit=100' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

# Or use @namespace/name

curl 'https://ampcode.com/api/v2/workspace/projects/@my-workspace/my-project/repository/contents/README.md?ref=main&recursive=false&limit=100' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "kind": "file",
  "commit": "string",
  "path": "README.md",
  "encoding": "base64",
  "content": "SGVsbG8sIHdvcmxkIQo=",
  "size": 1
}

Responses

200 File or directory contents

Response Body

Content Type application/json

Type value

object

kindREQUIRED

string file

commitREQUIRED

string

pathREQUIRED

string

encodingREQUIRED

string base64

contentREQUIRED

string

sizeREQUIRED

number

object

kindREQUIRED

string directory

commitREQUIRED

string

entriesREQUIRED

array

Items

object

pathREQUIRED

string

typeREQUIRED

string

modeREQUIRED

string

nextCursor

string

Example

{
  "kind": "file",
  "commit": "string",
  "path": "README.md",
  "encoding": "base64",
  "content": "SGVsbG8sIHdvcmxkIQo=",
  "size": 1
}

400 Invalid query, path, or cursor

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Missing scope, grant, or repository permission

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Project, ref, or path not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

413 File exceeds 1 MiB

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

502 Repository pagination unavailable

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Groups

APIs for managing workspace groups.

List Workspace Groups

GET /workspace/groups

List all workspace groups and their members.

OAuth Scopes

amp.api:workspace.groups:view

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/groups' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "groups": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "members": [
        {
          "userID": "string",
          "role": "captain",
          "name": "Example",
          "email": "author@example.com"
        }
      ]
    }
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

groupsREQUIRED

array

All groups in the workspace.

Items

object

idREQUIRED

string · uuid

Unique identifier for the workspace group.

nameREQUIRED

string

Workspace group name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

membersREQUIRED

array

Members assigned to the workspace group.

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

name

string

Full name of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

email

string · email

Primary email address of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

Example

{
  "groups": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "members": [
        {
          "userID": "string",
          "role": "captain",
          "name": "Example",
          "email": "author@example.com"
        }
      ]
    }
  ]
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Create Workspace Groups

POST /workspace/groups

Create a workspace group. Initial members are removed from any other workspace group.

OAuth Scopes

amp.api:workspace.groups:manage

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type object

nameREQUIRED

string

Workspace group name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

members

array

Initial group members. Listed users are removed from any other workspace group.

Default: []

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

Example

{
  "name": "Example",
  "members": []
}

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/groups' \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "members": []
}'

HTTP Response

201 Content Type application/json

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

Responses

201 Workspace group created

Response Body

Content Type application/json

Type object

groupREQUIRED

object

Workspace group.

idREQUIRED

string · uuid

Unique identifier for the workspace group.

nameREQUIRED

string

Workspace group name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

membersREQUIRED

array

Members assigned to the workspace group.

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

name

string

Full name of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

email

string · email

Primary email address of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

Example

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

400 Invalid request body

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

409 Workspace group name already exists

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Get Workspace Groups

GET /workspace/groups/{groupID}

Get one workspace group and its members.

OAuth Scopes

amp.api:workspace.groups:view

Path Parameters

groupID REQUIRED

ID of the target workspace group.

Type string · uuid

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/groups/00000000-0000-4000-8000-000000000000' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

Responses

200 Success

Response Body

Content Type application/json

Type object

groupREQUIRED

object

Workspace group.

idREQUIRED

string · uuid

Unique identifier for the workspace group.

nameREQUIRED

string

Workspace group name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

membersREQUIRED

array

Members assigned to the workspace group.

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

name

string

Full name of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

email

string · email

Primary email address of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

Example

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

400 Invalid group ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace group not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Update Workspace Groups

PATCH /workspace/groups/{groupID}

Update workspace group metadata.

OAuth Scopes

amp.api:workspace.groups:manage

Path Parameters

groupID REQUIRED

ID of the target workspace group.

Type string · uuid

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type object

nameREQUIRED

string

Workspace group name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

Example

{
  "name": "Example"
}

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/groups/00000000-0000-4000-8000-000000000000' \
  --request PATCH \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example"
}'

HTTP Response

200 Content Type application/json

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

Responses

200 Workspace group updated

Response Body

Content Type application/json

Type object

groupREQUIRED

object

Workspace group.

idREQUIRED

string · uuid

Unique identifier for the workspace group.

nameREQUIRED

string

Workspace group name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

membersREQUIRED

array

Members assigned to the workspace group.

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

name

string

Full name of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

email

string · email

Primary email address of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

Example

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

400 Invalid request body or group ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace group not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

409 Workspace group name already exists

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Delete Workspace Groups

DELETE /workspace/groups/{groupID}

Delete a workspace group. This removes group memberships and may affect group-based entitlements and group-shared private threads.

OAuth Scopes

amp.api:workspace.groups:manage

Path Parameters

groupID REQUIRED

ID of the target workspace group.

Type string · uuid

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/groups/00000000-0000-4000-8000-000000000000' \
  --request DELETE \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

Responses

204 Workspace group deleted

No content

HTTP 204 responses do not include a response body.

400 Invalid group ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace group not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Replace Workspace Groups Members

PUT /workspace/groups/{groupID}/members

Replace a workspace group membership list. After this request succeeds, this group has exactly the listed members; omitted users are removed from this group, and listed users are removed from any other workspace group.

OAuth Scopes

amp.api:workspace.groups:manage

Path Parameters

groupID REQUIRED

ID of the target workspace group.

Type string · uuid

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type object

membersREQUIRED

array

Full replacement membership list. After the request succeeds, this group has exactly these members, and listed users are removed from any other workspace group.

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

Example

{
  "members": [
    {
      "userID": "string",
      "role": "captain"
    }
  ]
}

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/groups/00000000-0000-4000-8000-000000000000/members' \
  --request PUT \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "members": [
    {
      "userID": "string",
      "role": "captain"
    }
  ]
}'

HTTP Response

200 Content Type application/json

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

Responses

200 Workspace group members replaced

Response Body

Content Type application/json

Type object

groupREQUIRED

object

Workspace group.

idREQUIRED

string · uuid

Unique identifier for the workspace group.

nameREQUIRED

string

Workspace group name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

membersREQUIRED

array

Members assigned to the workspace group.

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

name

string

Full name of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

email

string · email

Primary email address of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

Example

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

400 Invalid request body or group ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace group not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Add Workspace Groups Members

POST /workspace/groups/{groupID}/members

Add, move, or update roles for members in a workspace group. Existing group members not listed remain assigned to this group, and listed users are removed from any other workspace group.

OAuth Scopes

amp.api:workspace.groups:manage

Path Parameters

groupID REQUIRED

ID of the target workspace group.

Type string · uuid

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type object

membersREQUIRED

array

Members whose group assignment or role should be updated. Existing group members not listed remain assigned to this group, and listed users are added to this group and removed from any other workspace group.

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

Example

{
  "members": [
    {
      "userID": "string",
      "role": "captain"
    }
  ]
}

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/groups/00000000-0000-4000-8000-000000000000/members' \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "members": [
    {
      "userID": "string",
      "role": "captain"
    }
  ]
}'

HTTP Response

200 Content Type application/json

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

Responses

200 Workspace group members added, moved, or updated

Response Body

Content Type application/json

Type object

groupREQUIRED

object

Workspace group.

idREQUIRED

string · uuid

Unique identifier for the workspace group.

nameREQUIRED

string

Workspace group name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

membersREQUIRED

array

Members assigned to the workspace group.

Items

object

userIDREQUIRED

string

Workspace member user ID.

roleREQUIRED

string captain | member

Role of the user in the workspace group. Captains can manage their group.

name

string

Full name of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

email

string · email

Primary email address of the user. Only returned if the client has the "amp.api:workspace.members:view" scope.

Example

{
  "group": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "members": [
      {
        "userID": "string",
        "role": "captain",
        "name": "Example",
        "email": "author@example.com"
      }
    ]
  }
}

400 Invalid request body or group ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace group not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Entitlements

APIs for managing workspace entitlements.

List Workspace Entitlements

GET /workspace/entitlements

List all workspace entitlements.

OAuth Scopes

amp.api:workspace.entitlements:view

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/entitlements' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "entitlements": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "type": "paid_credits",
      "usageLimitUSD": 1,
      "windowDays": 1,
      "assignment": {
        "type": "default"
      }
    }
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

entitlementsREQUIRED

array

All workspace entitlements.

Items

object

idREQUIRED

string · uuid

Unique identifier for the workspace entitlement.

nameREQUIRED

string

Workspace entitlement name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

typeREQUIRED

string paid_credits

Resource type limited by this entitlement.

usageLimitUSDREQUIRED

integer

Dollar-denominated credit cap in whole US dollars.

windowDaysREQUIRED

value

Fixed quota window in days. Supported values are 1, 7, and 30.

number 1

number 7

number 30

assignmentREQUIRED

one of

Who receives this entitlement.

object

typeREQUIRED

string default

Apply this entitlement to workspace members without a more specific entitlement.

object

typeREQUIRED

string users

userIDsREQUIRED

array

Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments.

Items

string

Workspace member user ID.

object

typeREQUIRED

string workspace_groups

workspaceGroupIDsREQUIRED

array

Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments.

Items

string · uuid

Workspace group ID.

object

typeREQUIRED

string unmanaged

This entitlement uses an assignment mechanism not managed by this API.

Example

{
  "entitlements": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "type": "paid_credits",
      "usageLimitUSD": 1,
      "windowDays": 1,
      "assignment": {
        "type": "default"
      }
    }
  ]
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Create Workspace Entitlements

POST /workspace/entitlements

Create a workspace entitlement for dollar-denominated credit caps. Assignments can target default workspace members, direct users, or workspace groups.

OAuth Scopes

amp.api:workspace.entitlements:manage

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type object

nameREQUIRED

string

Workspace entitlement name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

usageLimitUSDREQUIRED

integer

Dollar-denominated credit cap in whole US dollars.

windowDaysREQUIRED

value

Fixed quota window in days. Supported values are 1, 7, and 30.

number 1

number 7

number 30

assignmentREQUIRED

one of

Who receives this entitlement.

object

typeREQUIRED

string default

Apply this entitlement to workspace members without a more specific entitlement.

object

typeREQUIRED

string users

userIDsREQUIRED

array

Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments.

Items

string

Workspace member user ID.

object

typeREQUIRED

string workspace_groups

workspaceGroupIDsREQUIRED

array

Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments.

Items

string · uuid

Workspace group ID.

Example

{
  "name": "Example",
  "usageLimitUSD": 1,
  "windowDays": 1,
  "assignment": {
    "type": "default"
  }
}

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/entitlements' \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "usageLimitUSD": 1,
  "windowDays": 1,
  "assignment": {
    "type": "default"
  }
}'

HTTP Response

201 Content Type application/json

{
  "entitlement": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "type": "paid_credits",
    "usageLimitUSD": 1,
    "windowDays": 1,
    "assignment": {
      "type": "default"
    }
  }
}

Responses

201 Workspace entitlement created

Response Body

Content Type application/json

Type object

entitlementREQUIRED

object

Workspace entitlement.

idREQUIRED

string · uuid

Unique identifier for the workspace entitlement.

nameREQUIRED

string

Workspace entitlement name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

typeREQUIRED

string paid_credits

Resource type limited by this entitlement.

usageLimitUSDREQUIRED

integer

Dollar-denominated credit cap in whole US dollars.

windowDaysREQUIRED

value

Fixed quota window in days. Supported values are 1, 7, and 30.

number 1

number 7

number 30

assignmentREQUIRED

one of

Who receives this entitlement.

object

typeREQUIRED

string default

Apply this entitlement to workspace members without a more specific entitlement.

object

typeREQUIRED

string users

userIDsREQUIRED

array

Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments.

Items

string

Workspace member user ID.

object

typeREQUIRED

string workspace_groups

workspaceGroupIDsREQUIRED

array

Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments.

Items

string · uuid

Workspace group ID.

object

typeREQUIRED

string unmanaged

This entitlement uses an assignment mechanism not managed by this API.

Example

{
  "entitlement": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "type": "paid_credits",
    "usageLimitUSD": 1,
    "windowDays": 1,
    "assignment": {
      "type": "default"
    }
  }
}

400 Invalid request body

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

409 Workspace entitlement conflict

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Get Workspace Entitlements

GET /workspace/entitlements/{entitlementID}

Get one workspace entitlement.

OAuth Scopes

amp.api:workspace.entitlements:view

Path Parameters

entitlementID REQUIRED

ID of the target workspace entitlement.

Type string · uuid

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/entitlements/00000000-0000-4000-8000-000000000000' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "entitlement": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "type": "paid_credits",
    "usageLimitUSD": 1,
    "windowDays": 1,
    "assignment": {
      "type": "default"
    }
  }
}

Responses

200 Success

Response Body

Content Type application/json

Type object

entitlementREQUIRED

object

Workspace entitlement.

idREQUIRED

string · uuid

Unique identifier for the workspace entitlement.

nameREQUIRED

string

Workspace entitlement name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

typeREQUIRED

string paid_credits

Resource type limited by this entitlement.

usageLimitUSDREQUIRED

integer

Dollar-denominated credit cap in whole US dollars.

windowDaysREQUIRED

value

Fixed quota window in days. Supported values are 1, 7, and 30.

number 1

number 7

number 30

assignmentREQUIRED

one of

Who receives this entitlement.

object

typeREQUIRED

string default

Apply this entitlement to workspace members without a more specific entitlement.

object

typeREQUIRED

string users

userIDsREQUIRED

array

Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments.

Items

string

Workspace member user ID.

object

typeREQUIRED

string workspace_groups

workspaceGroupIDsREQUIRED

array

Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments.

Items

string · uuid

Workspace group ID.

object

typeREQUIRED

string unmanaged

This entitlement uses an assignment mechanism not managed by this API.

Example

{
  "entitlement": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "type": "paid_credits",
    "usageLimitUSD": 1,
    "windowDays": 1,
    "assignment": {
      "type": "default"
    }
  }
}

400 Invalid entitlement ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace entitlement not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Update Workspace Entitlements

PATCH /workspace/entitlements/{entitlementID}

Update provided workspace entitlement fields. If assignment is provided, it replaces the entitlement assignment.

OAuth Scopes

amp.api:workspace.entitlements:manage

Path Parameters

entitlementID REQUIRED

ID of the target workspace entitlement.

Type string · uuid

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type object

name

string

Workspace entitlement name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

usageLimitUSD

integer

Dollar-denominated credit cap in whole US dollars.

windowDays

value

Fixed quota window in days. Supported values are 1, 7, and 30.

number 1

number 7

number 30

assignment

one of

Who receives this entitlement. If provided, this replaces the entitlement assignment; userIDs and workspaceGroupIDs are full replacement lists, not incremental additions.

object

typeREQUIRED

string default

Apply this entitlement to workspace members without a more specific entitlement.

object

typeREQUIRED

string users

userIDsREQUIRED

array

Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments.

Items

string

Workspace member user ID.

object

typeREQUIRED

string workspace_groups

workspaceGroupIDsREQUIRED

array

Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments.

Items

string · uuid

Workspace group ID.

Example

{
  "name": "Example",
  "usageLimitUSD": 1,
  "windowDays": 1,
  "assignment": {
    "type": "default"
  }
}

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/entitlements/00000000-0000-4000-8000-000000000000' \
  --request PATCH \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "usageLimitUSD": 1,
  "windowDays": 1,
  "assignment": {
    "type": "default"
  }
}'

HTTP Response

200 Content Type application/json

{
  "entitlement": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "type": "paid_credits",
    "usageLimitUSD": 1,
    "windowDays": 1,
    "assignment": {
      "type": "default"
    }
  }
}

Responses

200 Workspace entitlement updated

Response Body

Content Type application/json

Type object

entitlementREQUIRED

object

Workspace entitlement.

idREQUIRED

string · uuid

Unique identifier for the workspace entitlement.

nameREQUIRED

string

Workspace entitlement name. Use 3 to 32 letters, numbers, and hyphens, starting and ending with a letter or number. Names keep their case and are unique in the workspace ignoring case.

typeREQUIRED

string paid_credits

Resource type limited by this entitlement.

usageLimitUSDREQUIRED

integer

Dollar-denominated credit cap in whole US dollars.

windowDaysREQUIRED

value

Fixed quota window in days. Supported values are 1, 7, and 30.

number 1

number 7

number 30

assignmentREQUIRED

one of

Who receives this entitlement.

object

typeREQUIRED

string default

Apply this entitlement to workspace members without a more specific entitlement.

object

typeREQUIRED

string users

userIDsREQUIRED

array

Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments.

Items

string

Workspace member user ID.

object

typeREQUIRED

string workspace_groups

workspaceGroupIDsREQUIRED

array

Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments.

Items

string · uuid

Workspace group ID.

object

typeREQUIRED

string unmanaged

This entitlement uses an assignment mechanism not managed by this API.

Example

{
  "entitlement": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "type": "paid_credits",
    "usageLimitUSD": 1,
    "windowDays": 1,
    "assignment": {
      "type": "default"
    }
  }
}

400 Invalid request body or entitlement ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace entitlement not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

409 Workspace entitlement conflict

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Delete Workspace Entitlements

DELETE /workspace/entitlements/{entitlementID}

Delete a workspace entitlement.

OAuth Scopes

amp.api:workspace.entitlements:manage

Path Parameters

entitlementID REQUIRED

ID of the target workspace entitlement.

Type string · uuid

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/entitlements/00000000-0000-4000-8000-000000000000' \
  --request DELETE \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

Responses

204 Workspace entitlement deleted

No content

HTTP 204 responses do not include a response body.

400 Invalid entitlement ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace entitlement not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Model Providers

APIs for managing workspace model provider keys.

List Workspace Model Provider Keys

GET /workspace/model-provider-keys

List all workspace model provider (BYOK) keys. Key secrets are never returned.

OAuth Scopes

amp.api:workspace.model-provider-keys:view

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/model-provider-keys' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "modelProviderKeys": [
    {
      "provider": "meta",
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "redactedKey": null,
      "active": true,
      "lastUsedAt": null,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

modelProviderKeysREQUIRED

array

All workspace model provider keys.

Items

one of

A workspace model provider (BYOK) key. Inference for a provider uses the workspace key that is currently active for that provider.

object

providerREQUIRED

string meta

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

object

providerREQUIRED

string anthropic

Anthropic API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

object

providerREQUIRED

string openai

OpenAI API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

configREQUIRED

object

openAIRegion

string global | us | eu | au | ca | jp | in | sg | kr | gb | ae

OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces.

Default: "global"

object

providerREQUIRED

string xai

SpaceXAI API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

Example

{
  "modelProviderKeys": [
    {
      "provider": "meta",
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "Example",
      "redactedKey": null,
      "active": true,
      "lastUsedAt": null,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Create Workspace Model Provider Keys

POST /workspace/model-provider-keys

Create a workspace model provider (BYOK) key. Keys are created inactive unless active is true. Activating a key does not deactivate other keys. To rotate a key, create a new active key with the same configuration, then deactivate or delete the old key.

OAuth Scopes

amp.api:workspace.model-provider-keys:manage

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type one of

object

providerREQUIRED

string meta

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

apiKeyREQUIRED

string

Provider API key secret. Stored encrypted and never returned by this API.

active

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

Default: false

object

providerREQUIRED

string anthropic

Create an Anthropic API key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

apiKeyREQUIRED

string

Provider API key secret. Stored encrypted and never returned by this API.

active

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

Default: false

object

providerREQUIRED

string openai

Create an OpenAI API key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

apiKeyREQUIRED

string

Provider API key secret. Stored encrypted and never returned by this API.

active

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

Default: false

config

object

OpenAI-specific configuration. Defaults to the global region.

openAIRegion

string global | us | eu | au | ca | jp | in | sg | kr | gb | ae

OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces.

Default: "global"

object

providerREQUIRED

string xai

Create a SpaceXAI API key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

apiKeyREQUIRED

string

Provider API key secret. Stored encrypted and never returned by this API.

active

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

Default: false

Example

{
  "provider": "meta",
  "name": "Example",
  "apiKey": "string",
  "active": false
}

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/model-provider-keys' \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "meta",
  "name": "Example",
  "apiKey": "string",
  "active": false
}'

HTTP Response

201 Content Type application/json

{
  "modelProviderKey": {
    "provider": "meta",
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "redactedKey": null,
    "active": true,
    "lastUsedAt": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

Responses

201 Workspace model provider key created

Response Body

Content Type application/json

Type object

modelProviderKeyREQUIRED

one of

Workspace model provider key.

object

providerREQUIRED

string meta

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

object

providerREQUIRED

string anthropic

Anthropic API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

object

providerREQUIRED

string openai

OpenAI API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

configREQUIRED

object

openAIRegion

string global | us | eu | au | ca | jp | in | sg | kr | gb | ae

OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces.

Default: "global"

object

providerREQUIRED

string xai

SpaceXAI API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

Example

{
  "modelProviderKey": {
    "provider": "meta",
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "redactedKey": null,
    "active": true,
    "lastUsedAt": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

400 Invalid request body

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s) or restricted configuration

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Get Workspace Model Provider Keys

GET /workspace/model-provider-keys/{keyID}

Get one workspace model provider (BYOK) key. Key secrets are never returned.

OAuth Scopes

amp.api:workspace.model-provider-keys:view

Path Parameters

keyID REQUIRED

ID of the target workspace model provider key.

Type string · uuid

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/model-provider-keys/00000000-0000-4000-8000-000000000000' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "modelProviderKey": {
    "provider": "meta",
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "redactedKey": null,
    "active": true,
    "lastUsedAt": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

Responses

200 Success

Response Body

Content Type application/json

Type object

modelProviderKeyREQUIRED

one of

Workspace model provider key.

object

providerREQUIRED

string meta

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

object

providerREQUIRED

string anthropic

Anthropic API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

object

providerREQUIRED

string openai

OpenAI API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

configREQUIRED

object

openAIRegion

string global | us | eu | au | ca | jp | in | sg | kr | gb | ae

OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces.

Default: "global"

object

providerREQUIRED

string xai

SpaceXAI API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

Example

{
  "modelProviderKey": {
    "provider": "meta",
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "redactedKey": null,
    "active": true,
    "lastUsedAt": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

400 Invalid key ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace model provider key not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Update Workspace Model Provider Keys

PATCH /workspace/model-provider-keys/{keyID}

Update provided workspace model provider (BYOK) key fields. The key secret cannot be updated in place: to rotate a key, create a new key with the new secret and active set to true, then delete the old key.

OAuth Scopes

amp.api:workspace.model-provider-keys:manage

Path Parameters

keyID REQUIRED

ID of the target workspace model provider key.

Type string · uuid

Header Parameters

Content-Type REQUIRED

Must be application/json

Type string

Request Body

Content Type application/json

Type object

name

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

active

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

config

object

Provider-specific configuration. Only supported for openai keys.

openAIRegion

string global | us | eu | au | ca | jp | in | sg | kr | gb | ae

OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces.

Default: "global"

Example

{
  "name": "Example",
  "active": true,
  "config": {
    "openAIRegion": "global"
  }
}

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/model-provider-keys/00000000-0000-4000-8000-000000000000' \
  --request PATCH \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example",
  "active": true,
  "config": {
    "openAIRegion": "global"
  }
}'

HTTP Response

200 Content Type application/json

{
  "modelProviderKey": {
    "provider": "meta",
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "redactedKey": null,
    "active": true,
    "lastUsedAt": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

Responses

200 Workspace model provider key updated

Response Body

Content Type application/json

Type object

modelProviderKeyREQUIRED

one of

Workspace model provider key.

object

providerREQUIRED

string meta

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

object

providerREQUIRED

string anthropic

Anthropic API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

object

providerREQUIRED

string openai

OpenAI API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

configREQUIRED

object

openAIRegion

string global | us | eu | au | ca | jp | in | sg | kr | gb | ae

OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces.

Default: "global"

object

providerREQUIRED

string xai

SpaceXAI API key.

idREQUIRED

string · uuid

Unique identifier for the workspace model provider key.

nameREQUIRED

string

Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key.

redactedKeyREQUIRED

string,null

Redacted display form of the stored API key, such as "sk-ant-api••••1234".

activeREQUIRED

boolean

Whether this key is eligible for inference. Multiple keys for the same provider can be active. Model mappings and connection priority determine which key is used.

lastUsedAtREQUIRED

string,null · date-time

When the key was last used for inference, with roughly 30-second granularity.

createdAtREQUIRED

string · date-time

When the key was created.

updatedAtREQUIRED

string · date-time

When the key was last updated.

Example

{
  "modelProviderKey": {
    "provider": "meta",
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Example",
    "redactedKey": null,
    "active": true,
    "lastUsedAt": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

400 Invalid request body or key ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s) or restricted configuration

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace model provider key not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Delete Workspace Model Provider Keys

DELETE /workspace/model-provider-keys/{keyID}

Delete a workspace model provider (BYOK) key. The stored key secret is destroyed immediately.

OAuth Scopes

amp.api:workspace.model-provider-keys:manage

Path Parameters

keyID REQUIRED

ID of the target workspace model provider key.

Type string · uuid

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/model-provider-keys/00000000-0000-4000-8000-000000000000' \
  --request DELETE \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

Responses

204 Workspace model provider key deleted

No content

HTTP 204 responses do not include a response body.

400 Invalid key ID parameter

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

404 Workspace model provider key not found

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

Analytics

APIs for workspace usage analytics.

Get Workspace Analytics Daily Usage

GET /workspace/analytics/daily-usage

Get daily usage analytics for your workspace. Returns usage metrics and costs for users in the specified time period.

OAuth Scopes

amp.api:workspace.analytics:view

Query Parameters

endDate

End date (YYYY-MM-DD). Default: today

Type string · date

lookbackDays

Number of days to include.

Type integer

Default: 1

userID

Only include workspace-attributed usage for this user ID.

Type string

HTTP Request

curl 'https://ampcode.com/api/v2/workspace/analytics/daily-usage?lookbackDays=1' \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'

HTTP Response

200 Content Type application/json

{
  "metadata": {
    "startDate": "2026-01-01",
    "endDate": "2026-01-01",
    "activeUsers": 1,
    "totalUsers": 1,
    "totalUsage": 1,
    "totalOrbUsage": 1,
    "totalToolUsage": 1
  },
  "data": [
    {
      "date": "2026-01-01",
      "users": [
        {
          "user": {
            "id": "string",
            "email": "author@example.com"
          },
          "metrics": {
            "linesAdded": 1,
            "linesDeleted": 1,
            "linesModified": 1,
            "usage": 1,
            "orbUsage": 1,
            "toolUsage": 1,
            "estimatedProviderCostAtListPriceUSD": 1
          },
          "models": {},
          "orbs": [
            {}
          ],
          "tools": [
            {}
          ]
        }
      ]
    }
  ]
}

Responses

200 Success

Response Body

Content Type application/json

Type object

Daily usage metrics for the workspace. Paid usage amounts in USD retain each credit allocation's original dollar value, even if the workspace later changes credit units.

metadataREQUIRED

object

Metadata about the usage period

startDateREQUIRED

string · date

Start date of the period

endDateREQUIRED

string · date

End date of the period

activeUsersREQUIRED

number

Users with non-zero usage in the period

totalUsersREQUIRED

number

Total distinct users represented in the period, including former members with workspace-attributed usage

totalUsageREQUIRED

number

Total usage in the period (USD), including orb and tool usage

totalOrbUsageREQUIRED

number

Total orb usage in the period (USD)

totalToolUsageREQUIRED

number

Total tool usage in the period (USD)

dataREQUIRED

array

Daily usage data for each day in the period

Items

object

dateREQUIRED

string · date

Date in YYYY-MM-DD format

usersREQUIRED

array

Usage data for users in scope for the period, including users no longer in the workspace if they have usage attributed to this workspace

Items

object

userREQUIRED

object

User information

idREQUIRED

string

User ID

email

string · email

User email - only returned if the client has the "amp.api:workspace.members:view" scope

metricsREQUIRED

object

Usage metrics for the user

linesAddedREQUIRED

number

Lines added by the user

linesDeletedREQUIRED

number

Lines deleted by the user

linesModifiedREQUIRED

number

Lines modified by the user

usageREQUIRED

number

Usage for the user on that day (USD), including orb and tool usage. Counts only usage attributed to the workspace and paid with paid credits; excludes usage paid with free or promotional credits, subscriptions, or the free tier.

orbUsageREQUIRED

number

Workspace-attributed orb usage for the user on that day (USD). Included in usage; not included in models.

toolUsageREQUIRED

number

Workspace-attributed tool usage for the user on that day (USD). Included in usage; not included in models.

estimatedProviderCostAtListPriceUSDREQUIRED

number

EXPERIMENTAL. Estimated USD cost of bring-your-own-key (BYOK) inference by the user on that day, computed from token usage at the model provider’s public list price at the time of the request. This is what the customer would have paid the provider (for example Anthropic or OpenAI) at list price; it is not billed by Amp and is not included in the usage field. This is only an estimate. Amp cannot see negotiated pricing, discounts, committed-use contracts, or free-tier allowances a customer has with a provider, and the estimate does not include markups or fees charged by AI routers or gateways. Requests sent through an AI router connection (for example OpenRouter) are not estimated at all and contribute 0, because Amp has no list price for router-served models. Requests served through subscription connections (such as ChatGPT or Claude subscriptions) are excluded because they have no per-token provider bill. Requests made before 2026-08-26 are not included. Contact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice.

modelsREQUIRED

object

Per-model request and token counts for the user

orbsREQUIRED

array

Workspace-attributed orb runtime and usage for the user by orb size, largest usage first

Items

object

Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total.

sizeREQUIRED

string,null

Orb size, such as "a1.medium", or null when the CPU and memory match no current orb size

cpuCountREQUIRED

number,null

vCPUs of the orb, or null if unknown

memoryMBREQUIRED

number,null

Memory of the orb in MB, or null if unknown

runtimeMsREQUIRED

number

Billed orb runtime in milliseconds, whichever credits paid for it. Runtime paid for by credits that the enclosing usage total excludes, such as personal subscriptions, counts here but not in usage.

usageREQUIRED

number

Orb usage (USD), counted the same way as the enclosing usage total

toolsREQUIRED

array

Workspace-attributed tool calls and usage for the user by tool, largest usage first

Items

object

Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total.

toolREQUIRED

string

Tool name, such as "web_search" or "read_web_page"

callsREQUIRED

number

Number of charged calls, whichever credits paid for them, including calls that cost nothing

usageREQUIRED

number

Tool usage (USD), counted the same way as the enclosing usage total

Example

{
  "metadata": {
    "startDate": "2026-01-01",
    "endDate": "2026-01-01",
    "activeUsers": 1,
    "totalUsers": 1,
    "totalUsage": 1,
    "totalOrbUsage": 1,
    "totalToolUsage": 1
  },
  "data": [
    {
      "date": "2026-01-01",
      "users": [
        {
          "user": {
            "id": "string",
            "email": "author@example.com"
          },
          "metrics": {
            "linesAdded": 1,
            "linesDeleted": 1,
            "linesModified": 1,
            "usage": 1,
            "orbUsage": 1,
            "toolUsage": 1,
            "estimatedProviderCostAtListPriceUSD": 1
          },
          "models": {},
          "orbs": [
            {}
          ],
          "tools": [
            {}
          ]
        }
      ]
    }
  ]
}

400 Invalid query parameters

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

401 Unauthorized

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

403 Forbidden: missing client scope(s)

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}

500 Internal server error

Response Body

Content Type application/json

Type object

errorREQUIRED

string

Error message describing what went wrong

Example

{
  "error": "string"
}