{"info":{"title":"Amp External API","version":"v2","description":"The Amp External API allows integrations to interact with Amp workspace data.\n\nAll data access is scoped to the Amp workspace that owns the provided client credentials.\n\nIf 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.\n\nTo use this API, create a [External API Application](https://ampcode.com/workspace/applications) in your workspace. Right now, only machine-to-machine applications can be created; Sign in with Amp applications are not generally available.\n\nFor integrations and automations using the Amp product itself, use the [Amp CLI](https://ampcode.com/install) or [Amp SDK](https://ampcode.com/docs/sdk) instead."},"openapi":"3.0.0","tags":[{"name":"Meta","description":"APIs for the authenticated actor and API metadata.","x-amp-sort-order":1000},{"name":"Threads","description":"APIs for working with Amp threads."},{"name":"Workspace","description":"APIs for workspace-level resources such as members."},{"name":"Projects","description":"APIs for listing Amp projects."},{"name":"Groups","description":"APIs for managing workspace groups."},{"name":"Entitlements","description":"APIs for managing workspace entitlements."},{"name":"Model Providers","description":"APIs for managing workspace model provider keys."},{"name":"Analytics","description":"APIs for workspace usage analytics."},{"name":"Inference","description":"APIs for running model inference as a Sign in with Amp user."}],"servers":[{"url":"https://ampcode.com"}],"security":[{"v2.OAuth2AppAuth":[]}],"components":{"securitySchemes":{"v2.PersonalAccessToken":{"type":"http","scheme":"bearer","description":"Personal access token. Create one in [Settings → Access Tokens](https://ampcode.com/settings/access-tokens) and send it as `Authorization: Bearer <token>`. It acts as its owner: it requires the PAT scope the operation’s description names and the owner’s current resource permissions. Only operations listing this scheme accept PATs.\n\n**Git.** A personal access token can also clone, fetch, and push Amp-hosted project repositories over HTTPS. Select `amp.git:read` to clone and fetch, and `amp.git:write` to push. Neither includes the other, so select both to clone and push. The token reaches the projects its owner can read, and pushes only where the owner can push. Plugin and skills repositories do not accept it. Tokens created before November 17, 2026 have no Git access.\n\nSend the token as the HTTP Basic password; Amp ignores the username. To keep it out of the remote URL, pass it in a header:\n\n```sh\nAUTH=\"Authorization: Basic $(printf 'x:%s' \"$AMP_PAT\" | base64 | tr -d '\\n')\"\ngit -c http.extraHeader=\"$AUTH\" clone https://ampcode.com/@owner/project-name\ncd project-name\ngit config http.extraHeader \"$AUTH\"\n```\n\nLater `git fetch` and `git push` reuse the header. Git saves it in `.git/config`, so protect that file like the token. A missing scope returns `403`; an expired, revoked, or disabled token returns `401`. If your workspace has a required custom domain, use it instead of `ampcode.com`.\n\n**Deprecated scope names.** These old names are deprecated aliases. Credentials that carry them keep working, and `GET /api/v2/actor` returns a credential's scopes under the names it carries. Use the new names: `amp.api:threads:create` (now `amp.api:threads:write`), `amp.api:threads:view` (now `amp.api:threads:read`)."},"v2.SignInWithAmpOAuth":{"type":"oauth2","description":"Sign in with Amp OAuth access token. Include resource=https://ampcode.com/api/v2 in the authorization request. Amp requires that resource as the token audience and reads the exact scopes from the signed token. Amp also verifies the registered application, selected workspace, current membership, and user permissions. Workspace admins register Sign in with Amp applications in [workspace Applications settings](https://ampcode.com/workspace/applications). **Thread scopes.** 'amp.api:threads:read' includes both 'amp.api:threads.meta:read' and 'amp.api:threads.contents:read'. Every operation and field that requires one of them also accepts it. **Deprecated scope names.** These old names are deprecated aliases. Credentials that carry them keep working, and `GET /api/v2/actor` returns a credential's scopes under the names it carries. Use the new names: `amp.api:workspace.threads.meta:view` (now `amp.api:threads.meta:read`), `amp.api:workspace.threads.contents:view` (now `amp.api:threads.contents:read`), `amp.api:workspace.threads:manage` (now `amp.api:threads:write`), `amp.api:workspace.analytics:view` (now `amp.api:workspace.analytics:read`), `amp.api:workspace.entitlements:view` (now `amp.api:workspace.entitlements:read`), `amp.api:workspace.entitlements:manage` (now `amp.api:workspace.entitlements:write`), `amp.api:workspace.groups:view` (now `amp.api:workspace.groups:read`), `amp.api:workspace.groups:manage` (now `amp.api:workspace.groups:write`), `amp.api:workspace.members:view` (now `amp.api:workspace.members:read`), `amp.api:workspace.model-provider-keys:view` (now `amp.api:workspace.model-provider-keys:read`), `amp.api:workspace.model-provider-keys:manage` (now `amp.api:workspace.model-provider-keys:write`), `amp.api:workspace.projects:view` (now `amp.api:projects:read`).","flows":{"authorizationCode":{"authorizationUrl":"https://auth.ampcode.com/oauth2/authorize","scopes":{"openid":"Identify the signed-in user.","profile":"Read the signed-in user’s profile.","email":"Read the signed-in user’s email address.","offline_access":"Receive a refresh token for offline access.","amp.api:threads:read":"List the threads the signed-in user can see in this workspace, with their metadata, titles, repositories, hostnames, and labels. Includes both narrower thread scopes.","amp.api:threads.meta:read":"List the threads the signed-in user can see in this workspace, with their basic metadata.","amp.api:threads.contents:read":"Include the titles, repositories, hostnames, and labels of the threads the signed-in user can see.","amp.api:workspace.members:read":"View members and member information for this workspace","amp.api:projects:read":"View projects and repository metadata for this workspace","amp.git:read":"Read Amp-hosted project repositories available to the token holder.","amp.git:write":"Write to Amp-hosted project repositories the authorizing user can access."},"tokenUrl":"https://auth.ampcode.com/oauth2/token"}}},"v2.OAuth2AppAuth":{"type":"oauth2","name":"Amp M2M OAuth2 App","description":"Machine-to-machine (M2M) access token from the OAuth 2.0 client credentials flow. Workspace admins create M2M applications in [workspace Applications settings](https://ampcode.com/workspace/applications) and choose the scopes each one may request. The token acts for its whole workspace, limited to those scopes. **Thread scopes.** 'amp.api:threads:read' includes both 'amp.api:threads.meta:read' and 'amp.api:threads.contents:read'. Every operation and field that requires one of them also accepts it. For an M2M client, 'amp.api:threads:write' allows deleting threads. It does not allow creating them. **Deprecated scope names.** These old names are deprecated aliases. Credentials that carry them keep working, and `GET /api/v2/actor` returns a credential's scopes under the names it carries. Use the new names: `amp.api:workspace.threads.meta:view` (now `amp.api:threads.meta:read`), `amp.api:workspace.threads.contents:view` (now `amp.api:threads.contents:read`), `amp.api:workspace.threads:manage` (now `amp.api:threads:write`), `amp.api:workspace.analytics:view` (now `amp.api:workspace.analytics:read`), `amp.api:workspace.entitlements:view` (now `amp.api:workspace.entitlements:read`), `amp.api:workspace.entitlements:manage` (now `amp.api:workspace.entitlements:write`), `amp.api:workspace.groups:view` (now `amp.api:workspace.groups:read`), `amp.api:workspace.groups:manage` (now `amp.api:workspace.groups:write`), `amp.api:workspace.members:view` (now `amp.api:workspace.members:read`), `amp.api:workspace.model-provider-keys:view` (now `amp.api:workspace.model-provider-keys:read`), `amp.api:workspace.model-provider-keys:manage` (now `amp.api:workspace.model-provider-keys:write`), `amp.api:workspace.projects:view` (now `amp.api:projects:read`).","flows":{"clientCredentials":{"scopes":{"amp.api:threads:read":"View thread metadata and contents in this workspace","amp.api:threads.meta:read":"View basic thread metadata in this workspace","amp.api:threads.contents:read":"View thread contents and advanced details in this workspace","amp.api:threads:write":"Manage threads in this workspace","amp.api:workspace.analytics:read":"View analytics for this workspace","amp.api:workspace.entitlements:read":"View entitlements for this workspace","amp.api:workspace.entitlements:write":"Manage entitlements for this workspace","amp.api:workspace.groups:read":"View groups in this workspace","amp.api:workspace.groups:write":"Manage groups in this workspace","amp.api:workspace.members:read":"View members and member information for this workspace","amp.api:workspace.model-provider-keys:read":"View model provider (BYOK) keys for this workspace","amp.api:workspace.model-provider-keys:write":"Manage model provider (BYOK) keys for this workspace","amp.api:projects:read":"View projects and repository metadata for this workspace","amp.git:read":"Read Amp-hosted project repositories available to the token holder."},"tokenUrl":"https://auth.ampcode.com/oauth2/token"}}}},"schemas":{"v2.ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"},"v2.ActorIdentity":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["m2m"],"description":"Authentication actor type."},"id":{"type":"string","description":"WorkOS OAuth2 client ID from the access token subject."},"scopes":{"type":"array","items":{"type":"string"},"description":"Amp permission scopes granted to the presented credential."}},"required":["type","id","scopes"],"title":"v2.M2MActorIdentity"},{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"Authentication actor type."},"id":{"type":"string","description":"Amp user ID from the access token subject."},"scopes":{"type":"array","items":{"type":"string"},"description":"Amp permission scopes granted to the presented credential."}},"required":["type","id","scopes"],"title":"v2.UserActorIdentity"}],"title":"v2.ActorIdentity"},"v2.ActorResponse":{"type":"object","properties":{"actor":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["m2m"],"description":"Authentication actor type."},"id":{"type":"string","description":"WorkOS OAuth2 client ID from the access token subject."},"scopes":{"type":"array","items":{"type":"string"},"description":"Amp permission scopes granted to the presented credential."}},"required":["type","id","scopes"],"title":"v2.M2MActorIdentity"},{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"Authentication actor type."},"id":{"type":"string","description":"Amp user ID from the access token subject."},"scopes":{"type":"array","items":{"type":"string"},"description":"Amp permission scopes granted to the presented credential."}},"required":["type","id","scopes"],"title":"v2.UserActorIdentity"}],"title":"v2.ActorIdentity"}},"required":["actor"],"title":"v2.ActorResponse"},"v2.Repository":{"type":"object","properties":{"url":{"type":"string","description":"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":{"type":"string","description":"The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository."}},"required":["url"],"title":"v2.Repository"},"v2.ThreadAgentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"What a thread’s agent was last known to be doing."},"v2.ThreadStats":{"type":"object","properties":{"messageCount":{"type":"integer","description":"Number of messages in the thread, counting user messages, assistant messages, and tool results."},"userMessageCount":{"type":"integer","description":"Number of user messages with text or an image, not counting tool results. Includes messages that other threads, plugins, or automations sent to the thread. May be 0 for old threads."},"lastUserMessageAt":{"type":"string","format":"date-time","description":"When the last user message was sent, not counting messages that another thread sent. Unset if the thread has none."}},"required":["messageCount","userMessageCount"],"title":"v2.ThreadStats","description":"Message counts of a thread."},"v2.Thread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"createdAt":{"type":"string","format":"date-time","description":"When the thread was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"firstSyncedAt":{"type":"string","format":"date-time","description":"When the thread was first synced."},"creatorUserID":{"type":"string","description":"User ID of the thread creator."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"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."},"stats":{"type":"object","properties":{"messageCount":{"type":"integer","description":"Number of messages in the thread, counting user messages, assistant messages, and tool results."},"userMessageCount":{"type":"integer","description":"Number of user messages with text or an image, not counting tool results. Includes messages that other threads, plugins, or automations sent to the thread. May be 0 for old threads."},"lastUserMessageAt":{"type":"string","format":"date-time","description":"When the last user message was sent, not counting messages that another thread sent. Unset if the thread has none."}},"required":["messageCount","userMessageCount"],"title":"v2.ThreadStats","description":"Message counts of the thread."},"pinned":{"type":"boolean","description":"Whether the user of a personal access token or Sign in with Amp access token pinned the thread. Unset for M2M clients."},"unread":{"type":"boolean","description":"Whether the thread’s latest reply is unread by its owner, as the Amp app’s thread lists show it. Only returned to the owner, through a personal access token or Sign in with Amp access token, and only once the thread has a reply."},"lastReadAt":{"type":"string","format":"date-time","description":"When the owner read the thread’s latest reply. Only returned to the owner, through a personal access token or Sign in with Amp access token; unset while the reply is unread or there is none."},"hostname":{"type":"string","description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"mainThreadID":{"type":"string","description":"ID of the main thread, if this is a sub-thread"},"parentThreadID":{"type":"string","description":"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":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"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":{"type":"string","description":"The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository."}},"required":["url"],"title":"v2.Repository"},"description":"Repositories in which this thread started working. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"labels":{"type":"array","items":{"type":"string"},"description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"subThreads":{"type":"array","description":"Sub-threads belonging to this thread.","items":{"$ref":"#/components/schemas/v2.Thread"}}},"required":["id","creatorUserID"],"title":"v2.Thread","description":"A conversation thread in Amp"},"v2.ThreadListResponse":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"threads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"createdAt":{"type":"string","format":"date-time","description":"When the thread was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"firstSyncedAt":{"type":"string","format":"date-time","description":"When the thread was first synced."},"creatorUserID":{"type":"string","description":"User ID of the thread creator."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"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."},"stats":{"type":"object","properties":{"messageCount":{"type":"integer","description":"Number of messages in the thread, counting user messages, assistant messages, and tool results."},"userMessageCount":{"type":"integer","description":"Number of user messages with text or an image, not counting tool results. Includes messages that other threads, plugins, or automations sent to the thread. May be 0 for old threads."},"lastUserMessageAt":{"type":"string","format":"date-time","description":"When the last user message was sent, not counting messages that another thread sent. Unset if the thread has none."}},"required":["messageCount","userMessageCount"],"title":"v2.ThreadStats","description":"Message counts of the thread."},"pinned":{"type":"boolean","description":"Whether the user of a personal access token or Sign in with Amp access token pinned the thread. Unset for M2M clients."},"unread":{"type":"boolean","description":"Whether the thread’s latest reply is unread by its owner, as the Amp app’s thread lists show it. Only returned to the owner, through a personal access token or Sign in with Amp access token, and only once the thread has a reply."},"lastReadAt":{"type":"string","format":"date-time","description":"When the owner read the thread’s latest reply. Only returned to the owner, through a personal access token or Sign in with Amp access token; unset while the reply is unread or there is none."},"hostname":{"type":"string","description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"mainThreadID":{"type":"string","description":"ID of the main thread, if this is a sub-thread"},"parentThreadID":{"type":"string","description":"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":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"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":{"type":"string","description":"The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository."}},"required":["url"],"title":"v2.Repository"},"description":"Repositories in which this thread started working. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"labels":{"type":"array","items":{"type":"string"},"description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"subThreads":{"type":"array","description":"Sub-threads belonging to this thread.","items":{"$ref":"#/components/schemas/v2.Thread"}}},"required":["id","creatorUserID"],"title":"v2.Thread","description":"A conversation thread in Amp"},"description":"Array of threads matching the query"}},"required":["threads"],"title":"v2.ThreadListResponse","description":"Response model for thread list operations"},"v2.ThreadListEventThread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"What the thread’s agent is doing now. Unlike the list, this does not trail the agent."},"unread":{"type":"boolean","description":"Whether the thread has an assistant reply the user has not read."}},"required":["id","updatedAt","archived","agentState","unread"],"title":"v2.ThreadListEventThread","description":"The current values of a thread’s fields that change while it runs."},"v2.ThreadListEvent":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["thread"]},"thread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"What the thread’s agent is doing now. Unlike the list, this does not trail the agent."},"unread":{"type":"boolean","description":"Whether the thread has an assistant reply the user has not read."}},"required":["id","updatedAt","archived","agentState","unread"],"title":"v2.ThreadListEventThread","description":"The current values of a thread’s fields that change while it runs."}},"required":["type","thread"],"description":"A thread was created or changed, or is in the stream’s first snapshot. Merge it by `id`; an `id` you have not listed is a new thread."},{"type":"object","properties":{"type":{"type":"string","enum":["ready"]}},"required":["type"],"description":"The first snapshot is complete; later `thread` events are changes."},{"type":"object","properties":{"type":{"type":"string","enum":["heartbeat"]}},"required":["type"],"description":"Sent every 15 seconds."}],"title":"v2.ThreadListEvent","description":"One Server-Sent Event of `GET /api/v2/workspace/threads/events`, sent as `data: <JSON>`."},"v2.CreateThreadRequest":{"type":"object","properties":{"project":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[^/\\s]+\\/[^/\\s]+$"}],"description":"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."},"message":{"type":"string","minLength":1,"maxLength":1000000,"description":"Text of the first user message. The agent starts working on it immediately."},"agentMode":{"type":"string","minLength":1,"maxLength":128,"description":"Agent mode key, such as medium. Must be a mode the token owner can use in the project. Omit for the default mode."},"title":{"type":"string","minLength":1,"maxLength":256,"description":"Thread title. Omit to let Amp generate one from the conversation."},"labels":{"type":"array","items":{"type":"string","minLength":1},"description":"Labels to attach to the thread, at most 20. Names are lowercased and must be alphanumeric with hyphens."}},"required":["project","message"],"additionalProperties":false,"title":"v2.CreateThreadRequest"},"v2.CreatedThread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"url":{"type":"string","format":"uri","description":"URL of the thread in the Amp web app."},"agentMode":{"type":"string","description":"Agent mode key the thread runs."}},"required":["id","url","agentMode"],"title":"v2.CreatedThread"},"v2.CreateThreadResponse":{"type":"object","properties":{"thread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"url":{"type":"string","format":"uri","description":"URL of the thread in the Amp web app."},"agentMode":{"type":"string","description":"Agent mode key the thread runs."}},"required":["id","url","agentMode"],"title":"v2.CreatedThread"}},"required":["thread"],"title":"v2.CreateThreadResponse"},"v2.UpdateThreadRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":256,"description":"New thread title."},"labels":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string","minLength":1,"maxLength":32},"maxItems":20},"remove":{"type":"array","items":{"type":"string","minLength":1,"maxLength":32},"maxItems":20}},"additionalProperties":false,"description":"Labels to add to and remove from the thread. Names are lowercased and must be alphanumeric with hyphens; a thread has at most 20."},"pinned":{"type":"boolean","description":"Pin or unpin the thread in the user’s thread lists."},"archived":{"type":"boolean","description":"Archive or unarchive the thread."},"snooze":{"anyOf":[{"type":"string","enum":["next_message","one_hour","one_day","one_week","indefinite","off"]},{"type":"object","properties":{"until":{"type":"string","format":"date-time"}},"required":["until"],"additionalProperties":false}],"description":"Hide the thread from the user’s thread lists: until its next message, for an hour, a day, or a week, indefinitely, or until a future time. `off` ends a snooze."}},"additionalProperties":false,"title":"v2.UpdateThreadRequest"},"v2.ThreadMessagesResponse":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"messages":{"type":"array","items":{},"description":"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."}},"required":["messages"],"title":"v2.ThreadMessagesResponse","description":"Response model for thread messages operations."},"v2.PostThreadMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":1000000,"description":"Text of the user message. The agent answers it with the conversation so far as context."}},"required":["message"],"additionalProperties":false,"title":"v2.PostThreadMessageRequest"},"v2.PostThreadMessageResponse":{"type":"object","properties":{"thread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"url":{"type":"string","format":"uri","description":"URL of the thread in the Amp web app."}},"required":["id","url"]},"messageID":{"type":"string","description":"ID of the posted message, the same as its `messageID` in `GET /api/v2/threads/{threadID}/messages`. The agent’s reply follows it."}},"required":["thread","messageID"],"title":"v2.PostThreadMessageResponse"},"v2.OrbUsage":{"type":"object","properties":{"size":{"type":["string","null"],"description":"Orb size, such as \"a1.medium\", or null when the CPU and memory match no current orb size"},"cpuCount":{"type":["number","null"],"description":"vCPUs of the orb, or null if unknown"},"memoryMB":{"type":["number","null"],"description":"Memory of the orb in MB, or null if unknown"},"runtimeMs":{"type":"number","description":"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."},"usage":{"type":"number","description":"Orb usage (USD), counted the same way as the enclosing usage total"}},"required":["size","cpuCount","memoryMB","runtimeMs","usage"],"title":"v2.OrbUsage","description":"Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total."},"v2.ToolUsage":{"type":"object","properties":{"tool":{"type":"string","description":"Tool name, such as \"web_search\" or \"read_web_page\""},"calls":{"type":"number","description":"Number of charged calls, whichever credits paid for them, including calls that cost nothing"},"usage":{"type":"number","description":"Tool usage (USD), counted the same way as the enclosing usage total"}},"required":["tool","calls","usage"],"title":"v2.ToolUsage","description":"Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total."},"v2.ThreadCostResponse":{"type":"object","properties":{"threadID":{"type":"string","description":"The thread ID"},"subThreadIDs":{"type":"array","items":{"type":"string"},"description":"Always empty. Kept for compatibility; usage covers only this thread."},"usage":{"type":"number","description":"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."},"orbUsage":{"type":"number","description":"Orb usage of the thread (USD). Included in usage; not included in models."},"toolUsage":{"type":"number","description":"Tool usage of the thread (USD). Included in usage; not included in models."},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."},"orbs":{"type":"array","items":{"type":"object","properties":{"size":{"type":["string","null"],"description":"Orb size, such as \"a1.medium\", or null when the CPU and memory match no current orb size"},"cpuCount":{"type":["number","null"],"description":"vCPUs of the orb, or null if unknown"},"memoryMB":{"type":["number","null"],"description":"Memory of the orb in MB, or null if unknown"},"runtimeMs":{"type":"number","description":"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."},"usage":{"type":"number","description":"Orb usage (USD), counted the same way as the enclosing usage total"}},"required":["size","cpuCount","memoryMB","runtimeMs","usage"],"title":"v2.OrbUsage","description":"Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total."},"description":"Orb runtime and usage of the thread by orb size, largest usage first"},"tools":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","description":"Tool name, such as \"web_search\" or \"read_web_page\""},"calls":{"type":"number","description":"Number of charged calls, whichever credits paid for them, including calls that cost nothing"},"usage":{"type":"number","description":"Tool usage (USD), counted the same way as the enclosing usage total"}},"required":["tool","calls","usage"],"title":"v2.ToolUsage","description":"Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total."},"description":"Tool calls and usage of the thread by tool, largest usage first"},"models":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","description":"Provider identifier for the model usage bucket"},"model":{"type":"string","description":"Model identifier for the model usage bucket"},"requests":{"type":"number","description":"Number of requests for this provider/model"},"inputTokens":{"type":"number","description":"Total uncached input tokens for this provider/model"},"outputTokens":{"type":"number","description":"Total output tokens for this provider/model"},"cacheReadInputTokens":{"type":"number","description":"Total cache-read input tokens for this provider/model"},"cacheCreationInputTokens":{"type":"number","description":"Total cache-creation input tokens for this provider/model"},"usage":{"type":"number","description":"Total cost in USD for this provider/model"},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["provider","model","requests","inputTokens","outputTokens","cacheReadInputTokens","cacheCreationInputTokens","usage","estimatedProviderCostAtListPriceUSD"]},"description":"Per-model usage and cost breakdown for the thread"}},"required":["threadID","subThreadIDs","usage","orbUsage","toolUsage","estimatedProviderCostAtListPriceUSD","orbs","tools","models"],"title":"v2.ThreadCostResponse","description":"Thread usage information"},"v2.WorkspaceMember":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the user"},"name":{"type":"string","description":"Full name of the user"},"email":{"type":"string","format":"email","description":"The primary email address of the user"},"role":{"type":"string","enum":["admin","member"],"description":"Workspace-level role of the user"},"avatarURL":{"type":["string","null"],"format":"uri","description":"Absolute URL of the user’s profile picture, publicly fetchable without credentials, or null when the user has none"}},"required":["id","name","email","role","avatarURL"],"title":"v2.WorkspaceMember"},"v2.WorkspaceMembersResponse":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the user"},"name":{"type":"string","description":"Full name of the user"},"email":{"type":"string","format":"email","description":"The primary email address of the user"},"role":{"type":"string","enum":["admin","member"],"description":"Workspace-level role of the user"},"avatarURL":{"type":["string","null"],"format":"uri","description":"Absolute URL of the user’s profile picture, publicly fetchable without credentials, or null when the user has none"}},"required":["id","name","email","role","avatarURL"],"title":"v2.WorkspaceMember"},"description":"All members of the workspace"}},"required":["members"],"title":"v2.WorkspaceMembersResponse","description":"Response for workspace members listing"},"v2.WorkspaceProjectOwner":{"type":"object","properties":{"type":{"type":"string","enum":["workspace"]},"id":{"type":"string","format":"uuid","description":"Unique identifier of the workspace that owns the project."},"name":{"type":"string","description":"Name of the workspace that owns the project."}},"required":["type","id","name"],"title":"v2.WorkspaceProjectOwner"},"v2.WorkspaceProjectRepository":{"type":"object","properties":{"mode":{"type":"string","enum":["amp-hosted","github","mapped"],"description":"How Amp connects to or hosts the project repository."},"url":{"type":["string","null"],"format":"uri","description":"Credential-free repository URL, or null when no safe public URL is available."}},"required":["mode","url"],"title":"v2.WorkspaceProjectRepository"},"v2.WorkspaceProject":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the project."},"name":{"type":"string","description":"Project name."},"namespace":{"type":"string","description":"Project namespace."},"owner":{"type":"object","properties":{"type":{"type":"string","enum":["workspace"]},"id":{"type":"string","format":"uuid","description":"Unique identifier of the workspace that owns the project."},"name":{"type":"string","description":"Name of the workspace that owns the project."}},"required":["type","id","name"],"title":"v2.WorkspaceProjectOwner"},"repository":{"type":"object","properties":{"mode":{"type":"string","enum":["amp-hosted","github","mapped"],"description":"How Amp connects to or hosts the project repository."},"url":{"type":["string","null"],"format":"uri","description":"Credential-free repository URL, or null when no safe public URL is available."}},"required":["mode","url"],"title":"v2.WorkspaceProjectRepository"},"archived":{"type":"boolean","description":"Whether the project is archived. Its threads are archived and read-only, and no thread can be started in it until it is unarchived."}},"required":["id","name","namespace","owner","repository","archived"],"title":"v2.WorkspaceProject"},"v2.WorkspaceProjectsResponse":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the project."},"name":{"type":"string","description":"Project name."},"namespace":{"type":"string","description":"Project namespace."},"owner":{"type":"object","properties":{"type":{"type":"string","enum":["workspace"]},"id":{"type":"string","format":"uuid","description":"Unique identifier of the workspace that owns the project."},"name":{"type":"string","description":"Name of the workspace that owns the project."}},"required":["type","id","name"],"title":"v2.WorkspaceProjectOwner"},"repository":{"type":"object","properties":{"mode":{"type":"string","enum":["amp-hosted","github","mapped"],"description":"How Amp connects to or hosts the project repository."},"url":{"type":["string","null"],"format":"uri","description":"Credential-free repository URL, or null when no safe public URL is available."}},"required":["mode","url"],"title":"v2.WorkspaceProjectRepository"},"archived":{"type":"boolean","description":"Whether the project is archived. Its threads are archived and read-only, and no thread can be started in it until it is unarchived."}},"required":["id","name","namespace","owner","repository","archived"],"title":"v2.WorkspaceProject"},"description":"Projects owned by the workspace."}},"required":["projects"],"title":"v2.WorkspaceProjectsResponse"},"v2.WorkspaceGroupMemberRole":{"type":"string","enum":["captain","member"]},"v2.WorkspaceGroupMemberEntry":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMemberEntry"},"v2.WorkspaceGroupMember":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"v2.WorkspaceGroup":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup"},"v2.WorkspaceGroupsResponse":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup"},"description":"All groups in the workspace."}},"required":["groups"],"title":"v2.WorkspaceGroupsResponse"},"v2.WorkspaceGroupResponse":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup","description":"Workspace group."}},"required":["group"],"title":"v2.WorkspaceGroupResponse"},"v2.CreateWorkspaceGroupBody":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMemberEntry"},"maxItems":5000,"default":[],"description":"Initial group members. Listed users are removed from any other workspace group."}},"required":["name"],"title":"v2.CreateWorkspaceGroupBody"},"v2.UpdateWorkspaceGroupBody":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."}},"required":["name"],"title":"v2.UpdateWorkspaceGroupBody"},"v2.ReplaceWorkspaceGroupMembersBody":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMemberEntry"},"maxItems":5000,"description":"Full replacement membership list. After the request succeeds, this group has exactly these members, and listed users are removed from any other workspace group."}},"required":["members"],"title":"v2.ReplaceWorkspaceGroupMembersBody"},"v2.AddWorkspaceGroupMembersBody":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMemberEntry"},"maxItems":5000,"description":"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."}},"required":["members"],"title":"v2.AddWorkspaceGroupMembersBody"},"v2.WorkspaceEntitlementAssignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]}]},"v2.WorkspaceEntitlementResponseAssignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["unmanaged"],"description":"This entitlement uses an assignment mechanism not managed by this API."}},"required":["type"]}]},"v2.WorkspaceEntitlement":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace entitlement."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."},"type":{"type":"string","enum":["paid_credits"],"description":"Resource type limited by this entitlement."},"usageLimitUSD":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["unmanaged"],"description":"This entitlement uses an assignment mechanism not managed by this API."}},"required":["type"]}],"description":"Who receives this entitlement."}},"required":["id","name","type","usageLimitUSD","windowDays","assignment"],"title":"v2.WorkspaceEntitlement"},"v2.WorkspaceEntitlementsResponse":{"type":"object","properties":{"entitlements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace entitlement."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."},"type":{"type":"string","enum":["paid_credits"],"description":"Resource type limited by this entitlement."},"usageLimitUSD":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["unmanaged"],"description":"This entitlement uses an assignment mechanism not managed by this API."}},"required":["type"]}],"description":"Who receives this entitlement."}},"required":["id","name","type","usageLimitUSD","windowDays","assignment"],"title":"v2.WorkspaceEntitlement"},"description":"All workspace entitlements."}},"required":["entitlements"],"title":"v2.WorkspaceEntitlementsResponse"},"v2.WorkspaceEntitlementResponse":{"type":"object","properties":{"entitlement":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace entitlement."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."},"type":{"type":"string","enum":["paid_credits"],"description":"Resource type limited by this entitlement."},"usageLimitUSD":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["unmanaged"],"description":"This entitlement uses an assignment mechanism not managed by this API."}},"required":["type"]}],"description":"Who receives this entitlement."}},"required":["id","name","type","usageLimitUSD","windowDays","assignment"],"title":"v2.WorkspaceEntitlement","description":"Workspace entitlement."}},"required":["entitlement"],"title":"v2.WorkspaceEntitlementResponse"},"v2.CreateWorkspaceEntitlementBody":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]}],"description":"Who receives this entitlement."}},"required":["name","usageLimitUSD","windowDays","assignment"],"title":"v2.CreateWorkspaceEntitlementBody"},"v2.UpdateWorkspaceEntitlementBody":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]}],"description":"Who receives this entitlement. If provided, this replaces the entitlement assignment; userIDs and workspaceGroupIDs are full replacement lists, not incremental additions."}},"title":"v2.UpdateWorkspaceEntitlementBody"},"v2.WorkspaceModelProviderKeyOpenAIConfig":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig"},"v2.WorkspaceModelProviderKey":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Anthropic API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"OpenAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."},"config":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig"}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt","config"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"SpaceXAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]}],"description":"A workspace model provider (BYOK) key. Inference for a provider uses the workspace key that is currently active for that provider."},"v2.WorkspaceModelProviderKeysResponse":{"type":"object","properties":{"modelProviderKeys":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Anthropic API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"OpenAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."},"config":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig"}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt","config"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"SpaceXAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]}],"description":"A workspace model provider (BYOK) key. Inference for a provider uses the workspace key that is currently active for that provider."},"description":"All workspace model provider keys."}},"required":["modelProviderKeys"],"title":"v2.WorkspaceModelProviderKeysResponse"},"v2.WorkspaceModelProviderKeyResponse":{"type":"object","properties":{"modelProviderKey":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Anthropic API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"OpenAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."},"config":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig"}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt","config"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"SpaceXAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]}],"description":"Workspace model provider key."}},"required":["modelProviderKey"],"title":"v2.WorkspaceModelProviderKeyResponse"},"v2.CreateWorkspaceModelProviderKeyBody":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"apiKey":{"type":"string","minLength":1,"maxLength":8192,"description":"Provider API key secret. Stored encrypted and never returned by this API."},"active":{"type":"boolean","default":false,"description":"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."}},"required":["provider","name","apiKey"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Create an Anthropic API key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"apiKey":{"type":"string","minLength":1,"maxLength":8192,"description":"Provider API key secret. Stored encrypted and never returned by this API."},"active":{"type":"boolean","default":false,"description":"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."}},"required":["provider","name","apiKey"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"Create an OpenAI API key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"apiKey":{"type":"string","minLength":1,"maxLength":8192,"description":"Provider API key secret. Stored encrypted and never returned by this API."},"active":{"type":"boolean","default":false,"description":"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":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig","description":"OpenAI-specific configuration. Defaults to the global region."}},"required":["provider","name","apiKey"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"Create a SpaceXAI API key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"apiKey":{"type":"string","minLength":1,"maxLength":8192,"description":"Provider API key secret. Stored encrypted and never returned by this API."},"active":{"type":"boolean","default":false,"description":"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."}},"required":["provider","name","apiKey"]}],"title":"v2.CreateWorkspaceModelProviderKeyBody"},"v2.UpdateWorkspaceModelProviderKeyBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"active":{"type":"boolean","description":"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":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig","description":"Provider-specific configuration. Only supported for openai keys."}},"title":"v2.UpdateWorkspaceModelProviderKeyBody"},"v2.UsageMetrics":{"type":"object","properties":{"linesAdded":{"type":"number","description":"Lines added by the user"},"linesDeleted":{"type":"number","description":"Lines deleted by the user"},"linesModified":{"type":"number","description":"Lines modified by the user"},"usage":{"type":"number","description":"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."},"orbUsage":{"type":"number","description":"Workspace-attributed orb usage for the user on that day (USD). Included in usage; not included in models."},"toolUsage":{"type":"number","description":"Workspace-attributed tool usage for the user on that day (USD). Included in usage; not included in models."},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["linesAdded","linesDeleted","linesModified","usage","orbUsage","toolUsage","estimatedProviderCostAtListPriceUSD"],"title":"v2.UsageMetrics"},"v2.DailyUsageModelRequests":{"type":"object","additionalProperties":{"type":"object","properties":{"requests":{"type":"number","description":"Number of requests for the model"},"inputTokens":{"type":"number","description":"Total uncached input tokens consumed by the model for this user/day"},"outputTokens":{"type":"number","description":"Total output tokens consumed by the model for this user/day"},"cacheReadInputTokens":{"type":"number","description":"Total cache-read input tokens consumed by the model for this user/day"},"cacheCreationInputTokens":{"type":"number","description":"Total cache-creation input tokens consumed by the model for this user/day"},"totalTokens":{"type":"number","description":"Total tokens consumed by the model for this user/day"},"usage":{"type":"number","description":"Usage for this model (USD)"},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"EXPERIMENTAL. Estimated USD cost of bring-your-own-key (BYOK) inference for this model for this user/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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["requests","inputTokens","outputTokens","cacheReadInputTokens","cacheCreationInputTokens","totalTokens","usage","estimatedProviderCostAtListPriceUSD"],"description":"Request and token metrics for a model"},"description":"Map of provider/model identifiers to request and token metrics for the user","title":"v2.DailyUsageModelRequests"},"v2.DailyUsageUserObject":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","format":"email","description":"User email - only returned if the client has the \"amp.api:workspace.members:read\" scope"}},"required":["id"],"title":"v2.DailyUsageUserObject"},"v2.DailyUsageUserEntry":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","format":"email","description":"User email - only returned if the client has the \"amp.api:workspace.members:read\" scope"}},"required":["id"],"title":"v2.DailyUsageUserObject","description":"User information"},"metrics":{"type":"object","properties":{"linesAdded":{"type":"number","description":"Lines added by the user"},"linesDeleted":{"type":"number","description":"Lines deleted by the user"},"linesModified":{"type":"number","description":"Lines modified by the user"},"usage":{"type":"number","description":"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."},"orbUsage":{"type":"number","description":"Workspace-attributed orb usage for the user on that day (USD). Included in usage; not included in models."},"toolUsage":{"type":"number","description":"Workspace-attributed tool usage for the user on that day (USD). Included in usage; not included in models."},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["linesAdded","linesDeleted","linesModified","usage","orbUsage","toolUsage","estimatedProviderCostAtListPriceUSD"],"title":"v2.UsageMetrics","description":"Usage metrics for the user"},"models":{"type":"object","additionalProperties":{"type":"object","properties":{"requests":{"type":"number","description":"Number of requests for the model"},"inputTokens":{"type":"number","description":"Total uncached input tokens consumed by the model for this user/day"},"outputTokens":{"type":"number","description":"Total output tokens consumed by the model for this user/day"},"cacheReadInputTokens":{"type":"number","description":"Total cache-read input tokens consumed by the model for this user/day"},"cacheCreationInputTokens":{"type":"number","description":"Total cache-creation input tokens consumed by the model for this user/day"},"totalTokens":{"type":"number","description":"Total tokens consumed by the model for this user/day"},"usage":{"type":"number","description":"Usage for this model (USD)"},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"EXPERIMENTAL. Estimated USD cost of bring-your-own-key (BYOK) inference for this model for this user/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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["requests","inputTokens","outputTokens","cacheReadInputTokens","cacheCreationInputTokens","totalTokens","usage","estimatedProviderCostAtListPriceUSD"],"description":"Request and token metrics for a model"},"description":"Per-model request and token counts for the user","title":"v2.DailyUsageModelRequests"},"orbs":{"type":"array","items":{"type":"object","properties":{"size":{"type":["string","null"],"description":"Orb size, such as \"a1.medium\", or null when the CPU and memory match no current orb size"},"cpuCount":{"type":["number","null"],"description":"vCPUs of the orb, or null if unknown"},"memoryMB":{"type":["number","null"],"description":"Memory of the orb in MB, or null if unknown"},"runtimeMs":{"type":"number","description":"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."},"usage":{"type":"number","description":"Orb usage (USD), counted the same way as the enclosing usage total"}},"required":["size","cpuCount","memoryMB","runtimeMs","usage"],"title":"v2.OrbUsage","description":"Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total."},"description":"Workspace-attributed orb runtime and usage for the user by orb size, largest usage first"},"tools":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","description":"Tool name, such as \"web_search\" or \"read_web_page\""},"calls":{"type":"number","description":"Number of charged calls, whichever credits paid for them, including calls that cost nothing"},"usage":{"type":"number","description":"Tool usage (USD), counted the same way as the enclosing usage total"}},"required":["tool","calls","usage"],"title":"v2.ToolUsage","description":"Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total."},"description":"Workspace-attributed tool calls and usage for the user by tool, largest usage first"}},"required":["user","metrics","models","orbs","tools"],"title":"v2.DailyUsageUserEntry"},"v2.DailyUsageDay":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date in YYYY-MM-DD format"},"users":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","format":"email","description":"User email - only returned if the client has the \"amp.api:workspace.members:read\" scope"}},"required":["id"],"title":"v2.DailyUsageUserObject","description":"User information"},"metrics":{"type":"object","properties":{"linesAdded":{"type":"number","description":"Lines added by the user"},"linesDeleted":{"type":"number","description":"Lines deleted by the user"},"linesModified":{"type":"number","description":"Lines modified by the user"},"usage":{"type":"number","description":"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."},"orbUsage":{"type":"number","description":"Workspace-attributed orb usage for the user on that day (USD). Included in usage; not included in models."},"toolUsage":{"type":"number","description":"Workspace-attributed tool usage for the user on that day (USD). Included in usage; not included in models."},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["linesAdded","linesDeleted","linesModified","usage","orbUsage","toolUsage","estimatedProviderCostAtListPriceUSD"],"title":"v2.UsageMetrics","description":"Usage metrics for the user"},"models":{"type":"object","additionalProperties":{"type":"object","properties":{"requests":{"type":"number","description":"Number of requests for the model"},"inputTokens":{"type":"number","description":"Total uncached input tokens consumed by the model for this user/day"},"outputTokens":{"type":"number","description":"Total output tokens consumed by the model for this user/day"},"cacheReadInputTokens":{"type":"number","description":"Total cache-read input tokens consumed by the model for this user/day"},"cacheCreationInputTokens":{"type":"number","description":"Total cache-creation input tokens consumed by the model for this user/day"},"totalTokens":{"type":"number","description":"Total tokens consumed by the model for this user/day"},"usage":{"type":"number","description":"Usage for this model (USD)"},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"EXPERIMENTAL. Estimated USD cost of bring-your-own-key (BYOK) inference for this model for this user/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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["requests","inputTokens","outputTokens","cacheReadInputTokens","cacheCreationInputTokens","totalTokens","usage","estimatedProviderCostAtListPriceUSD"],"description":"Request and token metrics for a model"},"description":"Per-model request and token counts for the user","title":"v2.DailyUsageModelRequests"},"orbs":{"type":"array","items":{"type":"object","properties":{"size":{"type":["string","null"],"description":"Orb size, such as \"a1.medium\", or null when the CPU and memory match no current orb size"},"cpuCount":{"type":["number","null"],"description":"vCPUs of the orb, or null if unknown"},"memoryMB":{"type":["number","null"],"description":"Memory of the orb in MB, or null if unknown"},"runtimeMs":{"type":"number","description":"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."},"usage":{"type":"number","description":"Orb usage (USD), counted the same way as the enclosing usage total"}},"required":["size","cpuCount","memoryMB","runtimeMs","usage"],"title":"v2.OrbUsage","description":"Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total."},"description":"Workspace-attributed orb runtime and usage for the user by orb size, largest usage first"},"tools":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","description":"Tool name, such as \"web_search\" or \"read_web_page\""},"calls":{"type":"number","description":"Number of charged calls, whichever credits paid for them, including calls that cost nothing"},"usage":{"type":"number","description":"Tool usage (USD), counted the same way as the enclosing usage total"}},"required":["tool","calls","usage"],"title":"v2.ToolUsage","description":"Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total."},"description":"Workspace-attributed tool calls and usage for the user by tool, largest usage first"}},"required":["user","metrics","models","orbs","tools"],"title":"v2.DailyUsageUserEntry"},"description":"Usage data for users in scope for the period, including users no longer in the workspace if they have usage attributed to this workspace"}},"required":["date","users"],"title":"v2.DailyUsageDay"},"v2.DailyUsageMetadata":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date of the period"},"endDate":{"type":"string","format":"date","description":"End date of the period"},"activeUsers":{"type":"number","description":"Users with non-zero usage in the period"},"totalUsers":{"type":"number","description":"Total distinct users represented in the period, including former members with workspace-attributed usage"},"totalUsage":{"type":"number","description":"Total usage in the period (USD), including orb and tool usage"},"totalOrbUsage":{"type":"number","description":"Total orb usage in the period (USD)"},"totalToolUsage":{"type":"number","description":"Total tool usage in the period (USD)"}},"required":["startDate","endDate","activeUsers","totalUsers","totalUsage","totalOrbUsage","totalToolUsage"],"title":"v2.DailyUsageMetadata"},"v2.DailyUsageResponse":{"type":"object","properties":{"metadata":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date of the period"},"endDate":{"type":"string","format":"date","description":"End date of the period"},"activeUsers":{"type":"number","description":"Users with non-zero usage in the period"},"totalUsers":{"type":"number","description":"Total distinct users represented in the period, including former members with workspace-attributed usage"},"totalUsage":{"type":"number","description":"Total usage in the period (USD), including orb and tool usage"},"totalOrbUsage":{"type":"number","description":"Total orb usage in the period (USD)"},"totalToolUsage":{"type":"number","description":"Total tool usage in the period (USD)"}},"required":["startDate","endDate","activeUsers","totalUsers","totalUsage","totalOrbUsage","totalToolUsage"],"title":"v2.DailyUsageMetadata","description":"Metadata about the usage period"},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date in YYYY-MM-DD format"},"users":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","format":"email","description":"User email - only returned if the client has the \"amp.api:workspace.members:read\" scope"}},"required":["id"],"title":"v2.DailyUsageUserObject","description":"User information"},"metrics":{"type":"object","properties":{"linesAdded":{"type":"number","description":"Lines added by the user"},"linesDeleted":{"type":"number","description":"Lines deleted by the user"},"linesModified":{"type":"number","description":"Lines modified by the user"},"usage":{"type":"number","description":"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."},"orbUsage":{"type":"number","description":"Workspace-attributed orb usage for the user on that day (USD). Included in usage; not included in models."},"toolUsage":{"type":"number","description":"Workspace-attributed tool usage for the user on that day (USD). Included in usage; not included in models."},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["linesAdded","linesDeleted","linesModified","usage","orbUsage","toolUsage","estimatedProviderCostAtListPriceUSD"],"title":"v2.UsageMetrics","description":"Usage metrics for the user"},"models":{"type":"object","additionalProperties":{"type":"object","properties":{"requests":{"type":"number","description":"Number of requests for the model"},"inputTokens":{"type":"number","description":"Total uncached input tokens consumed by the model for this user/day"},"outputTokens":{"type":"number","description":"Total output tokens consumed by the model for this user/day"},"cacheReadInputTokens":{"type":"number","description":"Total cache-read input tokens consumed by the model for this user/day"},"cacheCreationInputTokens":{"type":"number","description":"Total cache-creation input tokens consumed by the model for this user/day"},"totalTokens":{"type":"number","description":"Total tokens consumed by the model for this user/day"},"usage":{"type":"number","description":"Usage for this model (USD)"},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"EXPERIMENTAL. Estimated USD cost of bring-your-own-key (BYOK) inference for this model for this user/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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["requests","inputTokens","outputTokens","cacheReadInputTokens","cacheCreationInputTokens","totalTokens","usage","estimatedProviderCostAtListPriceUSD"],"description":"Request and token metrics for a model"},"description":"Per-model request and token counts for the user","title":"v2.DailyUsageModelRequests"},"orbs":{"type":"array","items":{"type":"object","properties":{"size":{"type":["string","null"],"description":"Orb size, such as \"a1.medium\", or null when the CPU and memory match no current orb size"},"cpuCount":{"type":["number","null"],"description":"vCPUs of the orb, or null if unknown"},"memoryMB":{"type":["number","null"],"description":"Memory of the orb in MB, or null if unknown"},"runtimeMs":{"type":"number","description":"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."},"usage":{"type":"number","description":"Orb usage (USD), counted the same way as the enclosing usage total"}},"required":["size","cpuCount","memoryMB","runtimeMs","usage"],"title":"v2.OrbUsage","description":"Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total."},"description":"Workspace-attributed orb runtime and usage for the user by orb size, largest usage first"},"tools":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","description":"Tool name, such as \"web_search\" or \"read_web_page\""},"calls":{"type":"number","description":"Number of charged calls, whichever credits paid for them, including calls that cost nothing"},"usage":{"type":"number","description":"Tool usage (USD), counted the same way as the enclosing usage total"}},"required":["tool","calls","usage"],"title":"v2.ToolUsage","description":"Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total."},"description":"Workspace-attributed tool calls and usage for the user by tool, largest usage first"}},"required":["user","metrics","models","orbs","tools"],"title":"v2.DailyUsageUserEntry"},"description":"Usage data for users in scope for the period, including users no longer in the workspace if they have usage attributed to this workspace"}},"required":["date","users"],"title":"v2.DailyUsageDay"},"description":"Daily usage data for each day in the period"}},"required":["metadata","data"],"title":"v2.DailyUsageResponse","description":"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."},"v2.InferenceModel":{"type":"object","properties":{"id":{"type":"string","description":"Model ID to pass as model to the endpoint for its kind: POST /api/v2/inference for text, POST /api/v2/inference/embeddings for embedding, and POST /api/v2/inference/decisions for decision."},"kind":{"type":"string","enum":["text","embedding","decision"],"description":"What the model does: generate text, embed text, or answer typed decision questions."},"displayName":{"type":"string"},"providerName":{"type":"string","description":"Name of the company that makes the model."},"contextWindow":{"type":"integer","description":"Maximum input tokens, plus output tokens for text models."},"maxOutputTokens":{"type":["integer","null"],"description":"Maximum output tokens for text models; null for other kinds."},"dimensions":{"type":["integer","null"],"description":"Embedding length for embedding models; null for other kinds."},"capabilities":{"type":"object","properties":{"vision":{"type":"boolean","description":"Whether the model reads images. The inference endpoints do not accept images yet."},"reasoning":{"type":"boolean"},"reasoningEfforts":{"type":"array","items":{"type":"string"},"description":"Values reasoningEffort accepts for this model; empty when it takes none."}},"required":["vision","reasoning","reasoningEfforts"]}},"required":["id","kind","displayName","providerName","contextWindow","maxOutputTokens","dimensions","capabilities"],"title":"v2.InferenceModel"},"v2.InferenceModelsResponse":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Model ID to pass as model to the endpoint for its kind: POST /api/v2/inference for text, POST /api/v2/inference/embeddings for embedding, and POST /api/v2/inference/decisions for decision."},"kind":{"type":"string","enum":["text","embedding","decision"],"description":"What the model does: generate text, embed text, or answer typed decision questions."},"displayName":{"type":"string"},"providerName":{"type":"string","description":"Name of the company that makes the model."},"contextWindow":{"type":"integer","description":"Maximum input tokens, plus output tokens for text models."},"maxOutputTokens":{"type":["integer","null"],"description":"Maximum output tokens for text models; null for other kinds."},"dimensions":{"type":["integer","null"],"description":"Embedding length for embedding models; null for other kinds."},"capabilities":{"type":"object","properties":{"vision":{"type":"boolean","description":"Whether the model reads images. The inference endpoints do not accept images yet."},"reasoning":{"type":"boolean"},"reasoningEfforts":{"type":"array","items":{"type":"string"},"description":"Values reasoningEffort accepts for this model; empty when it takes none."}},"required":["vision","reasoning","reasoningEfforts"]}},"required":["id","kind","displayName","providerName","contextWindow","maxOutputTokens","dimensions","capabilities"],"title":"v2.InferenceModel"}}},"required":["models"],"title":"v2.InferenceModelsResponse"},"v2.InferenceRequest":{"type":"object","properties":{"model":{"type":"string","minLength":1,"maxLength":200,"description":"Model ID from GET /api/v2/inference/models, such as gpt-6.1-terra."},"instructions":{"type":"string","maxLength":200000,"description":"System instructions for the model."},"input":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","minLength":1,"maxLength":1000000}},"required":["role","content"]},"minItems":1,"maxItems":200,"description":"Messages, oldest first. Usually one user message."},"maxOutputTokens":{"type":"integer","minimum":16,"maximum":64000,"default":4000,"description":"Maximum tokens to generate, including reasoning tokens."},"reasoningEffort":{"type":"string","description":"One of the model's reasoningEfforts from GET /api/v2/inference/models. Omit for the model's default."},"responseFormat":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["json_schema"]},"name":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,64}$","description":"Name of the schema."},"schema":{"type":"object","additionalProperties":{},"description":"JSON Schema the output must match, in OpenAI strict structured output form: every object lists all of its properties in required and sets additionalProperties to false."}},"required":["type","name","schema"]}],"default":{"type":"text"},"description":"Plain text output, or JSON output that matches a JSON Schema."}},"required":["model","input"],"additionalProperties":false,"title":"v2.InferenceRequest"},"v2.InferenceResponse":{"type":"object","properties":{"model":{"type":"string","description":"Model version that answered, as the provider reports it."},"output":{"type":"string","description":"Generated text. With a json_schema response format, a JSON document."},"incomplete":{"type":"boolean","description":"True when generation stopped early, usually at maxOutputTokens."},"usage":{"type":"object","properties":{"inputTokens":{"type":"integer"},"cachedInputTokens":{"type":"integer"},"outputTokens":{"type":"integer","description":"Output tokens, including reasoning tokens."},"reasoningTokens":{"type":"integer"}},"required":["inputTokens","cachedInputTokens","outputTokens","reasoningTokens"]}},"required":["model","output","incomplete","usage"],"title":"v2.InferenceResponse"},"v2.InferenceEmbeddingsRequest":{"type":"object","properties":{"model":{"type":"string","enum":["text-embedding-3-small","text-embedding-3-large"],"description":"OpenAI embedding model. text-embedding-3-small returns 1536 dimensions and text-embedding-3-large returns 3072, unless dimensions asks for fewer."},"input":{"type":"array","items":{"type":"string","minLength":1,"maxLength":32000},"minItems":1,"maxItems":2048,"description":"Texts to embed, at most 8,192 tokens each and 300,000 tokens in total."},"dimensions":{"type":"integer","minimum":1,"maximum":3072,"description":"Shorten each embedding to this many dimensions. Omit for the model's full size."}},"required":["model","input"],"additionalProperties":false,"title":"v2.InferenceEmbeddingsRequest"},"v2.InferenceEmbeddingsResponse":{"type":"object","properties":{"model":{"type":"string","description":"Model that produced the embeddings, as the provider reports it."},"embeddings":{"type":"array","items":{"type":"array","items":{"type":"number"}},"description":"One embedding per input, in input order. Each has unit length."},"usage":{"type":"object","properties":{"inputTokens":{"type":"integer"}},"required":["inputTokens"]}},"required":["model","embeddings","usage"],"title":"v2.InferenceEmbeddingsResponse"},"v2.InferenceDecisionsRequest":{"type":"object","properties":{"model":{"type":"string","enum":["typesafe/jev","openai/gpt-6-luna"],"default":"typesafe/jev","description":"Decision model. typesafe/jev is TypeSafe's Jev; openai/gpt-6-luna is OpenAI's Decisions API. Keep one model for a use case: their probabilities are calibrated differently."},"state":{"anyOf":[{"type":"string","maxLength":50000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"The content the questions are about, as text or JSON."},"questions":{"type":"object","additionalProperties":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["noul"]},"instructions":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"The yes or no question."},"criteria":{"type":"object","properties":{"true":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"false":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]}},"additionalProperties":false,"description":"What makes the answer true or false."}},"required":["type","instructions"],"additionalProperties":false,"title":"v2.NoulDecisionQuestion","description":"A yes or no question. The answer is the probability that it is true."},{"type":"object","properties":{"type":{"type":"string","enum":["score"]},"instructions":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"What to rate."},"criteria":{"type":"array","items":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"minItems":2,"maxItems":10,"description":"Ordered levels, lowest first."}},"required":["type","instructions","criteria"],"additionalProperties":false,"title":"v2.ScoreDecisionQuestion","description":"A rating on an ordered scale. The answer is the expected level index."},{"type":"object","properties":{"type":{"type":"string","enum":["choice"]},"instructions":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"What to choose."},"criteria":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]},"description":"2 to 20 options, each mapped to a description or null."}},"required":["type","instructions","criteria"],"additionalProperties":false,"title":"v2.ChoiceDecisionQuestion","description":"A pick of one option. The answer is the chosen option."}]},"description":"1 to 20 questions under keys you choose. Answers use the same keys."}},"required":["state","questions"],"additionalProperties":false,"title":"v2.InferenceDecisionsRequest"},"v2.InferenceDecisionAnswer":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["noul"]},"noul":{"type":"number","description":"Probability, from 0 to 1, that the answer is true."}},"required":["type","noul"]},{"type":"object","properties":{"type":{"type":"string","enum":["score"]},"score":{"type":"number","description":"Expected level index, from 0 to the number of levels minus 1."},"legend":{"type":"object","additionalProperties":{"type":"string"},"description":"Level index to level text."},"probabilities":{"type":"object","additionalProperties":{"type":"number"},"description":"Probability of each option or level, summing to 1."},"confidence":{"type":"number"}},"required":["type","score","legend","probabilities","confidence"]},{"type":"object","properties":{"type":{"type":"string","enum":["choice"]},"choice":{"type":"string"},"probabilities":{"type":"object","additionalProperties":{"type":"number"},"description":"Probability of each option or level, summing to 1."},"confidence":{"type":"number"}},"required":["type","choice","probabilities","confidence"]}],"title":"v2.InferenceDecisionAnswer"},"v2.InferenceDecisionsResponse":{"type":"object","properties":{"model":{"type":"string","description":"Model version that answered, as the provider reports it."},"answers":{"type":"object","additionalProperties":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["noul"]},"noul":{"type":"number","description":"Probability, from 0 to 1, that the answer is true."}},"required":["type","noul"]},{"type":"object","properties":{"type":{"type":"string","enum":["score"]},"score":{"type":"number","description":"Expected level index, from 0 to the number of levels minus 1."},"legend":{"type":"object","additionalProperties":{"type":"string"},"description":"Level index to level text."},"probabilities":{"type":"object","additionalProperties":{"type":"number"},"description":"Probability of each option or level, summing to 1."},"confidence":{"type":"number"}},"required":["type","score","legend","probabilities","confidence"]},{"type":"object","properties":{"type":{"type":"string","enum":["choice"]},"choice":{"type":"string"},"probabilities":{"type":"object","additionalProperties":{"type":"number"},"description":"Probability of each option or level, summing to 1."},"confidence":{"type":"number"}},"required":["type","choice","probabilities","confidence"]}],"title":"v2.InferenceDecisionAnswer"},"description":"One answer per question, under the question keys."}},"required":["model","answers"],"title":"v2.InferenceDecisionsResponse"}},"parameters":{}},"paths":{"/api/v2/actor":{"get":{"summary":"Get Actor","description":"Return the authenticated actor ID, type, and Amp permission scopes granted to the presented credential. Does not return workspace data. Sign in with Amp OIDC ID tokens are not accepted; send the OAuth access token. Scopes do not grant access beyond current resource permissions.","operationId":"v2_actor_get","tags":["Meta"],"security":[{"v2.OAuth2AppAuth":[]},{"v2.SignInWithAmpOAuth":["openid","profile","email"]},{"v2.PersonalAccessToken":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"actor":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["m2m"],"description":"Authentication actor type."},"id":{"type":"string","description":"WorkOS OAuth2 client ID from the access token subject."},"scopes":{"type":"array","items":{"type":"string"},"description":"Amp permission scopes granted to the presented credential."}},"required":["type","id","scopes"],"title":"v2.M2MActorIdentity"},{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"Authentication actor type."},"id":{"type":"string","description":"Amp user ID from the access token subject."},"scopes":{"type":"array","items":{"type":"string"},"description":"Amp permission scopes granted to the presented credential."}},"required":["type","id","scopes"],"title":"v2.UserActorIdentity"}],"title":"v2.ActorIdentity"}},"required":["actor"],"title":"v2.ActorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/threads":{"get":{"description":"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.","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:threads.meta:read"]},{"v2.SignInWithAmpOAuth":["amp.api:threads.meta:read"]}],"operationId":"v2_workspace_threads_list","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":4096},"required":false,"description":"Cursor for pagination to get the next set of results.","name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Search query to filter threads by content. A Sign in with Amp access token needs the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope to search.","name":"query","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[^/\\s]+\\/[^/\\s]+$"}]},"required":false,"description":"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.","name":"project","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"description":"Only include threads where the thread's initial sync time is after this date (ISO 8601 format). Not allowed with `orderBy=updatedAt`.","name":"after","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"description":"Only include threads where the thread's initial sync time is before this date (ISO 8601 format). Not allowed with `orderBy=updatedAt`.","name":"before","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"description":"Only include threads last updated after this date (ISO 8601 format). Requires `orderBy=updatedAt`.","name":"updatedAfter","in":"query"},{"schema":{"type":"string","enum":["firstSyncedAt","updatedAt"]},"required":false,"description":"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`.","name":"orderBy","in":"query"},{"schema":{"type":"string","enum":["ASC","DESC"]},"required":false,"description":"Sort order for results. ASC = oldest first (default), DESC = newest first.","name":"sort","in":"query"},{"schema":{"type":"string","enum":["private","group_shared","workspace_shared","public_unlisted"]},"required":false,"description":"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.","name":"visibility","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Comma-separated thread field names to return, such as `title,updatedAt,stats`; `id` is always returned. A field the credential cannot read stays absent. Unknown names return `400`.","name":"fields","in":"query"},{"schema":{"type":"string","format":"email"},"required":false,"description":"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`.","name":"userEmail","in":"query"},{"schema":{"type":"string"},"required":false,"description":"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.","name":"userID","in":"query"}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"threads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"createdAt":{"type":"string","format":"date-time","description":"When the thread was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"firstSyncedAt":{"type":"string","format":"date-time","description":"When the thread was first synced."},"creatorUserID":{"type":"string","description":"User ID of the thread creator."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"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."},"stats":{"type":"object","properties":{"messageCount":{"type":"integer","description":"Number of messages in the thread, counting user messages, assistant messages, and tool results."},"userMessageCount":{"type":"integer","description":"Number of user messages with text or an image, not counting tool results. Includes messages that other threads, plugins, or automations sent to the thread. May be 0 for old threads."},"lastUserMessageAt":{"type":"string","format":"date-time","description":"When the last user message was sent, not counting messages that another thread sent. Unset if the thread has none."}},"required":["messageCount","userMessageCount"],"title":"v2.ThreadStats","description":"Message counts of the thread."},"pinned":{"type":"boolean","description":"Whether the user of a personal access token or Sign in with Amp access token pinned the thread. Unset for M2M clients."},"unread":{"type":"boolean","description":"Whether the thread’s latest reply is unread by its owner, as the Amp app’s thread lists show it. Only returned to the owner, through a personal access token or Sign in with Amp access token, and only once the thread has a reply."},"lastReadAt":{"type":"string","format":"date-time","description":"When the owner read the thread’s latest reply. Only returned to the owner, through a personal access token or Sign in with Amp access token; unset while the reply is unread or there is none."},"hostname":{"type":"string","description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"mainThreadID":{"type":"string","description":"ID of the main thread, if this is a sub-thread"},"parentThreadID":{"type":"string","description":"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":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"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":{"type":"string","description":"The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository."}},"required":["url"],"title":"v2.Repository"},"description":"Repositories in which this thread started working. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"labels":{"type":"array","items":{"type":"string"},"description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"subThreads":{"type":"array","description":"Sub-threads belonging to this thread.","items":{"$ref":"#/components/schemas/v2.Thread"}}},"required":["id","creatorUserID"],"title":"v2.Thread","description":"A conversation thread in Amp"},"description":"Array of threads matching the query"}},"required":["threads"],"title":"v2.ThreadListResponse","description":"Response model for thread list operations"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing scope(s), or a Sign in with Amp application or user without access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/threads":{"get":{"description":"Identical to List Workspace Threads (`GET /api/v2/workspace/threads`); use that endpoint instead.","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:threads.meta:read"]},{"v2.SignInWithAmpOAuth":["amp.api:threads.meta:read"]}],"operationId":"v2_threads_list","deprecated":true,"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":4096},"required":false,"description":"Cursor for pagination to get the next set of results.","name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Search query to filter threads by content. A Sign in with Amp access token needs the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope to search.","name":"query","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[^/\\s]+\\/[^/\\s]+$"}]},"required":false,"description":"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.","name":"project","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"description":"Only include threads where the thread's initial sync time is after this date (ISO 8601 format). Not allowed with `orderBy=updatedAt`.","name":"after","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"description":"Only include threads where the thread's initial sync time is before this date (ISO 8601 format). Not allowed with `orderBy=updatedAt`.","name":"before","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"description":"Only include threads last updated after this date (ISO 8601 format). Requires `orderBy=updatedAt`.","name":"updatedAfter","in":"query"},{"schema":{"type":"string","enum":["firstSyncedAt","updatedAt"]},"required":false,"description":"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`.","name":"orderBy","in":"query"},{"schema":{"type":"string","enum":["ASC","DESC"]},"required":false,"description":"Sort order for results. ASC = oldest first (default), DESC = newest first.","name":"sort","in":"query"},{"schema":{"type":"string","enum":["private","group_shared","workspace_shared","public_unlisted"]},"required":false,"description":"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.","name":"visibility","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Comma-separated thread field names to return, such as `title,updatedAt,stats`; `id` is always returned. A field the credential cannot read stays absent. Unknown names return `400`.","name":"fields","in":"query"},{"schema":{"type":"string","format":"email"},"required":false,"description":"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`.","name":"userEmail","in":"query"},{"schema":{"type":"string"},"required":false,"description":"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.","name":"userID","in":"query"}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"threads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"createdAt":{"type":"string","format":"date-time","description":"When the thread was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"firstSyncedAt":{"type":"string","format":"date-time","description":"When the thread was first synced."},"creatorUserID":{"type":"string","description":"User ID of the thread creator."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"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."},"stats":{"type":"object","properties":{"messageCount":{"type":"integer","description":"Number of messages in the thread, counting user messages, assistant messages, and tool results."},"userMessageCount":{"type":"integer","description":"Number of user messages with text or an image, not counting tool results. Includes messages that other threads, plugins, or automations sent to the thread. May be 0 for old threads."},"lastUserMessageAt":{"type":"string","format":"date-time","description":"When the last user message was sent, not counting messages that another thread sent. Unset if the thread has none."}},"required":["messageCount","userMessageCount"],"title":"v2.ThreadStats","description":"Message counts of the thread."},"pinned":{"type":"boolean","description":"Whether the user of a personal access token or Sign in with Amp access token pinned the thread. Unset for M2M clients."},"unread":{"type":"boolean","description":"Whether the thread’s latest reply is unread by its owner, as the Amp app’s thread lists show it. Only returned to the owner, through a personal access token or Sign in with Amp access token, and only once the thread has a reply."},"lastReadAt":{"type":"string","format":"date-time","description":"When the owner read the thread’s latest reply. Only returned to the owner, through a personal access token or Sign in with Amp access token; unset while the reply is unread or there is none."},"hostname":{"type":"string","description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"mainThreadID":{"type":"string","description":"ID of the main thread, if this is a sub-thread"},"parentThreadID":{"type":"string","description":"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":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"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":{"type":"string","description":"The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository."}},"required":["url"],"title":"v2.Repository"},"description":"Repositories in which this thread started working. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"labels":{"type":"array","items":{"type":"string"},"description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"subThreads":{"type":"array","description":"Sub-threads belonging to this thread.","items":{"$ref":"#/components/schemas/v2.Thread"}}},"required":["id","creatorUserID"],"title":"v2.Thread","description":"A conversation thread in Amp"},"description":"Array of threads matching the query"}},"required":["threads"],"title":"v2.ThreadListResponse","description":"Response model for thread list operations"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing scope(s), or a Sign in with Amp application or user without access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"post":{"summary":"Create Thread","description":"Start a thread in a project and send its first user message. Requires a personal access token with the amp.api:threads:write scope; M2M and Sign in with Amp tokens cannot create threads. For an M2M client, that scope allows deleting threads instead. 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.","operationId":"v2_threads_create","tags":["Threads"],"security":[{"v2.PersonalAccessToken":[]}],"parameters":[{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^[^/\\s]+\\/[^/\\s]+$"}],"description":"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."},"message":{"type":"string","minLength":1,"maxLength":1000000,"description":"Text of the first user message. The agent starts working on it immediately."},"agentMode":{"type":"string","minLength":1,"maxLength":128,"description":"Agent mode key, such as medium. Must be a mode the token owner can use in the project. Omit for the default mode."},"title":{"type":"string","minLength":1,"maxLength":256,"description":"Thread title. Omit to let Amp generate one from the conversation."},"labels":{"type":"array","items":{"type":"string","minLength":1},"description":"Labels to attach to the thread, at most 20. Names are lowercased and must be alphanumeric with hyphens."}},"required":["project","message"],"additionalProperties":false,"title":"v2.CreateThreadRequest"}}}},"responses":{"201":{"description":"Thread created","content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"url":{"type":"string","format":"uri","description":"URL of the thread in the Amp web app."},"agentMode":{"type":"string","description":"Agent mode key the thread runs."}},"required":["id","url","agentMode"],"title":"v2.CreatedThread"}},"required":["thread"],"title":"v2.CreateThreadResponse"}}}},"400":{"description":"Invalid request body, or an agent mode or label that cannot be used","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"402":{"description":"The token owner is out of credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.api:threads:write, or a workspace policy does not let the token start an orb","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project not found, or the token owner cannot use it","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"429":{"description":"The token owner created more than 100 threads in the current minute","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/threads/events":{"get":{"summary":"Stream Thread List Changes","description":"Streams live changes to the threads that `GET /api/v2/workspace/threads` lists for a Sign in with Amp access token, as Server-Sent Events (`text/event-stream`), so an application can keep its list current without polling. Each stream starts with a `thread` event for every thread in its snapshot, then `ready`, then a `thread` event whenever a thread is created or its title, agent state, archived state, or read state changes. It covers the user’s own threads updated in the last 24 hours, in the threads the list would return, and not threads that others shared with the user; list those with `GET /api/v2/workspace/threads`. The server closes each stream after about 60 seconds so access is checked again; reconnect and merge the new snapshot. This is experimental and has the same access requirements as listing with a Sign in with Amp token.","operationId":"v2_threads_events","tags":["Threads"],"security":[{"v2.SignInWithAmpOAuth":["amp.api:threads.meta:read"]}],"responses":{"200":{"description":"A stream of thread list events.","content":{"text/event-stream":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["thread"]},"thread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"What the thread’s agent is doing now. Unlike the list, this does not trail the agent."},"unread":{"type":"boolean","description":"Whether the thread has an assistant reply the user has not read."}},"required":["id","updatedAt","archived","agentState","unread"],"title":"v2.ThreadListEventThread","description":"The current values of a thread’s fields that change while it runs."}},"required":["type","thread"],"description":"A thread was created or changed, or is in the stream’s first snapshot. Merge it by `id`; an `id` you have not listed is a new thread."},{"type":"object","properties":{"type":{"type":"string","enum":["ready"]}},"required":["type"],"description":"The first snapshot is complete; later `thread` events are changes."},{"type":"object","properties":{"type":{"type":"string","enum":["heartbeat"]}},"required":["type"],"description":"Sent every 15 seconds."}],"title":"v2.ThreadListEvent","description":"One Server-Sent Event of `GET /api/v2/workspace/threads/events`, sent as `data: <JSON>`."}}}},"401":{"description":"Unauthorized, or the credential is not a Sign in with Amp access token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing scope(s), or a Sign in with Amp application or user without access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/user/threads":{"get":{"summary":"List User Threads","description":"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:read scope; M2M clients list a workspace's threads with `GET /api/v2/workspace/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`.","operationId":"v2_user_threads_list","tags":["Threads"],"security":[{"v2.PersonalAccessToken":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":4096},"required":false,"description":"Cursor for pagination to get the next set of results.","name":"cursor","in":"query"}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"threads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"createdAt":{"type":"string","format":"date-time","description":"When the thread was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"firstSyncedAt":{"type":"string","format":"date-time","description":"When the thread was first synced."},"creatorUserID":{"type":"string","description":"User ID of the thread creator."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"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."},"stats":{"type":"object","properties":{"messageCount":{"type":"integer","description":"Number of messages in the thread, counting user messages, assistant messages, and tool results."},"userMessageCount":{"type":"integer","description":"Number of user messages with text or an image, not counting tool results. Includes messages that other threads, plugins, or automations sent to the thread. May be 0 for old threads."},"lastUserMessageAt":{"type":"string","format":"date-time","description":"When the last user message was sent, not counting messages that another thread sent. Unset if the thread has none."}},"required":["messageCount","userMessageCount"],"title":"v2.ThreadStats","description":"Message counts of the thread."},"pinned":{"type":"boolean","description":"Whether the user of a personal access token or Sign in with Amp access token pinned the thread. Unset for M2M clients."},"unread":{"type":"boolean","description":"Whether the thread’s latest reply is unread by its owner, as the Amp app’s thread lists show it. Only returned to the owner, through a personal access token or Sign in with Amp access token, and only once the thread has a reply."},"lastReadAt":{"type":"string","format":"date-time","description":"When the owner read the thread’s latest reply. Only returned to the owner, through a personal access token or Sign in with Amp access token; unset while the reply is unread or there is none."},"hostname":{"type":"string","description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"mainThreadID":{"type":"string","description":"ID of the main thread, if this is a sub-thread"},"parentThreadID":{"type":"string","description":"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":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"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":{"type":"string","description":"The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository."}},"required":["url"],"title":"v2.Repository"},"description":"Repositories in which this thread started working. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"labels":{"type":"array","items":{"type":"string"},"description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"subThreads":{"type":"array","description":"Sub-threads belonging to this thread.","items":{"$ref":"#/components/schemas/v2.Thread"}}},"required":["id","creatorUserID"],"title":"v2.Thread","description":"A conversation thread in Amp"},"description":"Array of threads matching the query"}},"required":["threads"],"title":"v2.ThreadListResponse","description":"Response model for thread list operations"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized, or the credential is not a personal access token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.api:threads:read","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/threads/{threadID}":{"delete":{"description":"Delete a thread by ID. Requires an M2M client with the 'amp.api:threads:write' scope. Personal access tokens cannot delete threads. For a personal access token, that scope allows creating threads instead.","operationId":"v2_threads_delete","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:threads:write"]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"}],"responses":{"204":{"description":"Thread successfully deleted"},"400":{"description":"Invalid thread ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/experimental/threads/{threadID}":{"patch":{"summary":"Update Thread","description":"EXPERIMENTAL. Requires a Sign in with Amp OAuth access token with the amp.api:threads.meta:write scope, from an application whose creator has access to threads, for a user who has access too. Contact the Amp team for access. The scope acts as the signed-in user, so M2M clients cannot carry it. The thread must be one the user can see in the application's workspace. Rename, label, pin, snooze, archive, or unarchive a thread, as the user would in the Amp app. Only the thread's owner can make these changes.","operationId":"v2_experimental_threads_update","tags":["Threads"],"x-amp-hidden-from-docs":true,"security":[{"v2.SignInWithAmpOAuth":["amp.api:threads.meta:write"]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"},{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":256,"description":"New thread title."},"labels":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string","minLength":1,"maxLength":32},"maxItems":20},"remove":{"type":"array","items":{"type":"string","minLength":1,"maxLength":32},"maxItems":20}},"additionalProperties":false,"description":"Labels to add to and remove from the thread. Names are lowercased and must be alphanumeric with hyphens; a thread has at most 20."},"pinned":{"type":"boolean","description":"Pin or unpin the thread in the user’s thread lists."},"archived":{"type":"boolean","description":"Archive or unarchive the thread."},"snooze":{"anyOf":[{"type":"string","enum":["next_message","one_hour","one_day","one_week","indefinite","off"]},{"type":"object","properties":{"until":{"type":"string","format":"date-time"}},"required":["until"],"additionalProperties":false}],"description":"Hide the thread from the user’s thread lists: until its next message, for an hour, a day, or a week, indefinitely, or until a future time. `off` ends a snooze."}},"additionalProperties":false,"title":"v2.UpdateThreadRequest"}}}},"responses":{"204":{"description":"The thread was updated"},"400":{"description":"Invalid request body, no change requested, or a change the thread does not allow","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.api:threads.meta:write, an application or user without access to threads, or a thread the user does not own","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Thread not found, or the user cannot see it in the application’s workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/experimental/threads/{threadID}/read":{"post":{"summary":"Mark Thread Read","description":"EXPERIMENTAL. Requires a Sign in with Amp OAuth access token with the amp.api:threads.meta:write scope, from an application whose creator has access to threads, for a user who has access too. Contact the Amp team for access. The scope acts as the signed-in user, so M2M clients cannot carry it. The thread must be one the user can see in the application's workspace. Mark a thread the user owns read, as the Amp app's thread lists do. A thread's `unread` and `lastReadAt` can trail the change by a few seconds.","operationId":"v2_experimental_threads_mark_read","tags":["Threads"],"x-amp-hidden-from-docs":true,"security":[{"v2.SignInWithAmpOAuth":["amp.api:threads.meta:write"]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"}],"responses":{"204":{"description":"The thread was marked"},"400":{"description":"Invalid thread ID, or a thread without a thread actor, such as an imported one","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.api:threads.meta:write, an application or user without access to threads, or a thread the user does not own","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Thread not found, or the user cannot see it in the application’s workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/experimental/threads/{threadID}/unread":{"post":{"summary":"Mark Thread Unread","description":"EXPERIMENTAL. Requires a Sign in with Amp OAuth access token with the amp.api:threads.meta:write scope, from an application whose creator has access to threads, for a user who has access too. Contact the Amp team for access. The scope acts as the signed-in user, so M2M clients cannot carry it. The thread must be one the user can see in the application's workspace. Mark a thread the user owns unread, as the Amp app's thread lists do. A thread's `unread` and `lastReadAt` can trail the change by a few seconds.","operationId":"v2_experimental_threads_mark_unread","tags":["Threads"],"x-amp-hidden-from-docs":true,"security":[{"v2.SignInWithAmpOAuth":["amp.api:threads.meta:write"]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"}],"responses":{"204":{"description":"The thread was marked"},"400":{"description":"Invalid thread ID, or a thread without a thread actor, such as an imported one","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.api:threads.meta:write, an application or user without access to threads, or a thread the user does not own","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Thread not found, or the user cannot see it in the application’s workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/threads/{threadID}/metadata":{"get":{"description":"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:read scope, 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>`), and `archived` tells a paused orb whose thread was archived from one whose thread is only idle.","operationId":"v2_threads_metadata_get","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:threads.meta:read"]},{"v2.PersonalAccessToken":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"createdAt":{"type":"string","format":"date-time","description":"When the thread was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"firstSyncedAt":{"type":"string","format":"date-time","description":"When the thread was first synced."},"creatorUserID":{"type":"string","description":"User ID of the thread creator."},"archived":{"type":"boolean","description":"Whether the thread is archived."},"agentState":{"type":"object","properties":{"state":{"type":"string","enum":["working","idle","awaiting_approval","error"],"description":"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."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent reported this state."}},"required":["state","updatedAt"],"title":"v2.ThreadAgentState","description":"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."},"stats":{"type":"object","properties":{"messageCount":{"type":"integer","description":"Number of messages in the thread, counting user messages, assistant messages, and tool results."},"userMessageCount":{"type":"integer","description":"Number of user messages with text or an image, not counting tool results. Includes messages that other threads, plugins, or automations sent to the thread. May be 0 for old threads."},"lastUserMessageAt":{"type":"string","format":"date-time","description":"When the last user message was sent, not counting messages that another thread sent. Unset if the thread has none."}},"required":["messageCount","userMessageCount"],"title":"v2.ThreadStats","description":"Message counts of the thread."},"pinned":{"type":"boolean","description":"Whether the user of a personal access token or Sign in with Amp access token pinned the thread. Unset for M2M clients."},"unread":{"type":"boolean","description":"Whether the thread’s latest reply is unread by its owner, as the Amp app’s thread lists show it. Only returned to the owner, through a personal access token or Sign in with Amp access token, and only once the thread has a reply."},"lastReadAt":{"type":"string","format":"date-time","description":"When the owner read the thread’s latest reply. Only returned to the owner, through a personal access token or Sign in with Amp access token; unset while the reply is unread or there is none."},"hostname":{"type":"string","description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"mainThreadID":{"type":"string","description":"ID of the main thread, if this is a sub-thread"},"parentThreadID":{"type":"string","description":"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":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"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":{"type":"string","description":"The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository."}},"required":["url"],"title":"v2.Repository"},"description":"Repositories in which this thread started working. Only returned if an M2M client or Sign in with Amp access token has the 'amp.api:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"labels":{"type":"array","items":{"type":"string"},"description":"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:threads.contents:read' or 'amp.api:threads:read' scope. A personal access token with the 'amp.api:threads:read' scope always gets it."},"subThreads":{"type":"array","description":"Sub-threads belonging to this thread.","items":{"$ref":"#/components/schemas/v2.Thread"}}},"required":["id","creatorUserID"],"title":"v2.Thread","description":"A conversation thread in Amp"}}}},"400":{"description":"Invalid thread ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Thread not found, or the credential cannot read it","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/threads/{threadID}/messages":{"get":{"description":"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:read scope, and reads the threads its owner sees in their own thread lists.","operationId":"v2_threads_messages_list","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:threads.contents:read"]},{"v2.PersonalAccessToken":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":4096},"required":false,"description":"Cursor for pagination to get the next set of results.","name":"cursor","in":"query"}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"messages":{"type":"array","items":{},"description":"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."}},"required":["messages"],"title":"v2.ThreadMessagesResponse","description":"Response model for thread messages operations."}}}},"400":{"description":"Invalid thread ID or query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Thread not found, or the credential cannot read it","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"post":{"summary":"Post Thread Message","description":"Send a follow-up user message to a thread, which the agent answers with the thread's earlier conversation as context. Requires a personal access token with the amp.api:threads:write scope; M2M and Sign in with Amp tokens cannot post messages. Only the token owner's own orb threads accept it, such as the threads it created with `POST /api/v2/threads`. If the agent is still working, the message waits in the thread's queue and the agent answers it after its current turn, so you need not wait for `idle` before posting. The agent acts as the token owner, with their access, credentials, and Amp credits. The response returns once the thread accepts the message; poll `GET /api/v2/threads/{threadID}/metadata` until `agentState.state` is `idle`, then read the reply after `messageID` in `GET /api/v2/threads/{threadID}/messages`.","operationId":"v2_threads_messages_create","tags":["Threads"],"security":[{"v2.PersonalAccessToken":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"},{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":1000000,"description":"Text of the user message. The agent answers it with the conversation so far as context."}},"required":["message"],"additionalProperties":false,"title":"v2.PostThreadMessageRequest"}}}},"responses":{"202":{"description":"Message accepted; the agent answers it now, or after its current turn","content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"url":{"type":"string","format":"uri","description":"URL of the thread in the Amp web app."}},"required":["id","url"]},"messageID":{"type":"string","description":"ID of the posted message, the same as its `messageID` in `GET /api/v2/threads/{threadID}/messages`. The agent’s reply follows it."}},"required":["thread","messageID"],"title":"v2.PostThreadMessageResponse"}}}},"400":{"description":"Invalid thread ID or request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"402":{"description":"The token owner is out of credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.api:threads:write, or a workspace policy does not let the token start an orb","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Thread not found, or not an orb thread that the token owner owns. Threads shared with the owner are not accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"409":{"description":"The thread is archived","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"429":{"description":"The token owner posted more than 100 messages in the current minute","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/threads/{threadID}/usage":{"get":{"description":"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.","operationId":"v2_threads_usage_get","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:threads.meta:read"]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"threadID":{"type":"string","description":"The thread ID"},"subThreadIDs":{"type":"array","items":{"type":"string"},"description":"Always empty. Kept for compatibility; usage covers only this thread."},"usage":{"type":"number","description":"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."},"orbUsage":{"type":"number","description":"Orb usage of the thread (USD). Included in usage; not included in models."},"toolUsage":{"type":"number","description":"Tool usage of the thread (USD). Included in usage; not included in models."},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."},"orbs":{"type":"array","items":{"type":"object","properties":{"size":{"type":["string","null"],"description":"Orb size, such as \"a1.medium\", or null when the CPU and memory match no current orb size"},"cpuCount":{"type":["number","null"],"description":"vCPUs of the orb, or null if unknown"},"memoryMB":{"type":["number","null"],"description":"Memory of the orb in MB, or null if unknown"},"runtimeMs":{"type":"number","description":"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."},"usage":{"type":"number","description":"Orb usage (USD), counted the same way as the enclosing usage total"}},"required":["size","cpuCount","memoryMB","runtimeMs","usage"],"title":"v2.OrbUsage","description":"Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total."},"description":"Orb runtime and usage of the thread by orb size, largest usage first"},"tools":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","description":"Tool name, such as \"web_search\" or \"read_web_page\""},"calls":{"type":"number","description":"Number of charged calls, whichever credits paid for them, including calls that cost nothing"},"usage":{"type":"number","description":"Tool usage (USD), counted the same way as the enclosing usage total"}},"required":["tool","calls","usage"],"title":"v2.ToolUsage","description":"Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total."},"description":"Tool calls and usage of the thread by tool, largest usage first"},"models":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","description":"Provider identifier for the model usage bucket"},"model":{"type":"string","description":"Model identifier for the model usage bucket"},"requests":{"type":"number","description":"Number of requests for this provider/model"},"inputTokens":{"type":"number","description":"Total uncached input tokens for this provider/model"},"outputTokens":{"type":"number","description":"Total output tokens for this provider/model"},"cacheReadInputTokens":{"type":"number","description":"Total cache-read input tokens for this provider/model"},"cacheCreationInputTokens":{"type":"number","description":"Total cache-creation input tokens for this provider/model"},"usage":{"type":"number","description":"Total cost in USD for this provider/model"},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["provider","model","requests","inputTokens","outputTokens","cacheReadInputTokens","cacheCreationInputTokens","usage","estimatedProviderCostAtListPriceUSD"]},"description":"Per-model usage and cost breakdown for the thread"}},"required":["threadID","subThreadIDs","usage","orbUsage","toolUsage","estimatedProviderCostAtListPriceUSD","orbs","tools","models"],"title":"v2.ThreadCostResponse","description":"Thread usage information"}}}},"400":{"description":"Invalid thread ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Thread not found or usage data not available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/members":{"get":{"description":"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.","operationId":"v2_workspace_members_list","tags":["Workspace"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.members:read"]},{"v2.SignInWithAmpOAuth":["amp.api:workspace.members:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the user"},"name":{"type":"string","description":"Full name of the user"},"email":{"type":"string","format":"email","description":"The primary email address of the user"},"role":{"type":"string","enum":["admin","member"],"description":"Workspace-level role of the user"},"avatarURL":{"type":["string","null"],"format":"uri","description":"Absolute URL of the user’s profile picture, publicly fetchable without credentials, or null when the user has none"}},"required":["id","name","email","role","avatarURL"],"title":"v2.WorkspaceMember"},"description":"All members of the workspace"}},"required":["members"],"title":"v2.WorkspaceMembersResponse","description":"Response for workspace members listing"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing scope(s), or the user may not view the member list of this workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects":{"get":{"summary":"List Projects","description":"List projects owned by the workspace selected by the access token. User-owned projects and projects from other workspaces are not included.","operationId":"v2_workspace_projects_list","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":4096},"required":false,"description":"Cursor for pagination to get the next set of results.","name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"description":"Case-insensitive exact project name to return.","name":"name","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the project."},"name":{"type":"string","description":"Project name."},"namespace":{"type":"string","description":"Project namespace."},"owner":{"type":"object","properties":{"type":{"type":"string","enum":["workspace"]},"id":{"type":"string","format":"uuid","description":"Unique identifier of the workspace that owns the project."},"name":{"type":"string","description":"Name of the workspace that owns the project."}},"required":["type","id","name"],"title":"v2.WorkspaceProjectOwner"},"repository":{"type":"object","properties":{"mode":{"type":"string","enum":["amp-hosted","github","mapped"],"description":"How Amp connects to or hosts the project repository."},"url":{"type":["string","null"],"format":"uri","description":"Credential-free repository URL, or null when no safe public URL is available."}},"required":["mode","url"],"title":"v2.WorkspaceProjectRepository"},"archived":{"type":"boolean","description":"Whether the project is archived. Its threads are archived and read-only, and no thread can be started in it until it is unarchived."}},"required":["id","name","namespace","owner","repository","archived"],"title":"v2.WorkspaceProject"},"description":"Projects owned by the workspace."}},"required":["projects"],"title":"v2.WorkspaceProjectsResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing token scope or project permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspaces/{workspaceID}/projects":{"get":{"summary":"List Workspace Projects","description":"List projects owned by an explicitly selected workspace. The selector must match the workspace selected by the access token.","operationId":"v2_workspaces_projects_list","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace.","name":"workspaceID","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":4096},"required":false,"description":"Cursor for pagination to get the next set of results.","name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"description":"Case-insensitive exact project name to return.","name":"name","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the project."},"name":{"type":"string","description":"Project name."},"namespace":{"type":"string","description":"Project namespace."},"owner":{"type":"object","properties":{"type":{"type":"string","enum":["workspace"]},"id":{"type":"string","format":"uuid","description":"Unique identifier of the workspace that owns the project."},"name":{"type":"string","description":"Name of the workspace that owns the project."}},"required":["type","id","name"],"title":"v2.WorkspaceProjectOwner"},"repository":{"type":"object","properties":{"mode":{"type":"string","enum":["amp-hosted","github","mapped"],"description":"How Amp connects to or hosts the project repository."},"url":{"type":["string","null"],"format":"uri","description":"Credential-free repository URL, or null when no safe public URL is available."}},"required":["mode","url"],"title":"v2.WorkspaceProjectRepository"},"archived":{"type":"boolean","description":"Whether the project is archived. Its threads are archived and read-only, and no thread can be started in it until it is unarchived."}},"required":["id","name","namespace","owner","repository","archived"],"title":"v2.WorkspaceProject"},"description":"Projects owned by the workspace."}},"required":["projects"],"title":"v2.WorkspaceProjectsResponse"}}}},"400":{"description":"Invalid workspace ID or query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing token scope or project permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/{projectID}/repository/commits/search":{"get":{"operationId":"v2_project_repository_commits_search_id","summary":"Search Repository Commits","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectID","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before searching.","name":"ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Substring for commits, regex for content, glob for paths.","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"description":"Repository-relative path prefix.","name":"path","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"type":"string"},"nextCursor":{"type":"string"},"incomplete":{"type":"boolean"},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"message":{"type":"string"},"authorName":{"type":"string"},"authorEmail":{"type":"string"},"committerName":{"type":"string"},"committerEmail":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","message","authorName","authorEmail","committerName","committerEmail","createdAt"]}}},"required":["commit","incomplete","matches"]}}}},"400":{"description":"Invalid query or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project or ref not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"422":{"description":"A repository path exceeds the matching work limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/{projectID}/repository/content/search":{"get":{"operationId":"v2_project_repository_content_search_id","summary":"Search Repository Content","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectID","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before searching.","name":"ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Substring for commits, regex for content, glob for paths.","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"description":"Repository-relative path prefix.","name":"path","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"caseSensitive","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"type":"string"},"nextCursor":{"type":"string"},"incomplete":{"type":"boolean"},"matches":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"lineNumber":{"type":"number"},"text":{"type":"string"},"type":{"type":"string"}},"required":["lineNumber","text","type"]}}},"required":["path","lines"]}},"hasMore":{"type":"boolean"}},"required":["commit","incomplete","matches","hasMore"]}}}},"400":{"description":"Invalid query or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project or ref not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"422":{"description":"A repository path exceeds the matching work limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/{projectID}/repository/paths/search":{"get":{"operationId":"v2_project_repository_paths_search_id","summary":"Search Repository Paths","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectID","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before searching.","name":"ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Substring for commits, regex for content, glob for paths.","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"description":"Repository-relative path prefix.","name":"path","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"type":"string"},"nextCursor":{"type":"string"},"incomplete":{"type":"boolean"},"matches":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"mode":{"type":"string"}},"required":["path","type","mode"]}}},"required":["commit","incomplete","matches"]}}}},"400":{"description":"Invalid query or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project or ref not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"422":{"description":"A repository path exceeds the matching work limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/{projectID}/repository/diff":{"get":{"operationId":"v2_project_repository_diff_id","summary":"Compare Repository Commits","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectID","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Commit, branch, or tag to compare.","name":"ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":false,"description":"Optional base; comparison uses merge-base semantics.","name":"base","in":"query"}],"responses":{"200":{"description":"Diff","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"type":"string"},"base":{"type":["string","null"]},"comparison":{"type":"string","enum":["merge-base","parent"]},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"oldPath":{"type":"string"},"state":{"type":"string"},"additions":{"type":"number"},"deletions":{"type":"number"},"patch":{"type":"string"}},"required":["path","state","additions","deletions","patch"]}},"filteredFiles":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"oldPath":{"type":"string"},"state":{"type":"string"},"rawState":{"type":"string"},"bytes":{"type":"number"},"isEof":{"type":"boolean"}},"required":["path","state","rawState","bytes","isEof"]}},"incomplete":{"type":"boolean","description":"True when filteredFiles contains changed files without patches."}},"required":["commit","base","comparison","files","filteredFiles","incomplete"]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project or ref not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/{projectID}/repository/contents":{"get":{"operationId":"v2_project_repository_contents_root_id","summary":"List Repository Root","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectID","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before reading.","name":"ref","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"description":"List all descendants instead of direct children.","name":"recursive","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project, path, and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"}],"responses":{"200":{"description":"File or directory contents","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["file"]},"commit":{"type":"string"},"path":{"type":"string"},"encoding":{"type":"string","enum":["base64"]},"content":{"type":"string"},"size":{"type":"number"}},"required":["kind","commit","path","encoding","content","size"]},{"type":"object","properties":{"kind":{"type":"string","enum":["directory"]},"commit":{"type":"string"},"entries":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"mode":{"type":"string"}},"required":["path","type","mode"]}},"nextCursor":{"type":"string"}},"required":["kind","commit","entries"]}]}}}},"400":{"description":"Invalid query, path, or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project, ref, or path not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"413":{"description":"File exceeds 1 MiB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/{projectID}/repository/contents/{path}":{"get":{"operationId":"v2_project_repository_contents_path_id","summary":"Get Repository Contents","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectID","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":true,"name":"path","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before reading.","name":"ref","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"description":"List all descendants instead of direct children.","name":"recursive","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project, path, and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"}],"responses":{"200":{"description":"File or directory contents","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["file"]},"commit":{"type":"string"},"path":{"type":"string"},"encoding":{"type":"string","enum":["base64"]},"content":{"type":"string"},"size":{"type":"number"}},"required":["kind","commit","path","encoding","content","size"]},{"type":"object","properties":{"kind":{"type":"string","enum":["directory"]},"commit":{"type":"string"},"entries":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"mode":{"type":"string"}},"required":["path","type","mode"]}},"nextCursor":{"type":"string"}},"required":["kind","commit","entries"]}]}}}},"400":{"description":"Invalid query, path, or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project, ref, or path not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"413":{"description":"File exceeds 1 MiB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/@{namespace}/{name}/repository/commits/search":{"get":{"operationId":"v2_project_repository_commits_search_name","summary":"Search Repository Commits","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","example":"my-workspace"},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._-]+$","example":"my-project"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before searching.","name":"ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Substring for commits, regex for content, glob for paths.","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"description":"Repository-relative path prefix.","name":"path","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"type":"string"},"nextCursor":{"type":"string"},"incomplete":{"type":"boolean"},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"message":{"type":"string"},"authorName":{"type":"string"},"authorEmail":{"type":"string"},"committerName":{"type":"string"},"committerEmail":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","message","authorName","authorEmail","committerName","committerEmail","createdAt"]}}},"required":["commit","incomplete","matches"]}}}},"400":{"description":"Invalid query or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project or ref not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"422":{"description":"A repository path exceeds the matching work limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/@{namespace}/{name}/repository/content/search":{"get":{"operationId":"v2_project_repository_content_search_name","summary":"Search Repository Content","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","example":"my-workspace"},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._-]+$","example":"my-project"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before searching.","name":"ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Substring for commits, regex for content, glob for paths.","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"description":"Repository-relative path prefix.","name":"path","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"caseSensitive","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"type":"string"},"nextCursor":{"type":"string"},"incomplete":{"type":"boolean"},"matches":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"lineNumber":{"type":"number"},"text":{"type":"string"},"type":{"type":"string"}},"required":["lineNumber","text","type"]}}},"required":["path","lines"]}},"hasMore":{"type":"boolean"}},"required":["commit","incomplete","matches","hasMore"]}}}},"400":{"description":"Invalid query or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project or ref not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"422":{"description":"A repository path exceeds the matching work limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/@{namespace}/{name}/repository/paths/search":{"get":{"operationId":"v2_project_repository_paths_search_name","summary":"Search Repository Paths","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","example":"my-workspace"},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._-]+$","example":"my-project"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before searching.","name":"ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Substring for commits, regex for content, glob for paths.","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"description":"Repository-relative path prefix.","name":"path","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"type":"string"},"nextCursor":{"type":"string"},"incomplete":{"type":"boolean"},"matches":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"mode":{"type":"string"}},"required":["path","type","mode"]}}},"required":["commit","incomplete","matches"]}}}},"400":{"description":"Invalid query or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project or ref not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"422":{"description":"A repository path exceeds the matching work limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/@{namespace}/{name}/repository/diff":{"get":{"operationId":"v2_project_repository_diff_name","summary":"Compare Repository Commits","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","example":"my-workspace"},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._-]+$","example":"my-project"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Commit, branch, or tag to compare.","name":"ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":false,"description":"Optional base; comparison uses merge-base semantics.","name":"base","in":"query"}],"responses":{"200":{"description":"Diff","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"type":"string"},"base":{"type":["string","null"]},"comparison":{"type":"string","enum":["merge-base","parent"]},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"oldPath":{"type":"string"},"state":{"type":"string"},"additions":{"type":"number"},"deletions":{"type":"number"},"patch":{"type":"string"}},"required":["path","state","additions","deletions","patch"]}},"filteredFiles":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"oldPath":{"type":"string"},"state":{"type":"string"},"rawState":{"type":"string"},"bytes":{"type":"number"},"isEof":{"type":"boolean"}},"required":["path","state","rawState","bytes","isEof"]}},"incomplete":{"type":"boolean","description":"True when filteredFiles contains changed files without patches."}},"required":["commit","base","comparison","files","filteredFiles","incomplete"]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project or ref not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/@{namespace}/{name}/repository/contents":{"get":{"operationId":"v2_project_repository_contents_root_name","summary":"List Repository Root","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","example":"my-workspace"},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._-]+$","example":"my-project"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before reading.","name":"ref","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"description":"List all descendants instead of direct children.","name":"recursive","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project, path, and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"}],"responses":{"200":{"description":"File or directory contents","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["file"]},"commit":{"type":"string"},"path":{"type":"string"},"encoding":{"type":"string","enum":["base64"]},"content":{"type":"string"},"size":{"type":"number"}},"required":["kind","commit","path","encoding","content","size"]},{"type":"object","properties":{"kind":{"type":"string","enum":["directory"]},"commit":{"type":"string"},"entries":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"mode":{"type":"string"}},"required":["path","type","mode"]}},"nextCursor":{"type":"string"}},"required":["kind","commit","entries"]}]}}}},"400":{"description":"Invalid query, path, or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project, ref, or path not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"413":{"description":"File exceeds 1 MiB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/projects/@{namespace}/{name}/repository/contents/{path}":{"get":{"operationId":"v2_project_repository_contents_path_name","summary":"Get Repository Contents","description":"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.","tags":["Projects"],"security":[{"v2.OAuth2AppAuth":["amp.api:projects:read","amp.git:read"]},{"v2.SignInWithAmpOAuth":["amp.api:projects:read","amp.git:read"]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","example":"my-workspace"},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._-]+$","example":"my-project"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":true,"name":"path","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":true,"description":"Branch, tag, or commit; resolved to a commit before reading.","name":"ref","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"description":"List all descendants instead of direct children.","name":"recursive","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":16384},"required":false,"description":"Opaque continuation cursor. Keep the same project, path, and query. Cursors remain bound to the client. Every request must independently authorize access.","name":"cursor","in":"query"}],"responses":{"200":{"description":"File or directory contents","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["file"]},"commit":{"type":"string"},"path":{"type":"string"},"encoding":{"type":"string","enum":["base64"]},"content":{"type":"string"},"size":{"type":"number"}},"required":["kind","commit","path","encoding","content","size"]},{"type":"object","properties":{"kind":{"type":"string","enum":["directory"]},"commit":{"type":"string"},"entries":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"mode":{"type":"string"}},"required":["path","type","mode"]}},"nextCursor":{"type":"string"}},"required":["kind","commit","entries"]}]}}}},"400":{"description":"Invalid query, path, or cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Missing scope, grant, or repository permission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Project, ref, or path not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"413":{"description":"File exceeds 1 MiB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"Repository pagination unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/groups":{"get":{"description":"List all workspace groups and their members.","operationId":"v2_workspace_groups_list","tags":["Groups"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.groups:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup"},"description":"All groups in the workspace."}},"required":["groups"],"title":"v2.WorkspaceGroupsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"post":{"description":"Create a workspace group. Initial members are removed from any other workspace group.","operationId":"v2_workspace_groups_create","tags":["Groups"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.groups:write"]}],"parameters":[{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMemberEntry"},"maxItems":5000,"default":[],"description":"Initial group members. Listed users are removed from any other workspace group."}},"required":["name"],"title":"v2.CreateWorkspaceGroupBody"}}}},"responses":{"201":{"description":"Workspace group created","content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup","description":"Workspace group."}},"required":["group"],"title":"v2.WorkspaceGroupResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"409":{"description":"Workspace group name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/groups/{groupID}":{"get":{"description":"Get one workspace group and its members.","operationId":"v2_workspace_groups_get","tags":["Groups"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.groups:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace group.","name":"groupID","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup","description":"Workspace group."}},"required":["group"],"title":"v2.WorkspaceGroupResponse"}}}},"400":{"description":"Invalid group ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace group not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"patch":{"description":"Update workspace group metadata.","operationId":"v2_workspace_groups_update","tags":["Groups"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.groups:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace group.","name":"groupID","in":"path"},{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."}},"required":["name"],"title":"v2.UpdateWorkspaceGroupBody"}}}},"responses":{"200":{"description":"Workspace group updated","content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup","description":"Workspace group."}},"required":["group"],"title":"v2.WorkspaceGroupResponse"}}}},"400":{"description":"Invalid request body or group ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace group not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"409":{"description":"Workspace group name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"delete":{"description":"Delete a workspace group. This removes group memberships and may affect group-based entitlements and group-shared private threads.","operationId":"v2_workspace_groups_delete","tags":["Groups"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.groups:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace group.","name":"groupID","in":"path"}],"responses":{"204":{"description":"Workspace group deleted"},"400":{"description":"Invalid group ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace group not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/groups/{groupID}/members":{"put":{"description":"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.","operationId":"v2_workspace_groups_members_replace","tags":["Groups"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.groups:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace group.","name":"groupID","in":"path"},{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMemberEntry"},"maxItems":5000,"description":"Full replacement membership list. After the request succeeds, this group has exactly these members, and listed users are removed from any other workspace group."}},"required":["members"],"title":"v2.ReplaceWorkspaceGroupMembersBody"}}}},"responses":{"200":{"description":"Workspace group members replaced","content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup","description":"Workspace group."}},"required":["group"],"title":"v2.WorkspaceGroupResponse"}}}},"400":{"description":"Invalid request body or group ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace group not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"post":{"description":"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.","operationId":"v2_workspace_groups_members_add","tags":["Groups"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.groups:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace group.","name":"groupID","in":"path"},{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMemberEntry"},"maxItems":5000,"description":"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."}},"required":["members"],"title":"v2.AddWorkspaceGroupMembersBody"}}}},"responses":{"200":{"description":"Workspace group members added, moved, or updated","content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace group."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"array","items":{"type":"object","properties":{"userID":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"role":{"type":"string","enum":["captain","member"],"description":"Role of the user in the workspace group. Captains can manage their group."},"name":{"type":"string","description":"Full name of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."},"email":{"type":"string","format":"email","description":"Primary email address of the user. Only returned if the client has the \"amp.api:workspace.members:read\" scope."}},"required":["userID","role"],"title":"v2.WorkspaceGroupMember"},"description":"Members assigned to the workspace group."}},"required":["id","name","members"],"title":"v2.WorkspaceGroup","description":"Workspace group."}},"required":["group"],"title":"v2.WorkspaceGroupResponse"}}}},"400":{"description":"Invalid request body or group ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace group not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/entitlements":{"get":{"description":"List all workspace entitlements.","operationId":"v2_workspace_entitlements_list","tags":["Entitlements"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.entitlements:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"entitlements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace entitlement."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."},"type":{"type":"string","enum":["paid_credits"],"description":"Resource type limited by this entitlement."},"usageLimitUSD":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["unmanaged"],"description":"This entitlement uses an assignment mechanism not managed by this API."}},"required":["type"]}],"description":"Who receives this entitlement."}},"required":["id","name","type","usageLimitUSD","windowDays","assignment"],"title":"v2.WorkspaceEntitlement"},"description":"All workspace entitlements."}},"required":["entitlements"],"title":"v2.WorkspaceEntitlementsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"post":{"description":"Create a workspace entitlement for dollar-denominated credit caps. Assignments can target default workspace members, direct users, or workspace groups.","operationId":"v2_workspace_entitlements_create","tags":["Entitlements"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.entitlements:write"]}],"parameters":[{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]}],"description":"Who receives this entitlement."}},"required":["name","usageLimitUSD","windowDays","assignment"],"title":"v2.CreateWorkspaceEntitlementBody"}}}},"responses":{"201":{"description":"Workspace entitlement created","content":{"application/json":{"schema":{"type":"object","properties":{"entitlement":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace entitlement."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."},"type":{"type":"string","enum":["paid_credits"],"description":"Resource type limited by this entitlement."},"usageLimitUSD":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["unmanaged"],"description":"This entitlement uses an assignment mechanism not managed by this API."}},"required":["type"]}],"description":"Who receives this entitlement."}},"required":["id","name","type","usageLimitUSD","windowDays","assignment"],"title":"v2.WorkspaceEntitlement","description":"Workspace entitlement."}},"required":["entitlement"],"title":"v2.WorkspaceEntitlementResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"409":{"description":"Workspace entitlement conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/entitlements/{entitlementID}":{"get":{"description":"Get one workspace entitlement.","operationId":"v2_workspace_entitlements_get","tags":["Entitlements"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.entitlements:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace entitlement.","name":"entitlementID","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"entitlement":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace entitlement."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."},"type":{"type":"string","enum":["paid_credits"],"description":"Resource type limited by this entitlement."},"usageLimitUSD":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["unmanaged"],"description":"This entitlement uses an assignment mechanism not managed by this API."}},"required":["type"]}],"description":"Who receives this entitlement."}},"required":["id","name","type","usageLimitUSD","windowDays","assignment"],"title":"v2.WorkspaceEntitlement","description":"Workspace entitlement."}},"required":["entitlement"],"title":"v2.WorkspaceEntitlementResponse"}}}},"400":{"description":"Invalid entitlement ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace entitlement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"patch":{"description":"Update provided workspace entitlement fields. If assignment is provided, it replaces the entitlement assignment.","operationId":"v2_workspace_entitlements_update","tags":["Entitlements"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.entitlements:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace entitlement.","name":"entitlementID","in":"path"},{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]}],"description":"Who receives this entitlement. If provided, this replaces the entitlement assignment; userIDs and workspaceGroupIDs are full replacement lists, not incremental additions."}},"title":"v2.UpdateWorkspaceEntitlementBody"}}}},"responses":{"200":{"description":"Workspace entitlement updated","content":{"application/json":{"schema":{"type":"object","properties":{"entitlement":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace entitlement."},"name":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$","description":"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."},"type":{"type":"string","enum":["paid_credits"],"description":"Resource type limited by this entitlement."},"usageLimitUSD":{"type":"integer","minimum":0,"maximum":1000000,"description":"Dollar-denominated credit cap in whole US dollars."},"windowDays":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[7]},{"type":"number","enum":[30]}],"description":"Fixed quota window in days. Supported values are 1, 7, and 30."},"assignment":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["default"],"description":"Apply this entitlement to workspace members without a more specific entitlement."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"userIDs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256,"description":"Workspace member user ID."},"maxItems":5000,"description":"Workspace member user IDs assigned directly to this entitlement. Direct user assignments take precedence over group and default assignments."}},"required":["type","userIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["workspace_groups"]},"workspaceGroupIDs":{"type":"array","items":{"type":"string","format":"uuid","description":"Workspace group ID."},"minItems":1,"maxItems":1000,"description":"Workspace group IDs assigned to this entitlement. Direct user assignments take precedence over group assignments."}},"required":["type","workspaceGroupIDs"]},{"type":"object","properties":{"type":{"type":"string","enum":["unmanaged"],"description":"This entitlement uses an assignment mechanism not managed by this API."}},"required":["type"]}],"description":"Who receives this entitlement."}},"required":["id","name","type","usageLimitUSD","windowDays","assignment"],"title":"v2.WorkspaceEntitlement","description":"Workspace entitlement."}},"required":["entitlement"],"title":"v2.WorkspaceEntitlementResponse"}}}},"400":{"description":"Invalid request body or entitlement ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace entitlement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"409":{"description":"Workspace entitlement conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"delete":{"description":"Delete a workspace entitlement.","operationId":"v2_workspace_entitlements_delete","tags":["Entitlements"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.entitlements:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace entitlement.","name":"entitlementID","in":"path"}],"responses":{"204":{"description":"Workspace entitlement deleted"},"400":{"description":"Invalid entitlement ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace entitlement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/model-provider-keys":{"get":{"description":"List all workspace model provider (BYOK) keys. Key secrets are never returned.","operationId":"v2_workspace_model_provider_keys_list","tags":["Model Providers"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.model-provider-keys:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"modelProviderKeys":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Anthropic API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"OpenAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."},"config":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig"}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt","config"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"SpaceXAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]}],"description":"A workspace model provider (BYOK) key. Inference for a provider uses the workspace key that is currently active for that provider."},"description":"All workspace model provider keys."}},"required":["modelProviderKeys"],"title":"v2.WorkspaceModelProviderKeysResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"post":{"description":"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.","operationId":"v2_workspace_model_provider_keys_create","tags":["Model Providers"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.model-provider-keys:write"]}],"parameters":[{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"apiKey":{"type":"string","minLength":1,"maxLength":8192,"description":"Provider API key secret. Stored encrypted and never returned by this API."},"active":{"type":"boolean","default":false,"description":"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."}},"required":["provider","name","apiKey"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Create an Anthropic API key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"apiKey":{"type":"string","minLength":1,"maxLength":8192,"description":"Provider API key secret. Stored encrypted and never returned by this API."},"active":{"type":"boolean","default":false,"description":"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."}},"required":["provider","name","apiKey"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"Create an OpenAI API key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"apiKey":{"type":"string","minLength":1,"maxLength":8192,"description":"Provider API key secret. Stored encrypted and never returned by this API."},"active":{"type":"boolean","default":false,"description":"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":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig","description":"OpenAI-specific configuration. Defaults to the global region."}},"required":["provider","name","apiKey"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"Create a SpaceXAI API key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"apiKey":{"type":"string","minLength":1,"maxLength":8192,"description":"Provider API key secret. Stored encrypted and never returned by this API."},"active":{"type":"boolean","default":false,"description":"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."}},"required":["provider","name","apiKey"]}],"title":"v2.CreateWorkspaceModelProviderKeyBody"}}}},"responses":{"201":{"description":"Workspace model provider key created","content":{"application/json":{"schema":{"type":"object","properties":{"modelProviderKey":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Anthropic API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"OpenAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."},"config":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig"}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt","config"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"SpaceXAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]}],"description":"Workspace model provider key."}},"required":["modelProviderKey"],"title":"v2.WorkspaceModelProviderKeyResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s) or restricted configuration","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/model-provider-keys/{keyID}":{"get":{"description":"Get one workspace model provider (BYOK) key. Key secrets are never returned.","operationId":"v2_workspace_model_provider_keys_get","tags":["Model Providers"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.model-provider-keys:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace model provider key.","name":"keyID","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"modelProviderKey":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Anthropic API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"OpenAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."},"config":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig"}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt","config"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"SpaceXAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]}],"description":"Workspace model provider key."}},"required":["modelProviderKey"],"title":"v2.WorkspaceModelProviderKeyResponse"}}}},"400":{"description":"Invalid key ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace model provider key not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"patch":{"description":"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.","operationId":"v2_workspace_model_provider_keys_update","tags":["Model Providers"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.model-provider-keys:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace model provider key.","name":"keyID","in":"path"},{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"active":{"type":"boolean","description":"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":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig","description":"Provider-specific configuration. Only supported for openai keys."}},"title":"v2.UpdateWorkspaceModelProviderKeyBody"}}}},"responses":{"200":{"description":"Workspace model provider key updated","content":{"application/json":{"schema":{"type":"object","properties":{"modelProviderKey":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["meta"]},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["anthropic"],"description":"Anthropic API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]},{"type":"object","properties":{"provider":{"type":"string","enum":["openai"],"description":"OpenAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."},"config":{"type":"object","properties":{"openAIRegion":{"type":"string","enum":["global","us","eu","au","ca","jp","in","sg","kr","gb","ae"],"default":"global","description":"OpenAI data-residency region for this key. Non-global regions are only available for Enterprise workspaces."}},"title":"v2.WorkspaceModelProviderKeyOpenAIConfig"}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt","config"]},{"type":"object","properties":{"provider":{"type":"string","enum":["xai"],"description":"SpaceXAI API key."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the workspace model provider key."},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the model provider key. Names do not need to be unique; use the key ID to identify a key."},"redactedKey":{"type":["string","null"],"description":"Redacted display form of the stored API key, such as \"sk-ant-api••••1234\"."},"active":{"type":"boolean","description":"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."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"When the key was last used for inference, with roughly 30-second granularity."},"createdAt":{"type":"string","format":"date-time","description":"When the key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the key was last updated."}},"required":["provider","id","name","redactedKey","active","lastUsedAt","createdAt","updatedAt"]}],"description":"Workspace model provider key."}},"required":["modelProviderKey"],"title":"v2.WorkspaceModelProviderKeyResponse"}}}},"400":{"description":"Invalid request body or key ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s) or restricted configuration","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace model provider key not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}},"delete":{"description":"Delete a workspace model provider (BYOK) key. The stored key secret is destroyed immediately.","operationId":"v2_workspace_model_provider_keys_delete","tags":["Model Providers"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.model-provider-keys:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the target workspace model provider key.","name":"keyID","in":"path"}],"responses":{"204":{"description":"Workspace model provider key deleted"},"400":{"description":"Invalid key ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"404":{"description":"Workspace model provider key not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/workspace/analytics/daily-usage":{"get":{"description":"Get daily usage analytics for your workspace. Returns usage metrics and costs for users in the specified time period.","operationId":"v2_workspace_analytics_daily_usage","tags":["Analytics"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.analytics:read"]}],"parameters":[{"schema":{"type":"string","format":"date"},"required":false,"description":"End date (YYYY-MM-DD). Default: today","name":"endDate","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":365,"default":1},"required":false,"description":"Number of days to include.","name":"lookbackDays","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256},"required":false,"description":"Only include workspace-attributed usage for this user ID.","name":"userID","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date of the period"},"endDate":{"type":"string","format":"date","description":"End date of the period"},"activeUsers":{"type":"number","description":"Users with non-zero usage in the period"},"totalUsers":{"type":"number","description":"Total distinct users represented in the period, including former members with workspace-attributed usage"},"totalUsage":{"type":"number","description":"Total usage in the period (USD), including orb and tool usage"},"totalOrbUsage":{"type":"number","description":"Total orb usage in the period (USD)"},"totalToolUsage":{"type":"number","description":"Total tool usage in the period (USD)"}},"required":["startDate","endDate","activeUsers","totalUsers","totalUsage","totalOrbUsage","totalToolUsage"],"title":"v2.DailyUsageMetadata","description":"Metadata about the usage period"},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date in YYYY-MM-DD format"},"users":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","format":"email","description":"User email - only returned if the client has the \"amp.api:workspace.members:read\" scope"}},"required":["id"],"title":"v2.DailyUsageUserObject","description":"User information"},"metrics":{"type":"object","properties":{"linesAdded":{"type":"number","description":"Lines added by the user"},"linesDeleted":{"type":"number","description":"Lines deleted by the user"},"linesModified":{"type":"number","description":"Lines modified by the user"},"usage":{"type":"number","description":"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."},"orbUsage":{"type":"number","description":"Workspace-attributed orb usage for the user on that day (USD). Included in usage; not included in models."},"toolUsage":{"type":"number","description":"Workspace-attributed tool usage for the user on that day (USD). Included in usage; not included in models."},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["linesAdded","linesDeleted","linesModified","usage","orbUsage","toolUsage","estimatedProviderCostAtListPriceUSD"],"title":"v2.UsageMetrics","description":"Usage metrics for the user"},"models":{"type":"object","additionalProperties":{"type":"object","properties":{"requests":{"type":"number","description":"Number of requests for the model"},"inputTokens":{"type":"number","description":"Total uncached input tokens consumed by the model for this user/day"},"outputTokens":{"type":"number","description":"Total output tokens consumed by the model for this user/day"},"cacheReadInputTokens":{"type":"number","description":"Total cache-read input tokens consumed by the model for this user/day"},"cacheCreationInputTokens":{"type":"number","description":"Total cache-creation input tokens consumed by the model for this user/day"},"totalTokens":{"type":"number","description":"Total tokens consumed by the model for this user/day"},"usage":{"type":"number","description":"Usage for this model (USD)"},"estimatedProviderCostAtListPriceUSD":{"type":"number","description":"EXPERIMENTAL. Estimated USD cost of bring-your-own-key (BYOK) inference for this model for this user/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. Values can include fractions of a cent; round only for display after summing.\n\nThis 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. Always 0 for workspaces that do not show BYOK inference cost.\n\nContact Amp support before relying on this value for billing, chargeback, or reporting; its name, semantics, and availability may change without notice."}},"required":["requests","inputTokens","outputTokens","cacheReadInputTokens","cacheCreationInputTokens","totalTokens","usage","estimatedProviderCostAtListPriceUSD"],"description":"Request and token metrics for a model"},"description":"Per-model request and token counts for the user","title":"v2.DailyUsageModelRequests"},"orbs":{"type":"array","items":{"type":"object","properties":{"size":{"type":["string","null"],"description":"Orb size, such as \"a1.medium\", or null when the CPU and memory match no current orb size"},"cpuCount":{"type":["number","null"],"description":"vCPUs of the orb, or null if unknown"},"memoryMB":{"type":["number","null"],"description":"Memory of the orb in MB, or null if unknown"},"runtimeMs":{"type":"number","description":"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."},"usage":{"type":"number","description":"Orb usage (USD), counted the same way as the enclosing usage total"}},"required":["size","cpuCount","memoryMB","runtimeMs","usage"],"title":"v2.OrbUsage","description":"Usage of orbs (Amp-hosted sandboxes that run threads) of one size. Orb usage is included in the enclosing usage total."},"description":"Workspace-attributed orb runtime and usage for the user by orb size, largest usage first"},"tools":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","description":"Tool name, such as \"web_search\" or \"read_web_page\""},"calls":{"type":"number","description":"Number of charged calls, whichever credits paid for them, including calls that cost nothing"},"usage":{"type":"number","description":"Tool usage (USD), counted the same way as the enclosing usage total"}},"required":["tool","calls","usage"],"title":"v2.ToolUsage","description":"Usage of one tool that Amp charges per call, separately from model usage. Tool usage is included in the enclosing usage total."},"description":"Workspace-attributed tool calls and usage for the user by tool, largest usage first"}},"required":["user","metrics","models","orbs","tools"],"title":"v2.DailyUsageUserEntry"},"description":"Usage data for users in scope for the period, including users no longer in the workspace if they have usage attributed to this workspace"}},"required":["date","users"],"title":"v2.DailyUsageDay"},"description":"Daily usage data for each day in the period"}},"required":["metadata","data"],"title":"v2.DailyUsageResponse","description":"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."}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/inference/models":{"get":{"summary":"List Inference Models","description":"EXPERIMENTAL. Requires a Sign in with Amp OAuth access token with the amp.inference:run scope, from an application whose creator has access to it, for a user who has access too. Contact the Amp team for access. List the models the signed-in user can run with the inference, embeddings, and decisions endpoints, given their personal and workspace model providers and their workspace model policies. Each model's kind says which endpoint runs it.","operationId":"v2_inference_models_list","tags":["Inference"],"x-amp-hidden-from-docs":true,"security":[{"v2.SignInWithAmpOAuth":["amp.inference:run"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Model ID to pass as model to the endpoint for its kind: POST /api/v2/inference for text, POST /api/v2/inference/embeddings for embedding, and POST /api/v2/inference/decisions for decision."},"kind":{"type":"string","enum":["text","embedding","decision"],"description":"What the model does: generate text, embed text, or answer typed decision questions."},"displayName":{"type":"string"},"providerName":{"type":"string","description":"Name of the company that makes the model."},"contextWindow":{"type":"integer","description":"Maximum input tokens, plus output tokens for text models."},"maxOutputTokens":{"type":["integer","null"],"description":"Maximum output tokens for text models; null for other kinds."},"dimensions":{"type":["integer","null"],"description":"Embedding length for embedding models; null for other kinds."},"capabilities":{"type":"object","properties":{"vision":{"type":"boolean","description":"Whether the model reads images. The inference endpoints do not accept images yet."},"reasoning":{"type":"boolean"},"reasoningEfforts":{"type":"array","items":{"type":"string"},"description":"Values reasoningEffort accepts for this model; empty when it takes none."}},"required":["vision","reasoning","reasoningEfforts"]}},"required":["id","kind","displayName","providerName","contextWindow","maxOutputTokens","dimensions","capabilities"],"title":"v2.InferenceModel"}}},"required":["models"],"title":"v2.InferenceModelsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.inference:run, or the application creator does not have access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/inference":{"post":{"summary":"Run Inference","description":"EXPERIMENTAL. Requires a Sign in with Amp OAuth access token with the amp.inference:run scope, from an application whose creator has access to it, for a user who has access too. Contact the Amp team for access. Run one model call as the signed-in user, with no tools. The call costs the user Amp credits like their own usage in the application workspace: the workspace pays when it pays for its members, otherwise the user does. The response is not streamed.","operationId":"v2_inference_create","tags":["Inference"],"x-amp-hidden-from-docs":true,"security":[{"v2.SignInWithAmpOAuth":["amp.inference:run"]}],"parameters":[{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","minLength":1,"maxLength":200,"description":"Model ID from GET /api/v2/inference/models, such as gpt-6.1-terra."},"instructions":{"type":"string","maxLength":200000,"description":"System instructions for the model."},"input":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","minLength":1,"maxLength":1000000}},"required":["role","content"]},"minItems":1,"maxItems":200,"description":"Messages, oldest first. Usually one user message."},"maxOutputTokens":{"type":"integer","minimum":16,"maximum":64000,"default":4000,"description":"Maximum tokens to generate, including reasoning tokens."},"reasoningEffort":{"type":"string","description":"One of the model's reasoningEfforts from GET /api/v2/inference/models. Omit for the model's default."},"responseFormat":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["json_schema"]},"name":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,64}$","description":"Name of the schema."},"schema":{"type":"object","additionalProperties":{},"description":"JSON Schema the output must match, in OpenAI strict structured output form: every object lists all of its properties in required and sets additionalProperties to false."}},"required":["type","name","schema"]}],"default":{"type":"text"},"description":"Plain text output, or JSON output that matches a JSON Schema."}},"required":["model","input"],"additionalProperties":false,"title":"v2.InferenceRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Model version that answered, as the provider reports it."},"output":{"type":"string","description":"Generated text. With a json_schema response format, a JSON document."},"incomplete":{"type":"boolean","description":"True when generation stopped early, usually at maxOutputTokens."},"usage":{"type":"object","properties":{"inputTokens":{"type":"integer"},"cachedInputTokens":{"type":"integer"},"outputTokens":{"type":"integer","description":"Output tokens, including reasoning tokens."},"reasoningTokens":{"type":"integer"}},"required":["inputTokens","cachedInputTokens","outputTokens","reasoningTokens"]}},"required":["model","output","incomplete","usage"],"title":"v2.InferenceResponse"}}}},"400":{"description":"Invalid request body, or a model or reasoning effort the user cannot use","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"402":{"description":"The user is out of credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.inference:run, the application creator does not have access, or a workspace policy denies the model","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"The model provider failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/inference/embeddings":{"post":{"summary":"Create Embeddings","description":"EXPERIMENTAL. Requires a Sign in with Amp OAuth access token with the amp.inference:run scope, from an application whose creator has access to it, for a user who has access too. Contact the Amp team for access. Embed texts as the signed-in user, for clustering, search, or similarity. The call costs the user Amp credits like POST /api/v2/inference.","operationId":"v2_inference_embeddings_create","tags":["Inference"],"x-amp-hidden-from-docs":true,"security":[{"v2.SignInWithAmpOAuth":["amp.inference:run"]}],"parameters":[{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","enum":["text-embedding-3-small","text-embedding-3-large"],"description":"OpenAI embedding model. text-embedding-3-small returns 1536 dimensions and text-embedding-3-large returns 3072, unless dimensions asks for fewer."},"input":{"type":"array","items":{"type":"string","minLength":1,"maxLength":32000},"minItems":1,"maxItems":2048,"description":"Texts to embed, at most 8,192 tokens each and 300,000 tokens in total."},"dimensions":{"type":"integer","minimum":1,"maximum":3072,"description":"Shorten each embedding to this many dimensions. Omit for the model's full size."}},"required":["model","input"],"additionalProperties":false,"title":"v2.InferenceEmbeddingsRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Model that produced the embeddings, as the provider reports it."},"embeddings":{"type":"array","items":{"type":"array","items":{"type":"number"}},"description":"One embedding per input, in input order. Each has unit length."},"usage":{"type":"object","properties":{"inputTokens":{"type":"integer"}},"required":["inputTokens"]}},"required":["model","embeddings","usage"],"title":"v2.InferenceEmbeddingsResponse"}}}},"400":{"description":"Invalid request body, or input the model rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"402":{"description":"The user is out of credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.inference:run, the application creator does not have access, or a workspace policy denies the model","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"The model provider failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}},"/api/v2/inference/decisions":{"post":{"summary":"Run Decisions","description":"EXPERIMENTAL. Requires a Sign in with Amp OAuth access token with the amp.inference:run scope, from an application whose creator has access to it, for a user who has access too. Contact the Amp team for access. Answer typed questions about a state with a decision model, as the signed-in user. A decision model returns calibrated probabilities instead of text, so it suits classification, routing, and scoring. Same request and answers as amp.ai.decide in the plugin API.","operationId":"v2_inference_decisions_create","tags":["Inference"],"x-amp-hidden-from-docs":true,"security":[{"v2.SignInWithAmpOAuth":["amp.inference:run"]}],"parameters":[{"schema":{"type":"string","example":"application/json"},"required":true,"description":"Must be application/json","name":"Content-Type","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","enum":["typesafe/jev","openai/gpt-6-luna"],"default":"typesafe/jev","description":"Decision model. typesafe/jev is TypeSafe's Jev; openai/gpt-6-luna is OpenAI's Decisions API. Keep one model for a use case: their probabilities are calibrated differently."},"state":{"anyOf":[{"type":"string","maxLength":50000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"The content the questions are about, as text or JSON."},"questions":{"type":"object","additionalProperties":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["noul"]},"instructions":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"The yes or no question."},"criteria":{"type":"object","properties":{"true":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"false":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]}},"additionalProperties":false,"description":"What makes the answer true or false."}},"required":["type","instructions"],"additionalProperties":false,"title":"v2.NoulDecisionQuestion","description":"A yes or no question. The answer is the probability that it is true."},{"type":"object","properties":{"type":{"type":"string","enum":["score"]},"instructions":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"What to rate."},"criteria":{"type":"array","items":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"minItems":2,"maxItems":10,"description":"Ordered levels, lowest first."}},"required":["type","instructions","criteria"],"additionalProperties":false,"title":"v2.ScoreDecisionQuestion","description":"A rating on an ordered scale. The answer is the expected level index."},{"type":"object","properties":{"type":{"type":"string","enum":["choice"]},"instructions":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"What to choose."},"criteria":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":10000},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]},"description":"2 to 20 options, each mapped to a description or null."}},"required":["type","instructions","criteria"],"additionalProperties":false,"title":"v2.ChoiceDecisionQuestion","description":"A pick of one option. The answer is the chosen option."}]},"description":"1 to 20 questions under keys you choose. Answers use the same keys."}},"required":["state","questions"],"additionalProperties":false,"title":"v2.InferenceDecisionsRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Model version that answered, as the provider reports it."},"answers":{"type":"object","additionalProperties":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["noul"]},"noul":{"type":"number","description":"Probability, from 0 to 1, that the answer is true."}},"required":["type","noul"]},{"type":"object","properties":{"type":{"type":"string","enum":["score"]},"score":{"type":"number","description":"Expected level index, from 0 to the number of levels minus 1."},"legend":{"type":"object","additionalProperties":{"type":"string"},"description":"Level index to level text."},"probabilities":{"type":"object","additionalProperties":{"type":"number"},"description":"Probability of each option or level, summing to 1."},"confidence":{"type":"number"}},"required":["type","score","legend","probabilities","confidence"]},{"type":"object","properties":{"type":{"type":"string","enum":["choice"]},"choice":{"type":"string"},"probabilities":{"type":"object","additionalProperties":{"type":"number"},"description":"Probability of each option or level, summing to 1."},"confidence":{"type":"number"}},"required":["type","choice","probabilities","confidence"]}],"title":"v2.InferenceDecisionAnswer"},"description":"One answer per question, under the question keys."}},"required":["model","answers"],"title":"v2.InferenceDecisionsResponse"}}}},"400":{"description":"Invalid request body, or a state the model rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"402":{"description":"The user is out of credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"403":{"description":"Forbidden: missing amp.inference:run, the application creator does not have access, or a workspace policy denies the model","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}},"502":{"description":"The model provider failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"],"title":"v2.ErrorResponse"}}}}}}}},"webhooks":{}}