Acceptedobject · 1 properties
{
"type": "object",
"required": [
"accepted"
],
"properties": {
"accepted": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
}
ActivityCompletionTimenumber
Provider-reported terminal timestamp in Unix epoch milliseconds. Omitted when unknown; never inferred from creation time, duration, receive time, or silence. Display only for a terminal item status, not pending or running.
{
"type": "number",
"minimum": 0,
"description": "Provider-reported terminal timestamp in Unix epoch milliseconds. Omitted when unknown; never inferred from creation time, duration, receive time, or silence. Display only for a terminal item status, not pending or running."
}
AgentAccountActivateRequestobject · 2 properties
{
"type": "object",
"required": [
"agent",
"credential"
],
"properties": {
"agent": {
"$ref": "#/components/schemas/AgentAccountId"
},
"credential": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
}
},
"additionalProperties": false
}
AgentAccountAnswersobject
Answers to a login method's extra fields, as strings; the Hub converts each to the field's `valueType`.
{
"type": "object",
"description": "Answers to a login method's extra fields, as strings; the Hub converts each to the field's `valueType`.",
"maxProperties": 32,
"additionalProperties": {
"type": "string",
"x-uatu-maxUtf8Bytes": 4096
}
}
AgentAccountAttemptobject · 11 properties
{
"type": "object",
"required": [
"id",
"agent",
"target",
"methodId",
"url",
"instructions",
"completion",
"state",
"startedAt",
"expiresAt"
],
"properties": {
"id": {
"type": "string"
},
"agent": {
"$ref": "#/components/schemas/AgentAccountId"
},
"target": {
"type": "string"
},
"methodId": {
"type": "string"
},
"url": {
"type": "string"
},
"instructions": {
"type": "string"
},
"completion": {
"$ref": "#/components/schemas/AgentAccountCompletion"
},
"state": {
"enum": [
"pending",
"complete",
"failed",
"expired",
"cancelled"
]
},
"message": {
"type": "string"
},
"startedAt": {
"type": "number",
"description": "Unix epoch milliseconds."
},
"expiresAt": {
"type": "number",
"description": "Unix epoch milliseconds."
}
},
"additionalProperties": false
}
AgentAccountCodeRequestobject · 1 properties
{
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 8192,
"description": "One-operation secret: the code the sign-in page showed. Never persisted or returned."
}
},
"additionalProperties": false
}
AgentAccountCommandMethodobject · 4 properties
The agent runs a local helper the Hub does not run; log in with `command` on the Hub machine.
{
"type": "object",
"required": [
"id",
"kind",
"label",
"command"
],
"description": "The agent runs a local helper the Hub does not run; log in with `command` on the Hub machine.",
"properties": {
"id": {
"type": "string"
},
"kind": {
"const": "command"
},
"label": {
"type": "string"
},
"command": {
"type": "string"
}
},
"additionalProperties": false
}
AgentAccountCompletionschema
`device`: approve on the provider's site, nothing to paste. `code`: paste the code the sign-in page shows. `redirect`: the sign-in redirects to a loopback address on the Hub machine; from another device, paste the address the browser landed on.
{
"enum": [
"device",
"code",
"redirect"
],
"description": "`device`: approve on the provider's site, nothing to paste. `code`: paste the code the sign-in page shows. `redirect`: the sign-in redirects to a loopback address on the Hub machine; from another device, paste the address the browser landed on."
}
AgentAccountCredentialobject · 7 properties
{
"type": "object",
"required": [
"id",
"label",
"kind",
"active",
"removable"
],
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"kind": {
"enum": [
"key",
"oauth",
"saved",
"env",
"config",
"other"
],
"description": "`key`/`oauth`: saved by a key or browser login. `saved`: saved by a login whose kind the agent does not report. `env`: read from the agent's environment. `config`: set in the agent's configuration. `other`: anything else, such as a built-in provider."
},
"active": {
"type": "boolean"
},
"removable": {
"type": "boolean"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"description": "The agent's own message about the credential, such as needing a new login."
}
},
"additionalProperties": false
}
AgentAccountEnvMethodobject · 4 properties
The agent reads a variable from its environment; set it in the Hub's environment.
{
"type": "object",
"required": [
"id",
"kind",
"label",
"variables"
],
"description": "The agent reads a variable from its environment; set it in the Hub's environment.",
"properties": {
"id": {
"type": "string"
},
"kind": {
"const": "env"
},
"label": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
AgentAccountErrorobject · 2 properties
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, safe to show. Never contains a submitted key, code, or address."
},
"field": {
"type": "string",
"maxLength": 256,
"description": "The submitted field the error concerns (`key`, `code`, `address`, or a method field's key)."
}
},
"additionalProperties": false
}
AgentAccountFieldobject · 10 properties
One extra field a login method asks for. Shown only while every `when` condition holds against the earlier answers.
{
"type": "object",
"required": [
"key",
"label",
"kind",
"valueType",
"required"
],
"description": "One extra field a login method asks for. Shown only while every `when` condition holds against the earlier answers.",
"properties": {
"key": {
"type": "string"
},
"label": {
"type": "string"
},
"kind": {
"enum": [
"text",
"select"
]
},
"valueType": {
"enum": [
"string",
"number",
"boolean",
"list"
],
"description": "How the Hub converts the submitted string; `list` is comma-separated."
},
"required": {
"type": "boolean"
},
"secret": {
"type": "boolean",
"description": "The agent marked the answer as sensitive. Clients mask it and do not keep it after submitting."
},
"placeholder": {
"type": "string"
},
"description": {
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"value",
"label"
],
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
},
"hint": {
"type": "string"
}
},
"additionalProperties": false
}
},
"when": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountFieldCondition"
}
}
},
"additionalProperties": false
}
AgentAccountFieldConditionobject · 3 properties
{
"type": "object",
"required": [
"key",
"op",
"value"
],
"properties": {
"key": {
"type": "string"
},
"op": {
"enum": [
"eq",
"neq"
]
},
"value": {
"type": "string"
}
},
"additionalProperties": false
}
AgentAccountIdschema
{
"enum": [
"opencode",
"claude"
]
}
AgentAccountKeyMethodobject · 4 properties
{
"type": "object",
"required": [
"id",
"kind",
"label",
"fields"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"const": "key"
},
"label": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountField"
}
}
},
"additionalProperties": false
}
AgentAccountKeyRequestobject · 5 properties
{
"type": "object",
"required": [
"agent",
"target",
"method",
"key"
],
"properties": {
"agent": {
"$ref": "#/components/schemas/AgentAccountId"
},
"target": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"method": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"key": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 65536,
"description": "One-operation secret. Handed to the agent; never persisted or returned by the Hub."
},
"answers": {
"$ref": "#/components/schemas/AgentAccountAnswers"
}
},
"additionalProperties": false
}
AgentAccountLoginRequestobject · 4 properties
{
"type": "object",
"required": [
"agent",
"target",
"method"
],
"properties": {
"agent": {
"$ref": "#/components/schemas/AgentAccountId"
},
"target": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256,
"description": "The OpenCode provider or integration id; `claude` for Claude Code."
},
"method": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"answers": {
"$ref": "#/components/schemas/AgentAccountAnswers"
}
},
"additionalProperties": false
}
AgentAccountLogoutRequestobject · 3 properties
{
"type": "object",
"required": [
"agent",
"target",
"credential"
],
"properties": {
"agent": {
"$ref": "#/components/schemas/AgentAccountId"
},
"target": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"credential": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
}
},
"additionalProperties": false
}
AgentAccountMethod4 variants
{
"oneOf": [
{
"$ref": "#/components/schemas/AgentAccountKeyMethod"
},
{
"$ref": "#/components/schemas/AgentAccountOAuthMethod"
},
{
"$ref": "#/components/schemas/AgentAccountEnvMethod"
},
{
"$ref": "#/components/schemas/AgentAccountCommandMethod"
}
]
}
AgentAccountOAuthMethodobject · 5 properties
{
"type": "object",
"required": [
"id",
"kind",
"label",
"fields"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"const": "oauth"
},
"label": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountField"
}
},
"completion": {
"$ref": "#/components/schemas/AgentAccountCompletion"
}
},
"additionalProperties": false
}
AgentAccountRedirectRequestobject · 1 properties
{
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 8192,
"description": "The full address the browser landed on. One-operation secret: never persisted or returned."
}
},
"additionalProperties": false
}
AgentAccountsSnapshotobject · 2 properties
{
"type": "object",
"required": [
"agents",
"attempts"
],
"properties": {
"agents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountStatus"
}
},
"attempts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountAttempt"
}
}
},
"additionalProperties": false
}
AgentAccountStatusobject · 11 properties
{
"type": "object",
"required": [
"agent",
"name",
"state",
"capabilities",
"targets",
"methods",
"loginCommand"
],
"properties": {
"agent": {
"$ref": "#/components/schemas/AgentAccountId"
},
"name": {
"type": "string"
},
"state": {
"enum": [
"idle",
"starting",
"ready",
"not-installed",
"unavailable"
]
},
"version": {
"type": "string"
},
"generation": {
"enum": [
1,
2
]
},
"message": {
"type": "string"
},
"capabilities": {
"type": "object",
"required": [
"login",
"logout",
"activate"
],
"properties": {
"login": {
"type": "boolean"
},
"logout": {
"type": "boolean"
},
"activate": {
"type": "boolean"
}
},
"additionalProperties": false
},
"targets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountTarget"
}
},
"claude": {
"$ref": "#/components/schemas/ClaudeAccountState"
},
"methods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountMethod"
}
},
"loginCommand": {
"type": "string"
}
},
"additionalProperties": false
}
AgentAccountTargetobject · 5 properties
One OpenCode provider (1.x) or integration (2.x).
{
"type": "object",
"required": [
"id",
"name",
"connected",
"credentials",
"methods"
],
"description": "One OpenCode provider (1.x) or integration (2.x).",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"connected": {
"type": "boolean"
},
"credentials": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountCredential"
}
},
"methods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentAccountMethod"
}
}
},
"additionalProperties": false
}
AssignCredentialRequest2 variants
{
"oneOf": [
{
"$ref": "#/components/schemas/AuthenticationAssignmentRequest"
},
{
"$ref": "#/components/schemas/SigningAssignmentRequest"
}
]
}
AssignWorkspaceCredentialsRequestobject · 2 properties
{
"type": "object",
"minProperties": 1,
"properties": {
"authentication": {
"type": "object",
"required": [
"credentialId",
"host"
],
"properties": {
"credentialId": {
"$ref": "#/components/schemas/CredentialId"
},
"host": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
}
},
"additionalProperties": false
},
"signing": {
"type": "object",
"required": [
"credentialId"
],
"properties": {
"credentialId": {
"$ref": "#/components/schemas/CredentialId"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
AuthenticationAssignmentRequestobject · 4 properties
{
"type": "object",
"required": [
"workspaceId",
"role",
"host"
],
"properties": {
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"role": {
"const": "authentication"
},
"host": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"replace": {
"type": "boolean"
}
},
"additionalProperties": false
}
AuthenticationCredentialAssignmentobject · 4 properties
{
"type": "object",
"required": [
"workspaceId",
"credentialId",
"role",
"host"
],
"properties": {
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"credentialId": {
"$ref": "#/components/schemas/CredentialId"
},
"role": {
"const": "authentication"
},
"host": {
"type": "string",
"minLength": 1,
"description": "Normalized HTTPS provider host, optionally including a port."
}
},
"additionalProperties": false
}
AuthenticationSelectionobject · 2 properties
{
"type": "object",
"required": [
"credentialId",
"host"
],
"properties": {
"credentialId": {
"$ref": "#/components/schemas/CredentialId"
},
"host": {
"type": "string",
"minLength": 1,
"description": "Normalized provider host this credential becomes the authentication default for."
}
},
"additionalProperties": false
}
BrowseResultobject · 3 properties
{
"type": "object",
"required": [
"path",
"parent",
"dirs"
],
"properties": {
"path": {
"type": "string"
},
"parent": {
"type": [
"string",
"null"
]
},
"dirs": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"git",
"registeredId",
"displayName",
"running"
],
"properties": {
"name": {
"type": "string"
},
"git": {
"type": "boolean"
},
"registeredId": {
"oneOf": [
{
"$ref": "#/components/schemas/WorkspaceId"
},
{
"type": "null"
}
]
},
"displayName": {
"oneOf": [
{
"$ref": "#/components/schemas/WorkspaceDisplayName"
},
{
"type": "null"
}
],
"description": "Registered workspace display name; null for unregistered directories."
},
"running": {
"type": "boolean",
"description": "Whether the registered workspace currently has a live session. Always false for unregistered directories."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
BuildSummaryobject · 7 properties
{
"type": "object",
"required": [
"version",
"branch",
"commitSha",
"commitShort",
"release",
"identifier",
"bundledWebRevision"
],
"properties": {
"version": {
"type": "string"
},
"branch": {
"type": "string"
},
"commitSha": {
"type": "string"
},
"commitShort": {
"type": "string"
},
"release": {
"type": "boolean"
},
"identifier": {
"type": "string"
},
"bundledWebRevision": {
"type": "integer"
}
},
"additionalProperties": false
}
ChatAgentDescriptorobject · 2 properties
The identity of one offered agent. Capabilities ride the agent's availability, which only exists once its runtime has spoken.
{
"type": "object",
"required": [
"id",
"name"
],
"description": "The identity of one offered agent. Capabilities ride the agent's availability, which only exists once its runtime has spoken.",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[^:]+$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"additionalProperties": false
}
ChatEvent8 variants
{
"oneOf": [
{
"type": "object",
"required": [
"generation",
"sequence",
"conversationId",
"type",
"item"
],
"properties": {
"generation": {
"type": "string"
},
"sequence": {
"type": "integer",
"minimum": 0
},
"conversationId": {
"type": "string"
},
"type": {
"const": "item.upsert"
},
"item": {
"$ref": "#/components/schemas/ConversationItem"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"generation",
"sequence",
"conversationId",
"type",
"itemId"
],
"properties": {
"generation": {
"type": "string"
},
"sequence": {
"type": "integer",
"minimum": 0
},
"conversationId": {
"type": "string"
},
"type": {
"const": "item.remove"
},
"itemId": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"generation",
"sequence",
"conversationId",
"type",
"itemId",
"delta"
],
"properties": {
"generation": {
"type": "string"
},
"sequence": {
"type": "integer",
"minimum": 0
},
"conversationId": {
"type": "string"
},
"type": {
"const": "item.text_delta"
},
"itemId": {
"type": "string"
},
"delta": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"generation",
"sequence",
"conversationId",
"type",
"status"
],
"properties": {
"generation": {
"type": "string"
},
"sequence": {
"type": "integer",
"minimum": 0
},
"conversationId": {
"type": "string"
},
"type": {
"const": "conversation.status"
},
"status": {
"$ref": "#/components/schemas/ConversationStatus"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"generation",
"sequence",
"conversationId",
"type",
"configuration"
],
"properties": {
"generation": {
"type": "string"
},
"sequence": {
"type": "integer",
"minimum": 0
},
"conversationId": {
"type": "string"
},
"type": {
"const": "conversation.configuration"
},
"configuration": {
"$ref": "#/components/schemas/ConversationConfiguration"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"generation",
"sequence",
"conversationId",
"type",
"conversation"
],
"properties": {
"generation": {
"type": "string"
},
"sequence": {
"type": "integer",
"minimum": 0
},
"conversationId": {
"type": "string"
},
"type": {
"const": "conversation.updated"
},
"conversation": {
"allOf": [
{
"$ref": "#/components/schemas/ConversationSummary"
}
],
"description": "Updated summary for this conversation. Its id is the event conversationId."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"generation",
"sequence",
"conversationId",
"type",
"queued",
"change"
],
"description": "Restates the whole held queue after a change, so replayed or duplicated frames converge on the same state.",
"properties": {
"generation": {
"type": "string"
},
"sequence": {
"type": "integer",
"minimum": 0
},
"conversationId": {
"type": "string"
},
"type": {
"const": "conversation.queue"
},
"queued": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QueuedMessage"
}
},
"change": {
"type": "object",
"required": [
"kind",
"messageId"
],
"properties": {
"kind": {
"enum": [
"held",
"removed",
"delivered"
]
},
"messageId": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"$ref": "#/components/schemas/ChatResyncEvent"
}
]
}
ChatResyncEventobject · 5 properties
{
"type": "object",
"required": [
"generation",
"sequence",
"conversationId",
"type",
"reason"
],
"properties": {
"generation": {
"type": "string"
},
"sequence": {
"type": "integer",
"minimum": 0
},
"conversationId": {
"type": "string"
},
"type": {
"const": "resync"
},
"reason": {
"enum": [
"generation-changed",
"retention-gap",
"invalid-cursor",
"conversation-rewritten"
]
}
},
"additionalProperties": false
}
ClaudeAccountStateobject · 5 properties
{
"type": "object",
"required": [
"source"
],
"properties": {
"source": {
"enum": [
"subscription",
"console",
"env-api-key",
"env-token",
"api-key-helper",
"third-party",
"none",
"unknown"
]
},
"email": {
"type": "string"
},
"organization": {
"type": "string"
},
"plan": {
"type": "string"
},
"provider": {
"type": "string",
"description": "The API backend when it is not Anthropic's own."
}
},
"additionalProperties": false
}
CloneJobobject · 1 properties
{
"type": "object",
"required": [
"jobId"
],
"properties": {
"jobId": {
"type": "string"
}
},
"additionalProperties": false
}
CloneJobCancelResultobject · 1 properties
{
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"enum": [
"cancelled",
"terminal"
]
}
},
"additionalProperties": false
}
CloneJobInputobject · 1 properties
{
"type": "object",
"required": [
"input"
],
"properties": {
"input": {
"type": "string",
"description": "At most 8192 bytes UTF-8 encoded (a byte limit, not a character count); larger payloads are rejected with 413."
}
},
"additionalProperties": false
}
CommitLogEntryobject · 6 properties
One recent commit. Entries are open objects: consumers must ignore fields they don't know.
{
"type": "object",
"description": "One recent commit. Entries are open objects: consumers must ignore fields they don't know.",
"properties": {
"sha": {
"type": "string",
"description": "Short commit SHA."
},
"subject": {
"type": "string"
},
"message": {
"type": "string",
"description": "Full commit message."
},
"author": {
"type": [
"string",
"null"
]
},
"relativeTime": {
"type": [
"string",
"null"
],
"description": "Git's relative age text as of collection (\"3 hours ago\"). It does not advance between repository changes; render ages from committedAtMs instead."
},
"committedAtMs": {
"type": [
"number",
"null"
],
"description": "Commit time in epoch milliseconds. Clients render the commit's age from this so it stays current."
}
},
"additionalProperties": true
}
CompatibilityMetadataobject · 2 properties
Public Hub and proxied workspace compatibility identities.
{
"type": "object",
"required": [
"hubApiRevision",
"workspaceApiRevision"
],
"properties": {
"hubApiRevision": {
"type": "integer",
"minimum": 1
},
"workspaceApiRevision": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false,
"description": "Public Hub and proxied workspace compatibility identities."
}
ConfigureWorkspaceRequestobject · 6 properties
{
"type": "object",
"required": [
"path",
"displayName"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Absolute path of the existing direct non-symbolic-link folder to register."
},
"displayName": {
"$ref": "#/components/schemas/WorkspaceDisplayName"
},
"authentication": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthenticationSelection"
},
"description": "At most one default per provider host."
},
"signing": {
"oneOf": [
{
"$ref": "#/components/schemas/CredentialId"
},
{
"type": "null"
}
],
"description": "Default commit-signing credential."
},
"init": {
"type": "boolean",
"default": false,
"description": "Explicit confirmation to run `git init` on a non-Git folder."
},
"start": {
"type": "boolean",
"default": false,
"description": "Explicit start intent. Omitted or false, the workspace finishes registered and stopped."
}
},
"additionalProperties": false
}
ContextWindowItemobject · 7 properties
Limit-only metadata. Never render as a message or use as a token-occupancy sample. Prefer an applicable session observation to a catalog value or estimate, and update the meter even when the usage item is unchanged. A newer observation can increase or decrease the limit. A matching contextKey scopes the observation to the execution that produced usage.
{
"type": "object",
"description": "Limit-only metadata. Never render as a message or use as a token-occupancy sample. Prefer an applicable session observation to a catalog value or estimate, and update the meter even when the usage item is unchanged. A newer observation can increase or decrease the limit. A matching contextKey scopes the observation to the execution that produced usage.",
"required": [
"id",
"type",
"createdAt",
"model",
"limit",
"window"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "context_window"
},
"createdAt": {
"type": "number",
"minimum": 0
},
"model": {
"$ref": "#/components/schemas/ModelSelection"
},
"contextKey": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"limit": {
"type": "integer",
"minimum": 1
},
"window": {
"$ref": "#/components/schemas/ContextWindowMetadata"
}
},
"additionalProperties": false
}
ContextWindowMetadataobject · 6 properties
{
"type": "object",
"required": [
"source",
"freshness"
],
"properties": {
"source": {
"enum": [
"session",
"catalog",
"estimate"
]
},
"freshness": {
"enum": [
"current",
"cached"
]
},
"observedAt": {
"type": "number",
"minimum": 0
},
"kind": {
"enum": [
"effective",
"compaction"
]
},
"capacity": {
"type": "integer",
"minimum": 1,
"description": "Model capacity only when separately reported by the agent, never inferred from the compaction window."
},
"compactionThreshold": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
}
ConversationConfigurationobject · 3 properties
Effective configuration reported for this conversation. An absent field is unknown or agent-controlled, not an invitation to select the first offered value.
{
"type": "object",
"description": "Effective configuration reported for this conversation. An absent field is unknown or agent-controlled, not an invitation to select the first offered value.",
"properties": {
"model": {
"$ref": "#/components/schemas/ModelSelection"
},
"mode": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"variant": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "Reasoning variant of `model`. Invalid without `model` in the same configuration record."
}
},
"dependentRequired": {
"variant": [
"model"
]
},
"additionalProperties": false
}
ConversationInventoryEventobject · 2 properties
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"const": "conversation.inventory"
},
"catalogs": {
"type": "object",
"description": "Agent id to opaque catalog revision. Re-read an agent's models when its revision changes; reconnect frames carry current revisions to recover missed updates.",
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
}
},
"additionalProperties": false
}
ConversationItem16 variants
{
"oneOf": [
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"text"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "user_message"
},
"createdAt": {
"type": "number"
},
"text": {
"type": "string"
},
"requestId": {
"type": "string"
},
"attachments": {
"type": "array",
"maxItems": 8,
"items": {
"$ref": "#/components/schemas/MessageAttachment"
}
},
"origin": {
"const": "wakeup",
"description": "Present when the user did not type this prompt: `wakeup` is a scheduled wakeup firing, and the item opens that wakeup's turn. Clients present it as a wakeup, never as the user's message. Absent means the user typed it."
},
"wakeupId": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "With `origin: wakeup`: the `scheduled_wakeup` item that fired, when known."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"markdown"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "assistant_message"
},
"createdAt": {
"type": "number"
},
"markdown": {
"type": "string"
},
"completedAt": {
"type": "number"
},
"contextKey": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "Execution identity joining usage to its window observation, including the selected window variant."
},
"usage": {
"allOf": [
{
"$ref": "#/components/schemas/TokenUsage"
}
],
"description": "Message-level tokens. Normalization emits exactly one dedicated carrier per reported provider message: its id is `usage:<provider-message-id>` and its markdown is empty, so clients MUST treat it as data rather than render it as a message bubble. Present only where the agent declares the context capability and reported usage."
},
"model": {
"allOf": [
{
"$ref": "#/components/schemas/ModelSelection"
}
],
"description": "The model that reported this usage carrier, when known. Context percentages MUST use this model's context limit rather than a newly selected model that has not produced usage yet."
},
"agent": {
"type": "string",
"minLength": 1,
"description": "The agent that produced the message, as the provider names it (OpenCode: `build`, `plan`, `compaction`, or a subagent's kind). Rides the usage carrier so a cost receipt can name the main agent's lines. Absent where the provider names none."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"text",
"status"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "reasoning"
},
"createdAt": {
"type": "number"
},
"text": {
"type": "string"
},
"status": {
"enum": [
"pending",
"running",
"completed",
"failed",
"cancelled"
]
},
"durationMs": {
"type": "number"
},
"label": {
"type": "string",
"minLength": 1,
"description": "The row's label when it is recalled context rather than the model's own thinking (\"Recalled from memory\"). Absent for ordinary reasoning."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"name",
"status"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "tool"
},
"createdAt": {
"type": "number"
},
"name": {
"type": "string"
},
"status": {
"enum": [
"pending",
"running",
"completed",
"failed",
"cancelled"
]
},
"completedAt": {
"$ref": "#/components/schemas/ActivityCompletionTime"
},
"input": {
"type": "string"
},
"output": {
"type": "string"
},
"error": {
"type": "string"
},
"childConversationId": {
"type": "string"
},
"model": {
"type": "string",
"description": "For a task tool: the model the subagent's own session ran, mirrored from that child session. A subagent may run a different model from its parent."
},
"usage": {
"allOf": [
{
"$ref": "#/components/schemas/TokenUsage"
}
],
"description": "For a task tool: what the subagent spent on THE TASK THIS ROW REPRESENTS — the messages it produced answering that task's prompt. A subagent given several tasks is one `childConversationId` on several rows, each stating its own task; together they are what the subagent's session spent. Subagents the subagent launched are NOT included: they are listed in `descendants`. Absent until the task has reported any."
},
"descendants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SubagentLine"
},
"description": "For a task tool: every subagent launched beneath this row, at any depth, flat and ordered so that each line follows the row or line named by its `parentId`. The row's own `usage` plus its lines' is what the whole branch spent, each message counted once. Absent when the subagent launched none."
},
"elapsedMs": {
"type": "number",
"minimum": 0,
"description": "How long the tool has been running, from the agent's own progress heartbeat, for a tool still producing no output."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"command",
"status"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "command"
},
"createdAt": {
"type": "number"
},
"command": {
"type": "string"
},
"status": {
"enum": [
"pending",
"running",
"completed",
"failed",
"cancelled"
]
},
"completedAt": {
"$ref": "#/components/schemas/ActivityCompletionTime"
},
"output": {
"type": "string"
},
"exitCode": {
"type": "integer"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"path",
"operation"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "file_change"
},
"createdAt": {
"type": "number"
},
"path": {
"type": "string"
},
"operation": {
"enum": [
"create",
"update",
"delete"
]
},
"additions": {
"type": "integer",
"minimum": 0
},
"deletions": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
{
"$ref": "#/components/schemas/PermissionItem"
},
{
"$ref": "#/components/schemas/QuestionItem"
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"entries"
],
"description": "The agent's live task list: one presentation per conversation, upserted in place as items progress — never an entry per update. Present only for agents that keep a task list.",
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "task_progress"
},
"createdAt": {
"type": "number"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskProgressEntry"
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"status"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "turn_status"
},
"createdAt": {
"type": "number"
},
"status": {
"$ref": "#/components/schemas/ConversationStatus"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"level",
"message"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "notice"
},
"createdAt": {
"type": "number"
},
"level": {
"enum": [
"info",
"warning",
"error"
]
},
"message": {
"type": "string"
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "A machine-readable kind for notices the surface reacts to: `rate-limit-warning` and `rate-limit-rejected` carry the current rate-limit standing and are data for the composer, never a timeline row — a client MUST treat them the way it treats `context_report`. The standing occupies one item id for the conversation's life, upserted as it changes and removed when requests are allowed again. `refusal-fallback` names a model swap. `login-failed` marks a turn that failed because the agent's login is missing, expired, or refused; `message` is the agent's own words, and a client offers a way to log in. `reauthenticating` is the one item an agent occupies while it signs in again mid-session, removed when that finishes. Absent otherwise."
},
"resetsAt": {
"type": "number",
"minimum": 0,
"description": "When the rate-limit standing's window resets."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"total"
],
"description": "The agent's own statement of how full the context window is, at the point in the timeline where it was reported (after a turn, after a compaction). Data for the context readout, never rendered as a row: a client MUST treat it like the empty-markdown usage carrier. The readout uses whichever of a report or a usage carrier is newest in the timeline.",
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "context_report"
},
"createdAt": {
"type": "number"
},
"contextKey": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"window": {
"$ref": "#/components/schemas/ContextWindowMetadata"
},
"total": {
"type": "integer",
"minimum": 0,
"description": "Tokens occupying the window."
},
"max": {
"type": "integer",
"minimum": 1,
"description": "The window the total was measured against. Absent when the agent did not state one; the reporting model's known limit then applies."
},
"model": {
"$ref": "#/components/schemas/ModelSelection"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"tokens",
"kind"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"tokens": {
"type": "integer",
"minimum": 0
},
"kind": {
"enum": [
"used",
"free",
"buffer",
"deferred"
],
"description": "`used` rows occupy the window and sum to `total`; `free` is the remaining window; `buffer` a compaction reserve; `deferred` rows are out-of-window tool schemas listed for awareness only."
}
},
"additionalProperties": false
}
},
"plan": {
"$ref": "#/components/schemas/PlanUtilization"
}
},
"additionalProperties": false
},
{
"$ref": "#/components/schemas/ContextWindowItem"
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"taskId",
"description",
"status"
],
"description": "One background task the agent runs (a backgrounded command, a backgrounded subagent, a monitor), updated in place as it progresses and settles. A running task is presented in the composer's live list, a settled one as a timeline row with its outcome and summary; `toolUseId` links it to the tool row that launched it. Only for agents declaring `background-tasks`; ambient housekeeping tasks never appear.",
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "background_task"
},
"createdAt": {
"type": "number"
},
"taskId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"description": {
"type": "string",
"minLength": 1
},
"taskType": {
"type": "string"
},
"toolUseId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"status": {
"enum": [
"running",
"completed",
"failed",
"stopped"
]
},
"progress": {
"type": "string",
"description": "The agent's latest progress note, while running."
},
"summary": {
"type": "string",
"description": "The agent's summary, once settled."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"wakeupId",
"prompt",
"recurring",
"schedule",
"status"
],
"description": "One future turn the agent scheduled for itself (a self-paced wakeup, a cron, a loop), as its session reports it, updated in place through its life. `pending` rows are listed with the conversation's scheduled state and shown in the timeline; a one-shot that fired reads `fired` with `firedTurnId` naming the `user_message` (origin `wakeup`) that opened its turn; a recurring one stays `pending` across fires with `nextFireAt` moving on. `cancelled`: the agent removed it, or the user cancelled it or released the session; the workspace blocks a cancelled wakeup from firing again even if the agent's tooling later rebuilds it. `paused`: the session ended, but the agent's tooling rebuilds this wakeup (a cron) when the conversation runs again; `message` says so, and a conversation opened without a live session lists its paused wakeups. `lost`: the session ended some other way and the schedule ended with it; `message` says so. A reopened conversation whose session is gone replays no pending row. Only for agents declaring `scheduled-wakeups`.",
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "scheduled_wakeup"
},
"createdAt": {
"type": "number"
},
"wakeupId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"prompt": {
"type": "string",
"description": "The prompt the wakeup submits when it fires, as the agent reports it (possibly clipped by the agent)."
},
"recurring": {
"type": "boolean"
},
"schedule": {
"type": "string",
"minLength": 1,
"description": "Five-field cron expression in the workspace host's local time; a one-shot encodes a single fire time."
},
"nextFireAt": {
"type": "number",
"minimum": 0,
"description": "The workspace's reading of the next fire time (epoch ms), for display only: the agent fires on its own clock. Only on a pending row, and absent when the expression could not be read."
},
"status": {
"enum": [
"pending",
"fired",
"cancelled",
"paused",
"lost"
]
},
"firedTurnId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"message": {
"type": "string",
"description": "What happened to a wakeup that did not fire, when that needs saying (a lost or paused schedule)."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"id",
"type",
"createdAt"
],
"description": "The agent compacted the conversation at this point. Content before the marker stays in the timeline; the figures are the agent's own pre/post token counts when it reported them.",
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "compaction"
},
"createdAt": {
"type": "number"
},
"trigger": {
"enum": [
"manual",
"auto"
]
},
"preTokens": {
"type": "integer",
"minimum": 0
},
"postTokens": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}
]
}
ConversationStatusschema
`background`: no turn is running but the agent still holds live background work; prompting is possible. Presented only for agents declaring `background-tasks`. `scheduled`: nothing runs, but the agent's session holds one or more future turns it scheduled for itself (pending `scheduled_wakeup` items); prompting is possible, and the session can be released. Presented only for agents declaring `scheduled-wakeups`; `background` wins when both hold. `retrying` and `compacting` are live-turn states with a name: the agent is waiting to retry a failed API request, or compacting its context; both return to `running` when the turn resumes.
{
"enum": [
"idle",
"sending",
"running",
"completed",
"interrupted",
"failed",
"background",
"retrying",
"compacting",
"scheduled"
],
"description": "`background`: no turn is running but the agent still holds live background work; prompting is possible. Presented only for agents declaring `background-tasks`. `scheduled`: nothing runs, but the agent's session holds one or more future turns it scheduled for itself (pending `scheduled_wakeup` items); prompting is possible, and the session can be released. Presented only for agents declaring `scheduled-wakeups`; `background` wins when both hold. `retrying` and `compacting` are live-turn states with a name: the agent is waiting to retry a failed API request, or compacting its context; both return to `running` when the turn resumes."
}
ConversationSummaryobject · 6 properties
`id` is agent-qualified (`<agentId>:<providerConversationId>`); ids from different agents never collide. `agent` names the owner, fixed at creation for the conversation's lifetime.
{
"type": "object",
"required": [
"id",
"title",
"createdAt",
"updatedAt",
"status",
"agent"
],
"description": "`id` is agent-qualified (`<agentId>:<providerConversationId>`); ids from different agents never collide. `agent` names the owner, fixed at creation for the conversation's lifetime.",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"title": {
"type": "string"
},
"createdAt": {
"type": "number",
"minimum": 0
},
"updatedAt": {
"type": "number",
"minimum": 0
},
"status": {
"$ref": "#/components/schemas/ConversationStatus"
},
"agent": {
"$ref": "#/components/schemas/ChatAgentDescriptor"
}
},
"additionalProperties": false
}
CreateCloneJobRequestobject · 9 properties
{
"type": "object",
"required": [
"url",
"dest"
],
"properties": {
"url": {
"type": "string"
},
"dest": {
"type": "string"
},
"folderName": {
"type": "string",
"description": "Checkout folder name, independent of the workspace display name, trimmed before use. Absent, blank, or whitespace-only derives it from the clone URL. Any other value must be one visible path segment — `.`, `..`, path separators, control characters, and Unicode format characters (Cf) answer 400 — but, unlike FolderName, a dot-prefixed checkout is accepted."
},
"credentialId": {
"$ref": "#/components/schemas/CredentialId",
"description": "Clone authentication identity. Never retained as a workspace assignment unless explicitly requested."
},
"retainAssignment": {
"type": "boolean",
"default": false,
"description": "Explicitly retain the clone credential as the workspace authentication default for its host."
},
"displayName": {
"$ref": "#/components/schemas/WorkspaceDisplayName",
"description": "Workspace display name; defaults from the checkout folder name."
},
"retainedAuthentication": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthenticationSelection"
},
"description": "Workspace authentication defaults committed with the registration, independent of the clone identity."
},
"signing": {
"oneOf": [
{
"$ref": "#/components/schemas/CredentialId"
},
{
"type": "null"
}
],
"description": "Default commit-signing credential committed with the registration."
},
"start": {
"type": "boolean",
"default": false,
"description": "Explicit start-after-clone intent. Omitted or false, a successful clone finishes as a registered stopped workspace."
}
},
"dependentSchemas": {
"retainAssignment": {
"if": {
"properties": {
"retainAssignment": {
"const": true
}
}
},
"then": {
"properties": {
"credentialId": {
"$ref": "#/components/schemas/CredentialId"
}
},
"required": [
"credentialId"
]
}
}
},
"additionalProperties": false
}
CreateConfiguredWorkspaceRequestobject · 6 properties
{
"type": "object",
"required": [
"parent",
"folderName",
"displayName"
],
"properties": {
"parent": {
"type": "string",
"minLength": 1,
"description": "Absolute path of the existing direct parent directory."
},
"folderName": {
"$ref": "#/components/schemas/FolderName"
},
"displayName": {
"$ref": "#/components/schemas/WorkspaceDisplayName"
},
"authentication": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthenticationSelection"
}
},
"signing": {
"oneOf": [
{
"$ref": "#/components/schemas/CredentialId"
},
{
"type": "null"
}
]
},
"start": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}
CreateFolderRequestobject · 2 properties
{
"type": "object",
"required": [
"parent",
"name"
],
"properties": {
"parent": {
"type": "string",
"minLength": 1,
"description": "Absolute path of the existing direct parent directory."
},
"name": {
"$ref": "#/components/schemas/FolderName"
}
},
"additionalProperties": false
}
CreateFolderResultobject · 1 properties
{
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Absolute path of the created folder."
}
},
"additionalProperties": false
}
CreateTokenCredentialRequestobject · 5 properties
{
"type": "object",
"required": [
"name",
"host",
"token",
"capabilities"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"host": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"username": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"token": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 65536
},
"capabilities": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"enum": [
"https-git",
"github-cli",
"gitlab-cli"
]
}
}
},
"additionalProperties": false
}
CreateWorkspaceRequestobject · 3 properties
{
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string"
},
"init": {
"type": "boolean"
},
"start": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
}
CreateWorktreeRequestobject · 6 properties
{
"type": "object",
"required": [
"mode"
],
"properties": {
"sourceWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId",
"description": "Required."
},
"mode": {
"type": "string",
"enum": [
"new-branch",
"existing-local",
"remote-tracking"
]
},
"branch": {
"type": "string",
"minLength": 1,
"description": "The target local branch. Required for new-branch. For the other modes the Hub derives it — the existing local ref, or the remote ref minus its remote prefix — and rejects a mismatching guess. Held to Git's branch grammar before any repository is touched, so an option-like name or a revision expression never reaches a Git argument list."
},
"base": {
"type": "object",
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"local",
"remote"
]
},
"ref": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"description": "An exactly qualified starting ref. Mutually exclusive with baseRef."
},
"baseRef": {
"type": "string",
"minLength": 1,
"description": "A starting ref left for the Hub to qualify against the repository's own listing, for callers that have one name rather than a committed selection — feature/login is a valid local branch and origin/main a remote-qualified one, and only the listing tells them apart. A ref that is not in the listing is refused; one that is both is refused as ambiguous. Nothing is substituted for a near match. Ignored when base is present."
},
"start": {
"type": "boolean",
"description": "Post-commit intent. Creation leaves the workspace stopped by default, and a failed start does not fail the creation."
}
},
"additionalProperties": false
}
CredentialAssignment2 variants
Advisory normal-tool selection for the local backend; same-UID processes are not isolated by this assignment.
{
"oneOf": [
{
"$ref": "#/components/schemas/AuthenticationCredentialAssignment"
},
{
"$ref": "#/components/schemas/SigningCredentialAssignment"
}
],
"description": "Advisory normal-tool selection for the local backend; same-UID processes are not isolated by this assignment."
}
CredentialAssignmentResponseobject · 1 properties
{
"type": "object",
"required": [
"assignment"
],
"properties": {
"assignment": {
"$ref": "#/components/schemas/CredentialAssignment"
}
},
"additionalProperties": false
}
CredentialAssignmentsResponseobject · 1 properties
{
"type": "object",
"required": [
"assignments"
],
"properties": {
"assignments": {
"type": "array",
"minItems": 1,
"maxItems": 2,
"items": {
"$ref": "#/components/schemas/CredentialAssignment"
}
}
},
"additionalProperties": false
}
CredentialDeletedResponseobject · 1 properties
{
"type": "object",
"required": [
"deleted"
],
"properties": {
"deleted": {
"type": "boolean"
}
},
"additionalProperties": false
}
CredentialIdstring
{
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9_-]+$"
}
CredentialListobject · 1 properties
{
"type": "object",
"required": [
"credentials"
],
"properties": {
"credentials": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicCredential"
}
}
},
"additionalProperties": false
}
CredentialPublicKeyobject · 4 properties
{
"type": "object",
"required": [
"id",
"type",
"publicKey",
"fingerprint"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CredentialId"
},
"type": {
"enum": [
"ssh",
"openpgp"
]
},
"publicKey": {
"type": "string",
"minLength": 1
},
"fingerprint": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
CredentialResponseobject · 1 properties
{
"type": "object",
"required": [
"credential"
],
"properties": {
"credential": {
"$ref": "#/components/schemas/PublicCredential"
}
},
"additionalProperties": false
}
CredentialTestResponseobject · 1 properties
{
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReadinessResult"
}
}
},
"additionalProperties": false
}
CredentialToolListobject · 1 properties
{
"type": "object",
"required": [
"tools"
],
"properties": {
"tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicCredentialTool"
}
}
},
"additionalProperties": false
}
CredentialToolNameschema
{
"enum": [
"ssh",
"ssh-agent",
"ssh-add",
"ssh-keygen",
"gpg",
"gpgconf",
"git",
"gh",
"glab"
]
}
CredentialToolResponseobject · 1 properties
{
"type": "object",
"required": [
"tool"
],
"properties": {
"tool": {
"$ref": "#/components/schemas/PublicCredentialTool"
}
},
"additionalProperties": false
}
CredentialUnassignedResponseobject · 1 properties
{
"type": "object",
"required": [
"removed"
],
"properties": {
"removed": {
"type": "boolean"
}
},
"additionalProperties": false
}
DeleteCredentialRequestobject · 2 properties
{
"type": "object",
"required": [
"confirm"
],
"properties": {
"confirm": {
"type": "boolean",
"const": true
},
"unassign": {
"type": "boolean"
}
},
"additionalProperties": false
}
DeleteWorktreeRequestobject · 5 properties
{
"type": "object",
"required": [
"reference",
"confirm"
],
"properties": {
"sourceWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"reference": {
"$ref": "#/components/schemas/WorktreeReference"
},
"confirm": {
"type": "boolean",
"const": true,
"description": "Required — the same role the destructive button plays in the Hub's dialog, and for a checkout without local data the whole authorization. It authorizes the stated operation and overrides no blocker. There is no client-facing force option in this family."
},
"stop": {
"type": "boolean",
"description": "Additionally authorizes stopping this worktree's own Uatu sessions before removal. Activity Uatu does not own stays a blocker: Uatu never claims it can stop an external application."
},
"localDataFingerprint": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "The acknowledgement of local data: the `localData.fingerprint` the deletion preflight reported, echoed back. It authorizes deleting exactly the disclosed tracked changes, untracked files and ignored files with the checkout, and is re-verified at every recheck — a checkout whose local data changed since is refused as `local-data`. It never overrides a lock, a nested worktree, a submodule or nested repository, a Git operation in progress, external activity, uncertain identity or ownership. Only for acknowledged tracked or untracked data may the Hub pass Git a single force, never the double force that overrides a lock. Omitted for a checkout without local data."
}
},
"additionalProperties": false
}
DeviceSessionobject · 4 properties
{
"type": "object",
"required": [
"handle",
"deviceLabel",
"issuedAt",
"current"
],
"properties": {
"handle": {
"type": "string"
},
"deviceLabel": {
"type": "string"
},
"issuedAt": {
"type": "integer"
},
"current": {
"type": "boolean"
}
},
"additionalProperties": false
}
DeviceSessionListobject · 1 properties
{
"type": "object",
"required": [
"sessions"
],
"properties": {
"sessions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DeviceSession"
}
}
},
"additionalProperties": false
}
DocumentDiscoveryobject · 3 properties
{
"type": "object",
"required": [
"status",
"discovered"
],
"properties": {
"status": {
"enum": [
"indexing",
"ready",
"recovering",
"error"
]
},
"discovered": {
"type": "integer",
"minimum": 0
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
DocumentMetaobject · 7 properties
{
"type": "object",
"required": [
"id",
"name",
"relativePath",
"mtimeMs",
"rootId",
"kind",
"revision"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"relativePath": {
"type": "string"
},
"mtimeMs": {
"type": "number"
},
"rootId": {
"type": "string"
},
"kind": {
"enum": [
"markdown",
"asciidoc",
"text",
"binary"
]
},
"revision": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}
DocumentPatchobject · 16 properties
{
"type": "object",
"required": [
"kind",
"epoch",
"previousRevision",
"revision",
"generatedAt",
"scope",
"compareTarget",
"unscopedFingerprint",
"upserts",
"removals",
"changedId"
],
"properties": {
"kind": {
"const": "patch"
},
"epoch": {
"type": "string"
},
"previousRevision": {
"type": "integer",
"minimum": 0
},
"revision": {
"type": "integer",
"minimum": 0
},
"generatedAt": {
"type": "number"
},
"scope": {
"oneOf": [
{
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"const": "folder"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"documentId"
],
"properties": {
"kind": {
"const": "file"
},
"documentId": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"compareTarget": {
"enum": [
"base",
"last-commit"
]
},
"unscopedFingerprint": {
"type": "string"
},
"upserts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentMeta"
}
},
"removals": {
"type": "array",
"items": {
"type": "object",
"required": [
"rootId",
"id"
],
"properties": {
"rootId": {
"type": "string"
},
"id": {
"type": "string"
}
},
"additionalProperties": false
}
},
"roots": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentRoot"
}
},
"discovery": {
"$ref": "#/components/schemas/DocumentDiscovery"
},
"repositories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RepositorySnapshot"
}
},
"repositoryState": {
"$ref": "#/components/schemas/RepositoryFreshness"
},
"defaultDocumentId": {
"type": [
"string",
"null"
]
},
"changedId": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
DocumentRootobject · 4 properties
{
"type": "object",
"required": [
"id",
"label",
"path",
"hiddenCount"
],
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"path": {
"type": "string"
},
"hiddenCount": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}
DocumentUpdate2 variants
{
"oneOf": [
{
"$ref": "#/components/schemas/WorkspaceState"
},
{
"$ref": "#/components/schemas/DocumentPatch"
}
]
}
EmptyObjectobject
{
"type": "object",
"additionalProperties": false
}
Errorobject · 2 properties
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"needsInit": {
"type": "boolean"
}
},
"additionalProperties": false
}
FetchWorktreeRefsRequestobject · 1 properties
{
"type": "object",
"required": [
"sourceWorkspaceId"
],
"properties": {
"sourceWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
}
},
"additionalProperties": false
}
FolderMutationErrorobject · 1 properties
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
FolderNamestring
A visible, non-hidden single path segment. Dot-prefixed names, path separators, control characters (Cc — the C0 range, DEL, and the C1 range U+0080–U+009F), Unicode format characters (Cf — the zero-width family, the bidi embedding and override controls, the BOM, and the tag characters), and names made only of whitespace or format characters are rejected: none of them survive a nonempty check, and a bidi control can make a folder display a name other than the path it occupies. The pattern is a Unicode-mode expression, as JSON Schema requires, so its `\p{Cc}` and `\p{Cf}` escapes cover the whole categories, format characters above the BMP included; it accepts exactly the names the server accepts.
{
"type": "string",
"minLength": 1,
"pattern": "^(?!\\.)(?![\\s\\S]*[\\\\/\\p{Cc}\\p{Cf}])[\\s\\S]*\\S[\\s\\S]*$",
"description": "A visible, non-hidden single path segment. Dot-prefixed names, path separators, control characters (Cc — the C0 range, DEL, and the C1 range U+0080–U+009F), Unicode format characters (Cf — the zero-width family, the bidi embedding and override controls, the BOM, and the tag characters), and names made only of whitespace or format characters are rejected: none of them survive a nonempty check, and a bidi control can make a folder display a name other than the path it occupies. The pattern is a Unicode-mode expression, as JSON Schema requires, so its `\\p{Cc}` and `\\p{Cf}` escapes cover the whole categories, format characters above the BMP included; it accepts exactly the names the server accepts."
}
FolderStopConflictobject · 3 properties
{
"type": "object",
"required": [
"error",
"needsStop",
"workspaceIds"
],
"properties": {
"error": {
"type": "string",
"minLength": 1
},
"needsStop": {
"type": "boolean",
"const": true
},
"workspaceIds": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/WorkspaceId"
},
"description": "Complete list of running or starting affected workspaces."
}
},
"additionalProperties": false
}
ForgetWorktreeRequestobject · 2 properties
Calling this operation is itself the authorization to stop the workspace's own Uatu sessions first, if it is running — there is no stop: false variant.
{
"type": "object",
"required": [
"reference"
],
"properties": {
"sourceWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"reference": {
"$ref": "#/components/schemas/WorktreeReference"
}
},
"additionalProperties": false,
"description": "Calling this operation is itself the authorization to stop the workspace's own Uatu sessions first, if it is running — there is no stop: false variant."
}
GenerateOpenPgpCredentialRequestobject · 3 properties
{
"type": "object",
"required": [
"name",
"userId",
"passphrase"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"userId": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"passphrase": {
"$ref": "#/components/schemas/Passphrase"
}
},
"additionalProperties": false
}
GenerateSshCredentialRequestobject · 3 properties
{
"type": "object",
"required": [
"name",
"capabilities",
"passphrase"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"capabilities": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"enum": [
"ssh-authentication",
"ssh-signing"
]
}
},
"passphrase": {
"$ref": "#/components/schemas/Passphrase"
}
},
"additionalProperties": false
}
HubStateobject · 6 properties
{
"type": "object",
"required": [
"version",
"hubApiRevision",
"workspaceApiRevision",
"workspaces"
],
"properties": {
"version": {
"type": "string"
},
"hubApiRevision": {
"type": "integer",
"minimum": 1
},
"workspaceApiRevision": {
"type": "integer",
"minimum": 1
},
"workspaces": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HubWorkspace"
}
},
"workspaceDefaults": {
"$ref": "#/components/schemas/WorkspaceDefaults"
},
"worktreeApi": {
"type": "string",
"minLength": 1,
"description": "Present when this Hub serves worktree operations: the origin-rooted path of the published JSON family (GET .../worktrees?source=, POST .../worktrees/{fetch,create,open,preflight-delete,delete,register,forget}). The workspace picker and dashboard mount their worktree affordances from this field's presence alone; no server-rendered worktree URL is published."
}
},
"additionalProperties": false
}
HubWorkspaceobject · 17 properties
{
"type": "object",
"required": [
"id",
"displayName",
"path",
"backend",
"running",
"credentialRestartRequired",
"credentialAssignments",
"workspaceApiRevision"
],
"properties": {
"id": {
"$ref": "#/components/schemas/WorkspaceId"
},
"displayName": {
"$ref": "#/components/schemas/WorkspaceDisplayName"
},
"path": {
"type": "string"
},
"backend": {
"type": "string",
"const": "local"
},
"running": {
"type": "boolean"
},
"credentialRestartRequired": {
"type": "boolean",
"description": "Whether changed credential assignments require this running workspace to restart before its generated credential configuration is current."
},
"credentialAssignments": {
"$ref": "#/components/schemas/WorkspaceCredentialAssignmentSummary"
},
"workspaceApiRevision": {
"type": "integer",
"minimum": 1,
"description": "Workspace API revision spoken by this workspace's child. Matches the top-level workspaceApiRevision for the local backend; backends running children of other builds report the child's own revision."
},
"shells": {
"type": "array",
"items": {
"type": "object",
"required": [
"attached",
"label"
],
"properties": {
"attached": {
"type": "boolean"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
}
},
"parentId": {
"$ref": "#/components/schemas/WorkspaceId",
"description": "Present for a registered linked worktree. The main workspace it belongs to, whose credentials and shared configuration it inherits live. Its own `credentialAssignments` stay its own rows, normally none; read the parent's for the inherited policy."
},
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Opaque canonical repository identity shared by a main workspace and its linked worktrees. Group by this and `parentId`, never by names or paths. Absent when unknown."
},
"branch": {
"type": "string",
"minLength": 1,
"description": "The checkout's current local branch, read from its HEAD. For a linked worktree it is also its name. Absent when detached or unknown."
},
"detached": {
"type": "boolean",
"const": true,
"description": "Present when the checkout's HEAD is detached."
},
"sourceRef": {
"type": "string",
"minLength": 1,
"description": "Linked worktrees only. The recorded ref the branch was created from, when Uatu created it. Never inferred from upstream or history; absent means origin unknown."
},
"ownership": {
"type": "string",
"enum": [
"uatu",
"external",
"uncertain"
],
"description": "Linked worktrees only. `uatu` for a checkout with verified Uatu creation provenance, which alone can be deleted through Uatu."
},
"availability": {
"type": "string",
"enum": [
"missing",
"replaced"
],
"description": "Linked worktrees only, present when the registered checkout is not at its path (`missing`) or the path holds a different checkout (`replaced`). Such a workspace cannot start until resolved outside Uatu."
},
"createWorktree": {
"type": "boolean",
"const": true,
"description": "Present and true for a main checkout that can host linked worktrees. Construct the fork's create request against worktreeApi (mode: new-branch or existing-local/remote-tracking) with sourceWorkspaceId set to this workspace's id; no URL is published here."
}
},
"additionalProperties": false
}
ImportOpenPgpCredentialRequestobject · 2 properties
{
"type": "object",
"required": [
"name",
"privateKey"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"privateKey": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 1048576
}
},
"additionalProperties": false
}
ImportSshCredentialRequestobject · 4 properties
{
"type": "object",
"required": [
"name",
"capabilities",
"privateKey",
"passphrase"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"capabilities": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"enum": [
"ssh-authentication",
"ssh-signing"
]
}
},
"privateKey": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 1048576
},
"passphrase": {
"type": "string",
"maxLength": 4096,
"x-uatu-maxUtf8Bytes": 4096,
"description": "Existing key passphrase, or empty when the imported key is not encrypted. Never persisted or returned."
}
},
"additionalProperties": false
}
LiveConversationKeystring
Agent-qualified conversation id, `<agentId>:<providerConversationId>`, at most 4096 UTF-8 bytes.
{
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 4096,
"description": "Agent-qualified conversation id, `<agentId>:<providerConversationId>`, at most 4096 UTF-8 bytes."
}
LiveCursorstring
Opaque cursor scoped to one subscription, at most 1024 UTF-8 bytes. Conversation cursors are the workspace's own replay ids. The Hub assigns document, inventory, and activity cursors. An empty or absent cursor starts from the current position.
{
"type": "string",
"x-uatu-maxUtf8Bytes": 1024,
"description": "Opaque cursor scoped to one subscription, at most 1024 UTF-8 bytes. Conversation cursors are the workspace's own replay ids. The Hub assigns document, inventory, and activity cursors. An empty or absent cursor starts from the current position."
}
LiveDocumentKeystring
The watch context as a form-urlencoded query string of `compareTarget`, `scope`, and `documentId`, in that order, each only when set. For example `compareTarget=last-commit&scope=file&documentId=README.md`. `compareTarget` is `base` or `last-commit`, `scope` is `folder` or `file`, and `scope=file` also needs `documentId`. Empty or absent means the default context. Streams that present the same key share one upstream subscription. At most 4096 UTF-8 bytes, which leaves room for a file pinned deep in the tree, since `documentId` is a URL-encoded absolute path.
{
"type": "string",
"x-uatu-maxUtf8Bytes": 4096,
"description": "The watch context as a form-urlencoded query string of `compareTarget`, `scope`, and `documentId`, in that order, each only when set. For example `compareTarget=last-commit&scope=file&documentId=README.md`. `compareTarget` is `base` or `last-commit`, `scope` is `folder` or `file`, and `scope=file` also needs `documentId`. Empty or absent means the default context. Streams that present the same key share one upstream subscription. At most 4096 UTF-8 bytes, which leaves room for a file pinned deep in the tree, since `documentId` is a URL-encoded absolute path."
}
LiveSubscription4 variants
A subscription and the cursor to resume it from.
{
"description": "A subscription and the cursor to resume it from.",
"oneOf": [
{
"type": "object",
"required": [
"topic"
],
"properties": {
"topic": {
"type": "string",
"const": "document"
},
"key": {
"$ref": "#/components/schemas/LiveDocumentKey"
},
"cursor": {
"$ref": "#/components/schemas/LiveCursor"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"topic"
],
"properties": {
"topic": {
"type": "string",
"const": "inventory"
},
"cursor": {
"$ref": "#/components/schemas/LiveCursor"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"topic",
"key"
],
"properties": {
"topic": {
"type": "string",
"const": "conversation"
},
"key": {
"$ref": "#/components/schemas/LiveConversationKey"
},
"cursor": {
"$ref": "#/components/schemas/LiveCursor"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"topic"
],
"properties": {
"topic": {
"type": "string",
"const": "worktrees"
},
"cursor": {
"$ref": "#/components/schemas/LiveCursor",
"description": "Ignored. The worktrees topic has no replay cursor; every attach receives a fresh invalidation."
}
},
"additionalProperties": false
}
]
}
LiveSubscriptionChangeobject · 2 properties
Removals apply before additions. Adding a topic and key that is already subscribed replaces the subscription and re-attaches it from the new cursor.
{
"type": "object",
"properties": {
"add": {
"$ref": "#/components/schemas/LiveSubscriptionList"
},
"remove": {
"$ref": "#/components/schemas/LiveSubscriptionKeyList"
}
},
"additionalProperties": false,
"description": "Removals apply before additions. Adding a topic and key that is already subscribed replaces the subscription and re-attaches it from the new cursor."
}
LiveSubscriptionKey4 variants
One subscription on a stream, meaning a topic and its key where the topic has one. The activity topic is not subscribed here. Request it with the stream's `activity` parameter.
{
"description": "One subscription on a stream, meaning a topic and its key where the topic has one. The activity topic is not subscribed here. Request it with the stream's `activity` parameter.",
"oneOf": [
{
"type": "object",
"required": [
"topic"
],
"properties": {
"topic": {
"type": "string",
"const": "document"
},
"key": {
"$ref": "#/components/schemas/LiveDocumentKey"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"topic"
],
"properties": {
"topic": {
"type": "string",
"const": "inventory"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"topic",
"key"
],
"properties": {
"topic": {
"type": "string",
"const": "conversation"
},
"key": {
"$ref": "#/components/schemas/LiveConversationKey"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"topic"
],
"properties": {
"topic": {
"type": "string",
"const": "worktrees"
}
},
"additionalProperties": false
}
]
}
LiveSubscriptionKeyListarray
{
"type": "array",
"maxItems": 16,
"items": {
"$ref": "#/components/schemas/LiveSubscriptionKey"
}
}
LiveSubscriptionListarray
At most 16 entries. A later entry for the same topic and key replaces an earlier one.
{
"type": "array",
"maxItems": 16,
"items": {
"$ref": "#/components/schemas/LiveSubscription"
},
"description": "At most 16 entries. A later entry for the same topic and key replaces an earlier one."
}
LiveSubscriptionsUpdatedobject · 1 properties
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
}
MessageAttachmentobject · 3 properties
An image riding a user message, referenced by workspace attachment id — never by bytes. `id` is absent on a replayed attachment whose reference could not be recovered; clients render those as labeled placeholders.
{
"type": "object",
"required": [
"name",
"mimeType"
],
"description": "An image riding a user message, referenced by workspace attachment id — never by bytes. `id` is absent on a replayed attachment whose reference could not be recovered; clients render those as labeled placeholders.",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"mimeType": {
"type": "string",
"enum": [
"image/png",
"image/jpeg",
"image/gif",
"image/webp"
]
}
},
"additionalProperties": false
}
ModelSelectionobject · 2 properties
{
"type": "object",
"required": [
"providerId",
"modelId"
],
"properties": {
"providerId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"modelId": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"additionalProperties": false
}
NativeLoginRequestobject · 3 properties
{
"type": "object",
"required": [
"name",
"password"
],
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
},
"deviceLabel": {
"type": "string"
}
},
"additionalProperties": false
}
NativeLoginResponseobject · 2 properties
{
"type": "object",
"required": [
"sessionId",
"user"
],
"properties": {
"sessionId": {
"type": "string"
},
"user": {
"type": "string"
}
},
"additionalProperties": false
}
NotificationEnrollmentobject · 6 properties
{
"type": "object",
"required": [
"subscription",
"workspaceIds",
"needsAnswer",
"completed"
],
"properties": {
"id": {
"type": "string",
"maxLength": 128
},
"subscription": {
"type": "object",
"required": [
"endpoint",
"keys"
],
"properties": {
"endpoint": {
"type": "string",
"format": "uri",
"maxLength": 4096
},
"expirationTime": {
"type": [
"number",
"null"
]
},
"keys": {
"type": "object",
"required": [
"p256dh",
"auth"
],
"properties": {
"p256dh": {
"type": "string"
},
"auth": {
"type": "string"
}
}
}
}
},
"workspaceIds": {
"type": "array",
"maxItems": 256,
"items": {
"type": "string"
}
},
"allWorkspaces": {
"type": "boolean",
"default": false,
"description": "Cover every accessible workspace, including ones registered later, instead of `workspaceIds`."
},
"needsAnswer": {
"type": "boolean"
},
"completed": {
"type": "boolean"
}
}
}
NotificationStateobject · 3 properties
{
"type": "object",
"required": [
"configured",
"publicKey",
"device"
],
"additionalProperties": false,
"properties": {
"configured": {
"type": "boolean"
},
"publicKey": {
"type": [
"string",
"null"
]
},
"device": {
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"id",
"allWorkspaces",
"workspaceIds",
"needsAnswer",
"completed",
"active"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"allWorkspaces": {
"type": "boolean",
"description": "True when the device covers every accessible workspace as a standing rule; `workspaceIds` then holds the explicit selection it overrides."
},
"workspaceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"needsAnswer": {
"type": "boolean"
},
"completed": {
"type": "boolean"
},
"active": {
"type": "boolean"
}
}
}
]
}
}
}
OnboardedWorkspaceobject · 5 properties
{
"type": "object",
"required": [
"id",
"displayName",
"path",
"backend",
"running"
],
"properties": {
"id": {
"$ref": "#/components/schemas/WorkspaceId"
},
"displayName": {
"$ref": "#/components/schemas/WorkspaceDisplayName"
},
"path": {
"type": "string"
},
"backend": {
"type": "string",
"const": "local"
},
"running": {
"type": "boolean"
}
},
"additionalProperties": false
}
OpenWorktreeRequestobject · 3 properties
{
"type": "object",
"required": [
"reference"
],
"properties": {
"sourceWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"reference": {
"$ref": "#/components/schemas/WorktreeReference"
},
"start": {
"type": "boolean"
}
},
"additionalProperties": false
}
Passphrasestring
One-operation secret; never persisted or returned.
{
"type": "string",
"minLength": 1,
"maxLength": 4096,
"x-uatu-maxUtf8Bytes": 4096,
"description": "One-operation secret; never persisted or returned."
}
PermissionChoiceobject · 3 properties
{
"type": "object",
"required": [
"id",
"label"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string"
}
},
"additionalProperties": false
}
PermissionItemobject · 16 properties
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"requestId",
"action",
"resources",
"status"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "permission"
},
"createdAt": {
"type": "number"
},
"requestId": {
"type": "string"
},
"conversationId": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "Conversation that owns this request. Differs from the containing conversation when a subagent's request is shown in the conversation that launched it; answers are addressed here."
},
"action": {
"type": "string"
},
"resources": {
"type": "array",
"items": {
"type": "string"
}
},
"alwaysPatterns": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "What the persistent approval (`approved-session`) will authorize, in the owning agent's own syntax (OpenCode `git status *`, Claude Code `Bash(git status:*)`). Distinct from `resources`: the agent derives a reusable pattern from the request, and that pattern is what it installs. Empty means the agent supplied nothing reusable; absent means it did not say. Render verbatim; never derive scope from a resource."
},
"status": {
"enum": [
"pending",
"resolved"
]
},
"outcome": {
"enum": [
"approved-once",
"approved-session",
"rejected"
]
},
"diff": {
"type": "string",
"description": "Unified diff a file-edit permission would apply, when the agent attaches one. Absent for a permission with nothing to show."
},
"plan": {
"type": "string",
"description": "The plan this approval would put into effect, as markdown (a Claude Code plan approval)."
},
"choices": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/PermissionChoice"
},
"description": "Agent-provided approval intents. When present they replace the generic approve pair; rejecting stays universal."
},
"choiceId": {
"type": "string",
"description": "On resolution: the choice that approved it, when choices were offered."
},
"sourceToolId": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "The `tool` item this permission belongs to (`tool:<call id>`), when the agent names the call it is asking about (OpenCode 2.x `source`). What lets a request naming no resource of its own (an MCP tool's `*`) show the arguments of the call it would allow. Absent when the agent did not say; a client then falls back to the running tool row bearing the request's `action`."
},
"mcp": {
"$ref": "#/components/schemas/PermissionMcpTool"
}
},
"additionalProperties": false
}
PermissionMcpToolobject · 2 properties
The MCP server and tool a permission's `action` names, when the action is an MCP tool's registry name (`<server>_<tool>`, each half sanitized by OpenCode) and the agent resolved it against the MCP servers it reports. `server` is the name the user registered; `tool` the remainder. Absent for a built-in tool or an action no reported server matches. The `action` remains what a persistent approval installs.
{
"type": "object",
"description": "The MCP server and tool a permission's `action` names, when the action is an MCP tool's registry name (`<server>_<tool>`, each half sanitized by OpenCode) and the agent resolved it against the MCP servers it reports. `server` is the name the user registered; `tool` the remainder. Absent for a built-in tool or an action no reported server matches. The `action` remains what a persistent approval installs.",
"required": [
"server",
"tool"
],
"properties": {
"server": {
"type": "string",
"minLength": 1
},
"tool": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
PersonalStateobject · 7 properties
{
"type": "object",
"required": [
"version"
],
"properties": {
"version": {
"const": 1
},
"documentPath": {
"type": "string"
},
"follow": {
"type": "boolean"
},
"previewMode": {
"$ref": "#/components/schemas/ViewMode"
},
"compareTarget": {
"enum": [
"base",
"last-commit"
]
},
"filesFilter": {
"enum": [
"all",
"changed"
]
},
"lastPtyId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
}
PersonalStatePatchobject · 7 properties
{
"type": "object",
"properties": {
"version": {
"const": 1
},
"documentPath": {
"type": [
"string",
"null"
]
},
"follow": {
"type": [
"boolean",
"null"
]
},
"previewMode": {
"oneOf": [
{
"$ref": "#/components/schemas/ViewMode"
},
{
"type": "null"
}
]
},
"compareTarget": {
"enum": [
"base",
"last-commit",
null
]
},
"filesFilter": {
"enum": [
"all",
"changed",
null
]
},
"lastPtyId": {
"oneOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
PlanUtilizationobject · 2 properties
Plan utilization the login reports (claude.ai plans only). Empty when the login reports no windows (an API-key session). Absent from a report that does not speak to the plan (a compaction's post-count, an agent that never reports it): the previous report's plan then still stands.
{
"type": "object",
"description": "Plan utilization the login reports (claude.ai plans only). Empty when the login reports no windows (an API-key session). Absent from a report that does not speak to the plan (a compaction's post-count, an agent that never reports it): the previous report's plan then still stands.",
"properties": {
"fiveHour": {
"$ref": "#/components/schemas/PlanUtilizationWindow"
},
"sevenDay": {
"$ref": "#/components/schemas/PlanUtilizationWindow"
}
},
"additionalProperties": false
}
PlanUtilizationWindowobject · 2 properties
{
"type": "object",
"properties": {
"utilization": {
"type": "number",
"minimum": 0,
"description": "Percent of the window used, 0-100."
},
"resetsAt": {
"type": "number",
"minimum": 0,
"description": "When the window resets."
}
},
"additionalProperties": false
}
PreflightDeleteWorktreeRequestobject · 2 properties
{
"type": "object",
"required": [
"reference"
],
"properties": {
"sourceWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"reference": {
"$ref": "#/components/schemas/WorktreeReference"
}
},
"additionalProperties": false
}
PublicCredential3 variants
Explicit public DTO. It never contains a private key, passphrase, token value, secret path, or reusable agent credential.
{
"oneOf": [
{
"$ref": "#/components/schemas/PublicSshCredential"
},
{
"$ref": "#/components/schemas/PublicOpenPgpCredential"
},
{
"$ref": "#/components/schemas/PublicTokenCredential"
}
],
"description": "Explicit public DTO. It never contains a private key, passphrase, token value, secret path, or reusable agent credential."
}
PublicCredentialToolobject · 5 properties
{
"type": "object",
"required": [
"tool",
"path",
"version",
"results",
"guidance"
],
"properties": {
"tool": {
"$ref": "#/components/schemas/CredentialToolName"
},
"path": {
"type": [
"string",
"null"
]
},
"version": {
"type": [
"string",
"null"
]
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReadinessResult"
}
},
"guidance": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
PublicOpenPgpCredentialobject · 9 properties
{
"type": "object",
"required": [
"id",
"name",
"type",
"capabilities",
"enabled",
"createdAt",
"metadata",
"assignments",
"readiness"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CredentialId"
},
"name": {
"type": "string",
"minLength": 1
},
"type": {
"const": "openpgp"
},
"capabilities": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"uniqueItems": true,
"items": {
"const": "openpgp-signing"
}
},
"enabled": {
"type": "boolean"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"required": [
"publicKey",
"fingerprint"
],
"properties": {
"publicKey": {
"type": "string",
"minLength": 1
},
"fingerprint": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"assignments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CredentialAssignment"
}
},
"readiness": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReadinessResult"
}
}
},
"additionalProperties": false
}
PublicSshCredentialobject · 9 properties
{
"type": "object",
"required": [
"id",
"name",
"type",
"capabilities",
"enabled",
"createdAt",
"metadata",
"assignments",
"readiness"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CredentialId"
},
"name": {
"type": "string",
"minLength": 1
},
"type": {
"const": "ssh"
},
"capabilities": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"enum": [
"ssh-authentication",
"ssh-signing"
]
}
},
"enabled": {
"type": "boolean"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"required": [
"publicKey",
"fingerprint"
],
"properties": {
"publicKey": {
"type": "string",
"minLength": 1
},
"fingerprint": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"assignments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CredentialAssignment"
}
},
"readiness": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReadinessResult"
}
}
},
"additionalProperties": false
}
PublicTokenCredentialobject · 9 properties
{
"type": "object",
"required": [
"id",
"name",
"type",
"capabilities",
"enabled",
"createdAt",
"metadata",
"assignments",
"readiness"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CredentialId"
},
"name": {
"type": "string",
"minLength": 1
},
"type": {
"const": "token"
},
"capabilities": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"enum": [
"https-git",
"github-cli",
"gitlab-cli"
]
}
},
"enabled": {
"type": "boolean"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"required": [
"host"
],
"properties": {
"host": {
"type": "string",
"minLength": 1
},
"username": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"assignments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CredentialAssignment"
}
},
"readiness": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReadinessResult"
}
}
},
"additionalProperties": false
}
QuestionItemobject · 12 properties
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"requestId",
"questions",
"status"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"const": "question"
},
"createdAt": {
"type": "number"
},
"requestId": {
"type": "string"
},
"conversationId": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "Conversation that owns this request. See PermissionItem.conversationId."
},
"questions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StructuredQuestion"
}
},
"status": {
"enum": [
"pending",
"resolved"
]
},
"outcome": {
"$ref": "#/components/schemas/QuestionOutcome"
},
"source": {
"enum": [
"dialog",
"elicitation"
],
"description": "Who is asking, beyond the agent's own question tool: a tool-driven blocking dialog the agent asked the host to render, or an MCP server's elicitation. Answered and rejected through the same question operations."
},
"intro": {
"type": "string",
"minLength": 1,
"description": "A sentence of context shown above the form: the server and message behind an elicitation, the refusal a dialog is about."
},
"link": {
"type": "string",
"minLength": 1,
"pattern": "^https?://",
"description": "A link the request asks the user to open (a URL-mode elicitation)."
},
"schema": {
"type": "object",
"description": "The request as received (an elicitation's JSON schema, a dialog's kind and payload), for a reader auditing what was asked. Opaque."
}
},
"additionalProperties": false
}
QuestionOutcome2 variants
{
"oneOf": [
{
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"const": "rejected"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"answers"
],
"properties": {
"kind": {
"const": "answered"
},
"answers": {
"type": "array",
"maxItems": 32,
"description": "One answer array per question, in the same order as QuestionItem.questions. Offered option labels and, when allowFreeForm is true, ordinary custom strings are sent directly in each array; an array is empty only for a question marked optional.",
"items": {
"type": "array",
"minItems": 0,
"maxItems": 32,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"pattern": "\\S"
}
}
}
},
"additionalProperties": false
}
]
}
QueuedMessageobject · 5 properties
A submission the workspace holds until the running turn ends. Not a timeline item; it becomes one when delivered. `requestId` echoes the accepting mutation's client request id so the submitting client can reconcile.
{
"type": "object",
"required": [
"id",
"text",
"queuedAt"
],
"description": "A submission the workspace holds until the running turn ends. Not a timeline item; it becomes one when delivered. `requestId` echoes the accepting mutation's client request id so the submitting client can reconcile.",
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string",
"description": "Empty for an image-only message."
},
"queuedAt": {
"type": "number"
},
"requestId": {
"type": "string"
},
"attachments": {
"type": "array",
"maxItems": 8,
"items": {
"$ref": "#/components/schemas/MessageAttachment"
}
}
},
"additionalProperties": false
}
ReadinessResultobject · 3 properties
{
"type": "object",
"required": [
"layer",
"status",
"message"
],
"properties": {
"layer": {
"enum": [
"binary",
"version",
"runtime",
"credential",
"capability"
]
},
"status": {
"enum": [
"ready",
"unavailable",
"not-applicable"
]
},
"message": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
RegisterWorktreeRequestobject · 3 properties
{
"type": "object",
"required": [
"reference"
],
"properties": {
"sourceWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"reference": {
"$ref": "#/components/schemas/WorktreeReference"
},
"start": {
"type": "boolean"
}
},
"additionalProperties": false
}
RemoveFolderRequestobject · 2 properties
{
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Absolute path of the empty direct non-symbolic-link directory to remove."
},
"stop": {
"type": "boolean",
"default": false,
"description": "Authorizes stopping the affected workspace session before mutation."
}
},
"additionalProperties": false
}
RemoveFolderResultobject · 2 properties
{
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Absolute path removed by the operation."
},
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId",
"description": "Stable id of the registration removed with the folder",
"when one existed.": null
}
},
"additionalProperties": false
}
RenameFolderRequestobject · 3 properties
{
"type": "object",
"required": [
"path",
"name"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Absolute path of the direct non-symbolic-link directory to rename."
},
"name": {
"$ref": "#/components/schemas/FolderName"
},
"stop": {
"type": "boolean",
"default": false,
"description": "Authorizes stopping all affected workspace sessions before mutation."
}
},
"additionalProperties": false
}
RenameFolderResultobject · 2 properties
{
"type": "object",
"required": [
"path",
"workspaceIds"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Absolute destination path."
},
"workspaceIds": {
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/WorkspaceId"
},
"description": "Stable ids of every registration moved with the folder."
}
},
"additionalProperties": false
}
RepositoryFreshnessobject · 3 properties
{
"type": "object",
"required": [
"generation",
"status"
],
"properties": {
"generation": {
"type": "integer",
"minimum": 0
},
"status": {
"enum": [
"pending",
"ready",
"stale",
"error"
]
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
RepositorySnapshotobject · 12 properties
{
"type": "object",
"required": [
"id",
"rootPath",
"label",
"watchedRootIds",
"metadata",
"status",
"base",
"changedFiles",
"gitIgnoredFiles",
"configWarnings",
"message",
"commitLog"
],
"properties": {
"id": {
"type": "string"
},
"rootPath": {
"type": "string"
},
"label": {
"type": "string"
},
"watchedRootIds": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"enum": [
"available",
"non-git",
"unavailable"
]
},
"base": {
"type": "object",
"additionalProperties": true
},
"changedFiles": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"gitIgnoredFiles": {
"type": "array",
"items": {
"type": "string"
}
},
"configWarnings": {
"type": "array",
"items": {
"type": "string"
}
},
"message": {
"type": [
"string",
"null"
]
},
"commitLog": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommitLogEntry"
}
}
},
"additionalProperties": false
}
RevocationResultobject · 2 properties
{
"type": "object",
"required": [
"revoked"
],
"properties": {
"revoked": {
"type": "boolean"
},
"current": {
"type": "boolean"
}
},
"additionalProperties": false
}
RootGroupobject · 5 properties
{
"type": "object",
"required": [
"id",
"label",
"path",
"docs",
"hiddenCount"
],
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"path": {
"type": "string"
},
"docs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentMeta"
}
},
"hiddenCount": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}
SetCredentialToolRequestobject · 1 properties
{
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": [
"string",
"null"
],
"x-uatu-maxUtf8Bytes": 32768
}
},
"additionalProperties": false
}
SigningAssignmentRequestobject · 3 properties
{
"type": "object",
"required": [
"workspaceId",
"role"
],
"properties": {
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"role": {
"const": "signing"
},
"replace": {
"type": "boolean"
}
},
"additionalProperties": false
}
SigningCredentialAssignmentobject · 3 properties
{
"type": "object",
"required": [
"workspaceId",
"credentialId",
"role"
],
"properties": {
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"credentialId": {
"$ref": "#/components/schemas/CredentialId"
},
"role": {
"const": "signing"
}
},
"additionalProperties": false
}
StructuredQuestionobject · 6 properties
{
"type": "object",
"required": [
"prompt",
"header",
"options",
"multiple",
"allowFreeForm"
],
"properties": {
"prompt": {
"type": "string"
},
"header": {
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"description"
],
"properties": {
"label": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false
}
},
"multiple": {
"type": "boolean"
},
"allowFreeForm": {
"type": "boolean"
},
"optional": {
"type": "boolean",
"description": "The question may be answered with an empty answer array (an optional field of an elicitation form). Absent means required."
}
},
"additionalProperties": false
}
SubagentLineobject · 7 properties
A subagent launched by a subagent, as a line beneath the task row that launched its branch. Lines sharing a `conversationId` are one subagent given several tasks.
{
"type": "object",
"description": "A subagent launched by a subagent, as a line beneath the task row that launched its branch. Lines sharing a `conversationId` are one subagent given several tasks.",
"required": [
"id",
"parentId",
"description",
"conversationId"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "The launching row's item id in its own conversation. Unique within the list."
},
"parentId": {
"type": "string",
"minLength": 1,
"description": "The task row carrying the list, or an earlier line in it: what launched this subagent."
},
"description": {
"type": "string",
"minLength": 1
},
"subagent": {
"type": "string",
"description": "The kind of subagent, where the launcher named one."
},
"conversationId": {
"type": "string",
"minLength": 1,
"description": "The subagent's own session."
},
"model": {
"type": "string"
},
"usage": {
"allOf": [
{
"$ref": "#/components/schemas/TokenUsage"
}
],
"description": "What the subagent spent on this task alone. Absent until it has reported any."
}
},
"additionalProperties": false
}
TaskProgressEntryobject · 3 properties
{
"type": "object",
"required": [
"text",
"status"
],
"properties": {
"text": {
"type": "string",
"minLength": 1
},
"status": {
"enum": [
"pending",
"in_progress",
"completed"
]
},
"activeText": {
"type": "string",
"description": "Present-continuous label shown while in progress, when the agent provides one."
}
},
"additionalProperties": false
}
TimelineBaseobject · 3 properties
{
"type": "object",
"required": [
"id",
"type",
"createdAt"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"createdAt": {
"type": "number",
"minimum": 0
}
}
}
TokenUsageobject · 6 properties
What a message spent, as the agent reports it. Every component is optional: an absent one means the agent did not report it, which is not the same statement as zero. Window occupancy is input + cacheRead + cacheWrite; output is what came back rather than what occupies the window.
{
"type": "object",
"description": "What a message spent, as the agent reports it. Every component is optional: an absent one means the agent did not report it, which is not the same statement as zero. Window occupancy is input + cacheRead + cacheWrite; output is what came back rather than what occupies the window.",
"properties": {
"input": {
"type": "integer",
"minimum": 0
},
"output": {
"type": "integer",
"minimum": 0
},
"reasoning": {
"type": "integer",
"minimum": 0
},
"cacheRead": {
"type": "integer",
"minimum": 0
},
"cacheWrite": {
"type": "integer",
"minimum": 0
},
"costUsd": {
"type": "number",
"minimum": 0,
"description": "What the message cost in USD, where the agent prices its messages (OpenCode reports one per assistant message). Not a token component. Absent means the agent did not price it, which is not the same statement as zero; zero is what OpenCode reports for a model it has no price for."
}
},
"additionalProperties": false
}
UnassignCredentialRequest3 variants
{
"oneOf": [
{
"type": "object",
"required": [
"workspaceId",
"role",
"host"
],
"properties": {
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"role": {
"const": "authentication"
},
"host": {
"type": "string",
"minLength": 1,
"x-uatu-maxUtf8Bytes": 256
},
"stop": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"workspaceId",
"role"
],
"properties": {
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"role": {
"const": "signing"
},
"stop": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"stop": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
}
UnlockCredentialRequestobject · 1 properties
{
"type": "object",
"required": [
"passphrase"
],
"properties": {
"passphrase": {
"type": "string",
"maxLength": 4096,
"x-uatu-maxUtf8Bytes": 4096,
"description": "One-operation secret. Empty is valid for an unencrypted SSH key; OpenPGP unlock still requires a nonempty passphrase. Never persisted or returned."
}
},
"additionalProperties": false
}
UpdateWorkspaceDefaultsRequestobject · 1 properties
{
"type": "object",
"required": [
"defaultWorkspaceParent"
],
"properties": {
"defaultWorkspaceParent": {
"type": [
"string",
"null"
],
"description": "Absolute path of an existing direct non-symbolic-link directory, or null to clear the preference."
}
},
"additionalProperties": false
}
UpdateWorkspaceDisplayNameRequestobject · 1 properties
{
"type": "object",
"required": [
"displayName"
],
"properties": {
"displayName": {
"$ref": "#/components/schemas/WorkspaceDisplayName"
}
},
"additionalProperties": false
}
ViewModeschema
{
"enum": [
"rendered",
"source",
"diff"
]
}
WorkspaceActionobject · 5 properties
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/WorkspaceId"
},
"running": {
"type": "boolean"
},
"wasRunning": {
"type": "boolean"
},
"forgotten": {
"type": "boolean"
},
"recoveryRequired": {
"type": "string",
"description": "Registration only: the workspace committed but its recovery journal could not be cleared. The workspace is registered and stopped — any requested start was not attempted — and the Hub needs a restart before starts, assignment changes, folder mutations, and further registration resume."
}
},
"additionalProperties": false
}
WorkspaceConflict1 combined schemas
{
"allOf": [
{
"$ref": "#/components/schemas/Error"
}
]
}
WorkspaceCredentialAssignmentSummaryobject · 2 properties
{
"type": "object",
"required": [
"authentication",
"signing"
],
"properties": {
"authentication": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
},
"description": "Deduplicated public names of credentials assigned for Git authentication, regardless of current usability."
},
"signing": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
},
"description": "Deduplicated public names of credentials assigned for commit signing, regardless of current usability."
}
},
"additionalProperties": false
}
WorkspaceDefaultsobject · 3 properties
{
"type": "object",
"required": [
"configured",
"configuredAvailable",
"effective"
],
"properties": {
"configured": {
"type": [
"string",
"null"
],
"description": "The saved canonical default workspace parent, retained for diagnosis even while unavailable."
},
"configuredAvailable": {
"type": "boolean",
"description": "Whether the configured directory is currently a readable direct directory."
},
"effective": {
"type": "string",
"description": "Where pathless browse/create/clone flows start: the configured parent while usable, the daemon user's home otherwise."
}
},
"additionalProperties": false
}
WorkspaceDisplayNamestring
Mutable human-facing workspace label. Trimmed, 1-64 visible characters, no control characters. Never unique and never part of URLs; the stable workspace id is the routing identity.
{
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Mutable human-facing workspace label. Trimmed, 1-64 visible characters, no control characters. Never unique and never part of URLs; the stable workspace id is the routing identity."
}
WorkspaceIdstring
{
"type": "string",
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
}
WorkspaceOnboardingErrorobject · 3 properties
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"minLength": 1
},
"needsInit": {
"type": "boolean",
"const": true,
"description": "The folder is not a Git repository; re-submit with init true after user confirmation."
},
"retainedPath": {
"type": "string",
"description": "A created repository was initialized before the failure and is retained at this path; retry through the Existing folder flow."
}
},
"additionalProperties": false
}
WorkspaceOnboardingResultobject · 4 properties
{
"type": "object",
"required": [
"workspace",
"started",
"startError"
],
"properties": {
"workspace": {
"$ref": "#/components/schemas/OnboardedWorkspace"
},
"started": {
"type": "boolean"
},
"startError": {
"type": [
"string",
"null"
],
"description": "Non-null exactly when an explicitly requested start failed after the configuration committed; the workspace is preserved stopped for retry."
},
"recoveryRequired": {
"type": "string",
"description": "Present when the configuration committed but its recovery journal could not be cleared: the workspace is preserved stopped, and the Hub needs a restart before starts, assignment changes, folder mutations, and further onboarding resume."
}
},
"additionalProperties": false
}
WorkspaceStateobject · 18 properties
{
"type": "object",
"required": [
"kind",
"epoch",
"revision",
"discovery",
"repositoryState",
"workspaceApiRevision",
"roots",
"repositories",
"compareTarget",
"initialFollow",
"defaultDocumentId",
"changedId",
"generatedAt",
"build",
"scope"
],
"properties": {
"kind": {
"const": "snapshot"
},
"epoch": {
"type": "string"
},
"revision": {
"type": "integer",
"minimum": 0
},
"discovery": {
"$ref": "#/components/schemas/DocumentDiscovery"
},
"repositoryState": {
"$ref": "#/components/schemas/RepositoryFreshness"
},
"latestChange": {
"type": "object",
"required": [
"id",
"revision"
],
"properties": {
"id": {
"type": "string"
},
"revision": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"workspaceApiRevision": {
"type": "integer",
"minimum": 1
},
"roots": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RootGroup"
}
},
"repositories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RepositorySnapshot"
}
},
"compareTarget": {
"enum": [
"base",
"last-commit"
]
},
"initialFollow": {
"type": "boolean"
},
"defaultDocumentId": {
"type": [
"string",
"null"
]
},
"changedId": {
"type": [
"string",
"null"
]
},
"generatedAt": {
"type": "number"
},
"build": {
"$ref": "#/components/schemas/BuildSummary"
},
"scope": {
"oneOf": [
{
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"const": "folder"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"documentId"
],
"properties": {
"kind": {
"const": "file"
},
"documentId": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"unscopedFingerprint": {
"type": "string"
},
"terminal": {
"enum": [
"enabled",
"disabled"
]
}
},
"additionalProperties": false
}
WorkspaceSummaryResponseobject · 1 properties
{
"type": "object",
"required": [
"workspace"
],
"properties": {
"workspace": {
"$ref": "#/components/schemas/OnboardedWorkspace"
}
},
"additionalProperties": false
}
WorktreeAvailabilitystring
`present` is the ordinary case. `missing` is a registered path that is not there; `replaced` is a path occupied by a different checkout. Neither is ever silently repaired, and neither can start.
{
"type": "string",
"enum": [
"present",
"missing",
"replaced"
],
"description": "`present` is the ordinary case. `missing` is a registered path that is not there; `replaced` is a path occupied by a different checkout. Neither is ever silently repaired, and neither can start."
}
WorktreeCheckoutobject · 16 properties
{
"type": "object",
"required": [
"checkoutId",
"repositoryId",
"path",
"branch",
"detached",
"main",
"ownership",
"availability",
"registered",
"running",
"locked"
],
"properties": {
"checkoutId": {
"type": "string",
"minLength": 1,
"description": "Canonical identity of this checkout. Ownership and every destructive action are decided on this, never on a path: a path reused by another tree must not inherit an older record's ownership."
},
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Canonical repository identity shared by a main checkout and its linked worktrees. Group by this, never by names or paths."
},
"workspaceId": {
"$ref": "#/components/schemas/WorkspaceId",
"description": "The Hub registration, present only once registered. Present exactly when `registered` is true."
},
"parentWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId",
"description": "The registered main workspace this checkout belongs to, when known. It owns the credential policy this checkout inherits live."
},
"path": {
"type": "string",
"minLength": 1
},
"branch": {
"type": [
"string",
"null"
],
"minLength": 1,
"description": "The exact local branch, slashes included; for a linked worktree it is also its display name. Null for a detached or unreadable HEAD, which is stated rather than guessed."
},
"detached": {
"type": "boolean"
},
"main": {
"type": "boolean",
"description": "Whether this is the repository's main checkout. A main checkout is never deletable through Uatu."
},
"ownership": {
"$ref": "#/components/schemas/WorktreeOwnership"
},
"availability": {
"$ref": "#/components/schemas/WorktreeAvailability"
},
"registered": {
"type": "boolean"
},
"running": {
"type": "boolean"
},
"locked": {
"type": "boolean",
"description": "Whether Git reports the checkout locked. A locked checkout is never removed."
},
"sourceRef": {
"type": "string",
"minLength": 1,
"description": "Immutable branch-creation snapshot: the ref explicitly selected when Uatu created this branch. Not the upstream and not the starting revision, and never inferred from either. Absent means the origin is unknown."
},
"upstream": {
"type": "string",
"minLength": 1
},
"head": {
"type": "string",
"minLength": 1,
"description": "Short revision, for diagnostics. Never provenance."
}
},
"additionalProperties": false
}
WorktreeDeletionPreflightobject · 5 properties
ok: true carries checkout and requiresStop, and localData when the checkout has local data; ok: false carries error and, when the checkout itself was identified before the blocker was found, checkout too.
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"checkout": {
"$ref": "#/components/schemas/WorktreeCheckout"
},
"requiresStop": {
"type": "boolean",
"description": "Present when ok is true: whether proceeding to delete needs the caller's explicit stop authorization."
},
"localData": {
"$ref": "#/components/schemas/WorktreeLocalData",
"description": "Present only when ok is true and the checkout has local data: what deletion would permanently discard, and the fingerprint a deletion must echo back to acknowledge it."
},
"error": {
"$ref": "#/components/schemas/WorktreeError",
"description": "The ONE blocker that replaces deletion's normal consequences. No acknowledgement and no client-supplied force gets past it."
}
},
"additionalProperties": false,
"description": "ok: true carries checkout and requiresStop, and localData when the checkout has local data; ok: false carries error and, when the checkout itself was identified before the blocker was found, checkout too."
}
WorktreeErrorobject · 6 properties
{
"type": "object",
"required": [
"code",
"message",
"retry"
],
"properties": {
"code": {
"$ref": "#/components/schemas/WorktreeErrorCode"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "Already sanitized: no absolute path, no credential, no control character, bounded length. Safe to show a user verbatim."
},
"retry": {
"$ref": "#/components/schemas/WorktreeRetryAction"
},
"conflictCheckoutId": {
"type": "string",
"minLength": 1,
"description": "The existing checkout an occupancy conflict points at, to open instead of forcing."
},
"retainedCheckoutId": {
"type": "string",
"minLength": 1,
"description": "A checkout that outlived a failed operation and must not be recreated."
},
"phase": {
"$ref": "#/components/schemas/WorktreePhase"
}
},
"additionalProperties": false
}
WorktreeErrorCodestring
The closed set of refusals. A client that cannot map a code refuses rather than inventing a recovery.
{
"type": "string",
"enum": [
"invalid-input",
"git-unsupported",
"not-found",
"branch-exists",
"branch-in-use",
"destination-occupied",
"ref-unavailable",
"fetch-authentication",
"fetch-network",
"registration-failed",
"start-failed",
"local-data",
"git-lock",
"external-activity",
"nested-dependency",
"stop-failed",
"ownership-required",
"identity-uncertain",
"inventory-unavailable",
"folder-dependency",
"folder-dependency-unknown",
"conflict",
"permission-denied",
"timeout",
"cancelled",
"internal"
],
"description": "The closed set of refusals. A client that cannot map a code refuses rather than inventing a recovery."
}
WorktreeInventoryResponseobject · 1 properties
{
"type": "object",
"required": [
"inventory"
],
"properties": {
"inventory": {
"type": "object",
"required": [
"repositoryId",
"sourceWorkspaceId",
"status",
"checkouts",
"refs"
],
"properties": {
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "The reserved word `unknown` when the repository could not be identified at all, which is legal only on an explicitly stale error listing with no checkouts."
},
"sourceWorkspaceId": {
"$ref": "#/components/schemas/WorkspaceId"
},
"status": {
"type": "string",
"enum": [
"ready",
"loading",
"error"
]
},
"checkouts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorktreeCheckout"
}
},
"refs": {
"$ref": "#/components/schemas/WorktreeRefs"
},
"error": {
"$ref": "#/components/schemas/WorktreeError",
"description": "Present when status is error: the listing shown is explicitly stale."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
WorktreeLocalDataobject · 4 properties
Local data a deletion would permanently discard. A category is present only when it has at least one entry, and at least one is present.
{
"type": "object",
"required": [
"fingerprint"
],
"minProperties": 2,
"properties": {
"tracked": {
"$ref": "#/components/schemas/WorktreeLocalDataCategory",
"description": "Staged or unstaged changes to tracked files."
},
"untracked": {
"$ref": "#/components/schemas/WorktreeLocalDataCategory",
"description": "Untracked files."
},
"ignored": {
"$ref": "#/components/schemas/WorktreeLocalDataCategory",
"description": "Ignored entries; a wholly ignored directory is one entry, listed with its trailing `/`, and stands for that folder and everything inside it."
},
"fingerprint": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Opaque: identifies the complete set of local-data status entries across all three categories, bound to this checkout. Echo it back as the deletion's `localDataFingerprint`."
}
},
"additionalProperties": false,
"description": "Local data a deletion would permanently discard. A category is present only when it has at least one entry, and at least one is present."
}
WorktreeLocalDataCategoryobject · 2 properties
{
"type": "object",
"required": [
"count",
"sample"
],
"properties": {
"count": {
"type": "integer",
"minimum": 1,
"description": "Status entries in this category."
},
"sample": {
"type": "array",
"maxItems": 5,
"items": {
"type": "string",
"minLength": 1,
"pattern": "^[^/]",
"description": "A checkout-relative path, never absolute."
},
"description": "Up to five of this category's entries, sorted; never more than count."
}
},
"additionalProperties": false
}
WorktreeOperationResultobject · 10 properties
A successful result carries phase, registered and started; a refusal carries error, and retainedCheckout when a checkout outlived it.
{
"type": "object",
"required": [
"ok",
"operationId",
"kind"
],
"properties": {
"ok": {
"type": "boolean"
},
"operationId": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"create",
"register",
"start",
"fetch",
"refresh",
"delete",
"forget"
]
},
"phase": {
"$ref": "#/components/schemas/WorktreePhase"
},
"checkout": {
"$ref": "#/components/schemas/WorktreeCheckout"
},
"registered": {
"type": "boolean"
},
"started": {
"type": "boolean"
},
"startError": {
"$ref": "#/components/schemas/WorktreeError",
"description": "An explicitly requested start that failed. It does not fail the operation: the workspace remains configured and stopped."
},
"error": {
"$ref": "#/components/schemas/WorktreeError"
},
"retainedCheckout": {
"$ref": "#/components/schemas/WorktreeCheckout",
"description": "Present when Git succeeded and a later step did not. Retry acts on this checkout; a second one is never created."
}
},
"additionalProperties": false,
"description": "A successful result carries phase, registered and started; a refusal carries error, and retainedCheckout when a checkout outlived it."
}
WorktreeOwnershipstring
How this checkout relates to Uatu. `main` is the repository's main checkout. `uatu` means verified Uatu creation provenance, which alone may be deleted through Uatu. `external` is somebody else's tree, whether or not it is registered. `uncertain` means the recorded identity could not be confirmed; its content is retained and destructive actions are refused. Never inferred from a name, a path, or the presence of an agent's configuration directory.
{
"type": "string",
"enum": [
"main",
"uatu",
"external",
"uncertain"
],
"description": "How this checkout relates to Uatu. `main` is the repository's main checkout. `uatu` means verified Uatu creation provenance, which alone may be deleted through Uatu. `external` is somebody else's tree, whether or not it is registered. `uncertain` means the recorded identity could not be confirmed; its content is retained and destructive actions are refused. Never inferred from a name, a path, or the presence of an agent's configuration directory."
}
WorktreePhasestring
The last boundary the operation provably passed. Not a progress percentage: it is what restart recovery reconciles against actual Git state. Create phases run validating to complete; delete phases preflight to complete; unphased kinds report only complete.
{
"type": "string",
"enum": [
"validating",
"reserving",
"creating",
"verifying",
"registering",
"assigning",
"starting",
"preflight",
"fencing",
"stopping",
"rechecking",
"removing",
"unregistering",
"complete"
],
"description": "The last boundary the operation provably passed. Not a progress percentage: it is what restart recovery reconciles against actual Git state. Create phases run validating to complete; delete phases preflight to complete; unphased kinds report only complete."
}
WorktreeReferencestring
A registered workspace id, a canonical checkout id, or the exact branch of exactly one linked checkout in this repository family. A branch is resolved against the authoritative inventory and yields a canonical identity, which is what every safety check then runs on — so a stale name can never address a path's new occupant. A branch matching more than one checkout is refused as ambiguous.
{
"type": "string",
"minLength": 1,
"description": "A registered workspace id, a canonical checkout id, or the exact branch of exactly one linked checkout in this repository family. A branch is resolved against the authoritative inventory and yields a canonical identity, which is what every safety check then runs on — so a stale name can never address a path's new occupant. A branch matching more than one checkout is refused as ambiguous."
}
WorktreeRefsobject · 3 properties
{
"type": "object",
"required": [
"local",
"remote",
"fetchedAt"
],
"properties": {
"local": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"remote": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Remote-qualified, such as origin/release."
},
"fetchedAt": {
"type": [
"integer",
"null"
],
"description": "Unix epoch milliseconds of the last successful fetch in this Hub run, or null when the listing comes from repository state alone. A cached listing is never network-fresh."
}
},
"additionalProperties": false
}
WorktreeRefsResponseobject · 3 properties
ok: true carries refs alone; ok: false carries error, and usually refs — the cached listing, unchanged.
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"refs": {
"$ref": "#/components/schemas/WorktreeRefs",
"description": "Reported whether or not the fetch succeeded: absent only when a refusal is decided before any repository is read."
},
"error": {
"$ref": "#/components/schemas/WorktreeError"
}
},
"additionalProperties": false,
"description": "ok: true carries refs alone; ok: false carries error, and usually refs — the cached listing, unchanged."
}
WorktreeRetryActionstring
The one follow-up the originating flow offers. `none` means there is none; it is never a licence to force.
{
"type": "string",
"enum": [
"none",
"retry-registration",
"retry-start",
"retry-fetch",
"retry-delete",
"refresh",
"open-existing"
],
"description": "The one follow-up the originating flow offers. `none` means there is none; it is never a licence to force."
}