{ "openapi": "3.1.0", "info": { "title": "Reflex API", "version": "1.0.0" }, "servers": [ { "url": "/api" } ], "tags": [ { "name": "activity" }, { "name": "agent-associations" }, { "name": "agent-drafts" }, { "name": "agent-groups" }, { "name": "agent-labels" }, { "name": "agent-personas" }, { "name": "agents" }, { "name": "auth" }, { "name": "blueprints" }, { "name": "company" }, { "name": "config" }, { "name": "device" }, { "name": "enterprise-identity" }, { "name": "flags" }, { "name": "invites" }, { "name": "mcp" }, { "name": "me" }, { "name": "org-setup" }, { "name": "organizations" }, { "name": "permissions" }, { "name": "plugins" }, { "name": "profile" }, { "name": "resource-grants" }, { "name": "secrets" }, { "name": "service-accounts" }, { "name": "share-requests" }, { "name": "snapshots" }, { "name": "status" }, { "name": "teams" }, { "name": "uploads" }, { "name": "user" }, { "name": "users" } ], "paths": { "/activity/recent": { "get": { "operationId": "getRecentActivity", "summary": "List the most recent events across the caller's unarchived agents.", "tags": [ "activity" ], "x-route-scope": "active-org", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TaggedActivityEvent" } } }, "required": [ "items" ], "additionalProperties": false } } } } } } }, "/agent-associations": { "get": { "operationId": "listAgentAssociations", "summary": "List agent work-item associations in the active organization.", "tags": [ "agent-associations" ], "x-route-scope": "active-org", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "repoSlug", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agent-drafts": { "get": { "operationId": "listAgentDrafts", "summary": "List the caller's launch drafts in the active organization.", "tags": [ "agent-drafts" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } }, "post": { "operationId": "saveAgentDraft", "summary": "Create or update a launch draft.", "tags": [ "agent-drafts" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agd_[A-Za-z0-9]{22}$" }, "payload": { "type": "object", "properties": { "name": { "type": "string" }, "agentType": { "type": "string" }, "prompt": { "type": "string", "minLength": 1 }, "systemPrompt": { "type": "string" }, "personaId": { "type": "string", "maxLength": 64 }, "model": { "type": "string" }, "modelEndpointId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blueprintId": { "type": "string" }, "blueprintName": { "type": "string" }, "sandboxOptions": { "type": "object", "properties": { "blueprintName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blueprintId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshotId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resourceSize": { "anyOf": [ { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "X_LARGE", "XX_LARGE" ] }, { "type": "null" } ] }, "customSize": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "cpuCores": { "type": "number", "minimum": 0.5 }, "gbMemory": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "diskSizeGb": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "cpuCores", "gbMemory" ], "additionalProperties": false }, { "type": "null" } ] }, "dockerd": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "computerUse": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "artifactMirrors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "idleTimeMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "resumeOnHttp": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "mimeType", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "name", "mimeType", "data" ] } ] } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "pluginName": { "type": "string" }, "config": {} }, "required": [ "attachmentId", "pluginName" ] } }, "envVars": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "value": { "type": "string" }, "secretRef": { "type": "string" }, "isSecret": { "type": "boolean" } }, "required": [ "key" ] } }, "promptMode": { "type": "string", "enum": [ "implement", "plan", "review" ] }, "listenersEnabled": { "type": "boolean" }, "labelIds": { "maxItems": 10, "type": "array", "items": { "type": "string", "pattern": "^alb_[A-Za-z0-9]{22}$" } }, "groupId": { "type": "string", "pattern": "^agp_[A-Za-z0-9]{22}$" }, "authMethod": { "type": "string", "enum": [ "org-key", "claude-max", "codex-subscription" ] }, "providerSecretId": { "type": "string", "pattern": "^mps_[A-Za-z0-9]{22}$" }, "repoSlug": { "type": "string" }, "repoBranch": { "type": "string" }, "orgShare": { "type": "string", "enum": [ "none", "view", "edit" ] }, "selectedProviderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "manualBlueprintName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshotId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resourceSize": { "anyOf": [ { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "X_LARGE", "XX_LARGE" ] }, { "type": "null" } ] }, "dockerd": { "type": "boolean" }, "computerUse": { "type": "boolean" }, "idleTimeMinutes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "selectedPersonaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reasoningEffort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "initialPrompt": { "type": "string" }, "chatAttachments": { "type": "array", "items": {} }, "attachmentValues": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "pluginName": { "type": "string" }, "config": {} }, "required": [ "attachmentId", "pluginName" ] } } } }, "clientSeq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "payload", "clientSeq" ] } } } }, "responses": { "200": { "description": "Successful response" } } } }, "/agent-drafts/{id}": { "delete": { "operationId": "deleteAgentDraft", "summary": "Delete a launch draft.", "tags": [ "agent-drafts" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agd_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agent-groups": { "get": { "operationId": "listAgentGroups", "summary": "List the current user's agent groups in the active organization.", "tags": [ "agent-groups" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentGroupsResponse" } } } } } }, "post": { "operationId": "createAgentGroup", "summary": "Create an agent group, optionally with its first members.", "tags": [ "agent-groups" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentGroupRequest" } } } }, "responses": { "201": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGroupResponse" } } } } } } }, "/agent-groups/{groupId}": { "patch": { "operationId": "updateAgentGroup", "summary": "Rename an agent group.", "tags": [ "agent-groups" ], "x-route-scope": "active-org", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agp_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentGroupRequest" } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGroupResponse" } } } } } }, "delete": { "operationId": "deleteAgentGroup", "summary": "Delete an agent group and every membership in it.", "tags": [ "agent-groups" ], "x-route-scope": "active-org", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agp_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agent-groups/{groupId}/members": { "post": { "operationId": "addAgentGroupMembers", "summary": "File agents into a group, moving them out of any other group.", "tags": [ "agent-groups" ], "x-route-scope": "active-org", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agp_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGroupMembersRequest" } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGroupResponse" } } } } } }, "delete": { "operationId": "removeAgentGroupMembers", "summary": "Remove agents from a group.", "tags": [ "agent-groups" ], "x-route-scope": "active-org", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agp_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGroupMembersRequest" } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGroupResponse" } } } } } } }, "/agent-labels": { "get": { "operationId": "listAgentLabels", "summary": "List the agent labels in the active organization.", "tags": [ "agent-labels" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentLabelsResponse" } } } } } }, "post": { "operationId": "createAgentLabel", "summary": "Create an agent label, optionally applying it straight away.", "tags": [ "agent-labels" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentLabelRequest" } } } }, "responses": { "201": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLabelResponse" } } } } } } }, "/agent-labels/{labelId}": { "patch": { "operationId": "updateAgentLabel", "summary": "Rename an agent label or reword its description.", "tags": [ "agent-labels" ], "x-route-scope": "active-org", "parameters": [ { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^alb_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentLabelRequest" } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLabelResponse" } } } } } }, "delete": { "operationId": "deleteAgentLabel", "summary": "Delete an agent label and strip it from every agent.", "tags": [ "agent-labels" ], "x-route-scope": "active-org", "parameters": [ { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^alb_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agent-labels/{labelId}/members": { "post": { "operationId": "addAgentLabelMembers", "summary": "Apply a label to agents.", "tags": [ "agent-labels" ], "x-route-scope": "active-org", "parameters": [ { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^alb_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLabelMembersRequest" } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLabelResponse" } } } } } }, "delete": { "operationId": "removeAgentLabelMembers", "summary": "Remove a label from agents.", "tags": [ "agent-labels" ], "x-route-scope": "active-org", "parameters": [ { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^alb_[A-Za-z0-9]{22}$" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLabelMembersRequest" } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLabelResponse" } } } } } } }, "/agent-personas": { "get": { "operationId": "listAgentPersonas", "summary": "List the agent personas visible in the active organization.", "tags": [ "agent-personas" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPersona" } } } } } } } }, "/agent-personas/{id}": { "get": { "operationId": "getAgentPersona", "summary": "Get an agent persona by id.", "tags": [ "agent-personas" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persona id (`prs_*`)." } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPersona" } } } } } } }, "/agent-personas/{id}/launch": { "post": { "operationId": "launchAgentFromPersona", "summary": "Launch an agent from a persona.", "description": "Starts an agent from the persona's saved configuration with per-launch overrides layered on top. `agentType` runs the persona as a different agent — the model, endpoint route, and the persona's pinned provider key are then re-resolved for that type rather than carried over.", "tags": [ "agent-personas" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persona id (`prs_*`)." } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1 }, "promptStrategy": { "type": "string", "enum": [ "prepend-default", "replace" ] }, "name": { "type": "string" }, "agentType": { "type": "string", "minLength": 1 }, "model": { "type": "string" }, "modelEndpointId": { "type": "string", "minLength": 1 }, "systemPrompt": { "type": "string" }, "promptMode": { "type": "string", "enum": [ "implement", "plan", "review" ] }, "authMethod": { "type": "string", "enum": [ "org-key", "claude-max", "codex-subscription" ] }, "providerSecretId": { "type": "string", "pattern": "^mps_[A-Za-z0-9]{22}$" }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "mimeType", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "name", "mimeType", "data" ] } ] } }, "extraAttachments": { "type": "array", "items": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "pluginName": { "type": "string" }, "config": {} }, "required": [ "attachmentId", "pluginName" ] } }, "extraEnvVars": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "value": { "type": "string" }, "secretRef": { "type": "string" }, "isSecret": { "type": "boolean" } }, "required": [ "key" ], "additionalProperties": false } }, "repoSlug": { "type": "string" }, "repoBranch": { "type": "string" }, "extraLabelIds": { "type": "array", "items": { "type": "string" } }, "groupId": { "type": "string" }, "blueprintName": { "type": "string" }, "sandboxOptions": { "type": "object", "properties": { "blueprintName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blueprintId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshotId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resourceSize": { "anyOf": [ { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "X_LARGE", "XX_LARGE" ] }, { "type": "null" } ] }, "customSize": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "cpuCores": { "type": "number", "minimum": 0.5 }, "gbMemory": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "diskSizeGb": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "cpuCores", "gbMemory" ], "additionalProperties": false }, { "type": "null" } ] }, "dockerd": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "computerUse": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "artifactMirrors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "idleTimeMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "resumeOnHttp": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "prompt" ] } } } }, "responses": { "201": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/agents": { "get": { "operationId": "listAgents", "summary": "List the agents in the active organization.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "archived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "pinned", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "mark", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "const": "any" }, { "type": "string", "enum": [ "blocked", "in_review", "completed" ] } ] } }, { "name": "groupId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "labelId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "agents", "nextCursor" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createAgent", "summary": "Create and launch a new agent run.", "description": "Returns as soon as the run is created; the devbox provisions in the background. Watch the agent status or event stream for progress.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "agentType": { "type": "string" }, "prompt": { "type": "string", "minLength": 1 }, "systemPrompt": { "type": "string" }, "personaId": { "type": "string", "maxLength": 64 }, "model": { "type": "string" }, "modelEndpointId": { "type": "string", "minLength": 1 }, "blueprintId": { "type": "string" }, "blueprintName": { "type": "string" }, "sandboxOptions": { "type": "object", "properties": { "blueprintName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blueprintId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshotId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resourceSize": { "anyOf": [ { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "X_LARGE", "XX_LARGE" ] }, { "type": "null" } ] }, "customSize": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "cpuCores": { "type": "number", "minimum": 0.5 }, "gbMemory": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "diskSizeGb": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "cpuCores", "gbMemory" ], "additionalProperties": false }, { "type": "null" } ] }, "dockerd": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "computerUse": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "artifactMirrors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "idleTimeMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "resumeOnHttp": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "mimeType", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "name", "mimeType", "data" ] } ] } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "pluginName": { "type": "string" }, "config": {} }, "required": [ "attachmentId", "pluginName" ] } }, "envVars": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "value": { "type": "string" }, "secretRef": { "type": "string" }, "isSecret": { "type": "boolean" } }, "required": [ "key" ], "additionalProperties": false } }, "promptMode": { "type": "string", "enum": [ "implement", "plan", "review" ] }, "listenersEnabled": { "type": "boolean" }, "labelIds": { "maxItems": 10, "type": "array", "items": { "type": "string", "pattern": "^alb_[A-Za-z0-9]{22}$" } }, "groupId": { "type": "string", "pattern": "^agp_[A-Za-z0-9]{22}$" }, "authMethod": { "type": "string", "enum": [ "org-key", "claude-max", "codex-subscription" ] }, "providerSecretId": { "type": "string", "pattern": "^mps_[A-Za-z0-9]{22}$" }, "repoSlug": { "type": "string" }, "repoBranch": { "type": "string" }, "orgShare": { "type": "string", "enum": [ "none", "view", "edit" ] } }, "required": [ "agentType", "prompt" ] } } } }, "responses": { "201": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentResponse" } } } } } } }, "/agents/{id}": { "get": { "operationId": "getAgent", "summary": "Get a single agent by id.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } }, "patch": { "operationId": "updateAgent", "summary": "Update an agent's name or pinned state.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "pinned": { "type": "boolean" }, "listenersEnabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } }, "delete": { "operationId": "killAgent", "summary": "Delete the agent: force stop it, shut down its devbox, and hide the run.", "description": "Soft-deletes the run so normal reads no longer return it while retaining its durable history. Use `POST /agents/:id/stop` to force stop an agent while keeping it visible.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/agents/{id}/archive": { "post": { "operationId": "archiveAgent", "summary": "Archive the agent run.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/agents/{id}/capability-requests/{requestId}/decision": { "post": { "operationId": "decideAgentCapabilityRequest", "summary": "Answer an agent's capability request (allow once, for this agent, always, deny, never).", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCapabilityDecisionRequest" } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCapabilityDecisionResponse" } } } } } } }, "/agents/{id}/commands/{commandId}": { "get": { "operationId": "getAgentCommandStatus", "summary": "Read the delivery status of a command sent to the agent.", "description": "Returns the lifecycle status of a mailbox command (`pending`, `claimed`, `sent`, or `failed` with a failure code). Pass `wait` (ms, capped server-side) to hold the request open until the command reaches `sent` or `failed`; at the bound the current status is returned.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commandId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "wait", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 25000 } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommandStatusResponse" } } } } } } }, "/agents/{id}/complete": { "post": { "operationId": "completeAgent", "summary": "Mark the agent's run as completed without shutting down its devbox.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agents/{id}/control-response": { "post": { "operationId": "sendAgentControlResponse", "summary": "Answer a pending control request from the agent.", "description": "Returns { ok: true } once the answer reaches the agent, or 409 (control_response_no_pending_request) when no request is parked. With mailbox command delivery, an answer whose outcome is still unknown at the bounded wait returns 202 with { status: \"pending\", commandId }.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": {} }, "required": [ "payload" ] } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "202": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommandPendingResponse" } } } } } } }, "/agents/{id}/devbox-logs": { "get": { "operationId": "getAgentDevboxLogs", "summary": "Fetch the platform logs for the agent's devbox.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agents/{id}/devbox-status": { "get": { "operationId": "getAgentDevboxStatus", "summary": "Get the live status, size, and architecture of the agent's devbox.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agents/{id}/interrupt": { "post": { "operationId": "interruptAgent", "summary": "Interrupt the agent's current turn.", "description": "Returns the interrupted agent. With mailbox command delivery, an interrupt whose outcome is still unknown at the bounded wait returns 202 with { status: \"pending\", commandId }.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "202": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommandPendingResponse" } } } } } } }, "/agents/{id}/listeners": { "get": { "operationId": "listAgentListeners", "summary": "List the listeners (timers, ref signals, watches) an agent has armed.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentListenersResponse" } } } } } } }, "/agents/{id}/listeners/{listenerId}/cancel": { "post": { "operationId": "cancelAgentListener", "summary": "Cancel an armed or pending listener.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listenerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListenerResponse" } } } } } } }, "/agents/{id}/listeners/{listenerId}/renew": { "post": { "operationId": "renewAgentListener", "summary": "Extend an armed listener's lease.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listenerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewAgentListenerRequest" } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListenerResponse" } } } } } } }, "/agents/{id}/mark": { "post": { "operationId": "setAgentMark", "summary": "Set or clear the agent's triage mark.", "description": "Marks a run blocked / in review / completed for triage. A null mark clears it. The server also clears the mark when the run starts its next turn or is archived.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mark": { "anyOf": [ { "type": "string", "enum": [ "blocked", "in_review", "completed" ] }, { "type": "null" } ] } }, "required": [ "mark" ] } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/agents/{id}/mcp-servers": { "post": { "operationId": "attachAgentMcpServers", "summary": "Attach MCP servers to a running agent's devbox.", "description": "Mints live MCP hub tokens for the devbox and registers each server in the agent's native config immediately, then records the ids on the agent's `mcp-servers` attachment. The devbox must be running (409 `agent_devbox_not_running` otherwise); a registration the box reports as failed is a 502 `mcp_registration_failed` with nothing persisted. `activation` reports whether the agent process that is running right now loaded the servers (`active`, usable on its next turn) or whether they wait on disk for its next start (`deferred`) — both are successful attaches. Already-attached ids are skipped, unknown or disabled ids are dropped (compare the returned agent's attachments to detect a partial drop), and the request 404s `mcp_config_not_found` only when no id resolves. Local (stdio) servers are rejected because their subprocess secrets only exist as create-time devbox params.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mcpServerIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "mcpServerIds" ] } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/Agent" }, "activation": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "active" }, "serverNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "state", "serverNames" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "deferred" }, "reason": { "type": "string", "enum": [ "restart-required", "agent-unreachable" ] } }, "required": [ "state", "reason" ], "additionalProperties": false } ] } }, "required": [ "agent", "activation" ], "additionalProperties": false } } } } } } }, "/agents/{id}/message": { "post": { "operationId": "sendAgentMessage", "summary": "Send a message to the agent's chat.", "description": "Returns 201 with the acknowledging event once the message reaches the agent. With mailbox command delivery, a send whose outcome is still unknown at the bounded wait returns 202 with { status: \"pending\", commandId }: the message is accepted and durable, delivery just has not been confirmed yet.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "mimeType", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "name", "mimeType", "data" ] } ] } } } } } } }, "responses": { "201": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AxonEvent" } } } }, "202": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommandPendingResponse" } } } } } } }, "/agents/{id}/pin": { "post": { "operationId": "pinAgent", "summary": "Pin the agent.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agents/{id}/queue": { "get": { "operationId": "getAgentQueue", "summary": "List the messages queued for the agent.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "text": { "type": "string" }, "attachments": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "image", "link" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "storageObjectId": { "type": "string" }, "data": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false } }, { "type": "null" } ] }, "position": { "type": "number" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number" } }, "required": [ "id", "agentId", "text", "attachments", "position", "userId", "createdAt" ], "additionalProperties": false } } } } } } }, "post": { "operationId": "enqueueAgentMessage", "summary": "Add a message to the agent's queue.", "description": "Queued messages are delivered one per turn whenever the agent next accepts input, even when no client is connected.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "image", "link" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "storageObjectId": { "type": "string" }, "data": { "type": "string" } }, "required": [ "id", "type", "name" ] } } }, "required": [ "text" ] } } } }, "responses": { "201": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "text": { "type": "string" }, "attachments": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "image", "link" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "storageObjectId": { "type": "string" }, "data": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false } }, { "type": "null" } ] }, "position": { "type": "number" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number" } }, "required": [ "id", "agentId", "text", "attachments", "position", "userId", "createdAt" ], "additionalProperties": false } } } } } } }, "/agents/{id}/queue/{msgId}": { "patch": { "operationId": "updateQueuedAgentMessage", "summary": "Edit a queued message.", "description": "Edits the text and, when `attachments` is present, replaces the attachment list with the one sent.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "image", "link" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "storageObjectId": { "type": "string" }, "data": { "type": "string" } }, "required": [ "id", "type", "name" ] } } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "text": { "type": "string" }, "attachments": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "image", "link" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "storageObjectId": { "type": "string" }, "data": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false } }, { "type": "null" } ] }, "position": { "type": "number" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number" } }, "required": [ "id", "agentId", "text", "attachments", "position", "userId", "createdAt" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "removeQueuedAgentMessage", "summary": "Remove a message from the agent's queue.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "msgId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/agents/{id}/queue/order": { "put": { "operationId": "reorderAgentQueue", "summary": "Reorder the agent's queued messages.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderedIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "orderedIds" ] } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "text": { "type": "string" }, "attachments": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "image", "link" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "storageObjectId": { "type": "string" }, "data": { "type": "string" } }, "required": [ "id", "type", "name" ], "additionalProperties": false } }, { "type": "null" } ] }, "position": { "type": "number" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number" } }, "required": [ "id", "agentId", "text", "attachments", "position", "userId", "createdAt" ], "additionalProperties": false } } } } } } } }, "/agents/{id}/refs": { "get": { "operationId": "listAgentRefs", "summary": "List the refs (pull requests, issues) an agent holds, with each kind's signals and actions.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentRefsResponse" } } } } } } }, "/agents/{id}/resume": { "post": { "operationId": "resumeAgent", "summary": "Resume the agent's devbox if it is suspended.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agents/{id}/runtime-settings": { "post": { "operationId": "updateAgentRuntimeSettings", "summary": "Retarget a running agent's sticky runtime settings.", "description": "Switches the model a running agent uses from its next response on, the only runtime setting today. The new model is validated exactly as a launch with it would be (present in the agent type's catalog, enabled by admin policy, and reachable with the credentials the requesting user can see, on the run's own route). The switch is posted to the agent's box as the harness's own instruction, which the box keeps across suspends (a sleeping box wakes to take it), and then recorded on the agent, so it is what cost attribution records from here on. Returns the updated agent record. 409 `agent_not_switchable` for a run that is still starting or can no longer take a turn (stopping/stopped/error/terminated), 400 `model_switch_unsupported` for a harness that takes its model only at startup, 400 `agent_type_has_no_model_catalog` for a single-model agent type, 400 `model_not_in_catalog` for a model outside the catalog, 400 `model_not_reachable_for_run` for a model on the other route than the run's (direct or AI Gateway), 403 `model_not_allowed` when admin policy disables the model or its provider, and 503 `model_switch_not_delivered` when the instruction could not be posted, in which case nothing changed.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/agents/{id}/services/{serviceId}/logs": { "get": { "operationId": "getAgentServiceLogs", "summary": "Fetch the log for one service on the agent's devbox.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "serviceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agents/{id}/services/status": { "get": { "operationId": "getAgentServiceStatuses", "summary": "Get the live status of every service on the agent's devbox.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentServiceStatusesResponse" } } } } } } }, "/agents/{id}/session-index": { "get": { "operationId": "getAgentSessionIndex", "summary": "The agent's session index: every prompt and turn boundary, for nav and paging.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionIndexResponse" } } } } } } }, "/agents/{id}/snapshots": { "post": { "operationId": "createAgentSnapshot", "summary": "Capture a reusable snapshot of the agent's devbox disk.", "description": "This ends the run: per-run state is stripped from the disk, the capture starts asynchronously, and the devbox shuts down once it completes. Poll the snapshot's status route until the capture finishes.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "commitMessage": { "type": "string", "maxLength": 1000 } }, "required": [ "name" ] } } } }, "responses": { "202": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snapshot" } } } } } } }, "/agents/{id}/stop": { "post": { "operationId": "stopAgent", "summary": "Stop the agent's run and shut down its devbox.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/agents/{id}/stream": { "get": { "operationId": "getAgentStream", "summary": "Get the agent's event history: a turn-aligned window for indexed agents, the full array for legacy ones.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "paged", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, { "name": "fromSeq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "toSeq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AxonEvent" } }, { "$ref": "#/components/schemas/PagedAgentStreamResponse" } ] } } } } } } }, "/agents/{id}/subscription": { "put": { "operationId": "switchAgentSubscription", "summary": "Switch the model-provider subscription a running agent uses.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerSecretId": { "type": "string", "minLength": 1 } }, "required": [ "providerSecretId" ] } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/agents/{id}/unarchive": { "post": { "operationId": "unarchiveAgent", "summary": "Unarchive the agent run.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } } } }, "/agents/{id}/unpin": { "post": { "operationId": "unpinAgent", "summary": "Unpin the agent.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/agents/{id}/unread": { "post": { "operationId": "markAgentUnread", "summary": "Mark the agent unread for the current user.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentView" } } } } } } }, "/agents/{id}/view": { "post": { "operationId": "recordAgentView", "summary": "Record that the current user has viewed the agent.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentView" } } } } } } }, "/agents/archive-all": { "post": { "operationId": "archiveAllAgents", "summary": "Archive every matching agent run in the active organization.", "description": "Still running agents are stopped first, which shuts down their devboxes. The sweep can be narrowed by owner and created date range.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "createdAtFrom": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAtTo": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "userId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "archived" ], "additionalProperties": false } } } } } } }, "/agents/views": { "get": { "operationId": "listAgentViews", "summary": "List the current user's per-agent last-viewed timestamps.", "tags": [ "agents" ], "x-route-scope": "active-org", "parameters": [ { "name": "x-organization-id", "in": "header", "required": true, "description": "Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentViewsResponse" } } } } } } }, "/auth/dev-login": { "post": { "operationId": "devLogin", "summary": "Sign in with development credentials", "tags": [ "auth" ], "x-route-scope": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "login": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "providerUserId": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "token", "user" ], "additionalProperties": false } } } } } } }, "/auth/device/acknowledge": { "post": { "operationId": "acknowledgeDeviceAuthToken", "summary": "Acknowledge that a device credential was saved.", "description": "Idempotently erases the encrypted handoff after the client has durably stored the returned API key.", "tags": [ "auth" ], "x-route-scope": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceCode" ] } } } }, "responses": { "204": { "description": "No content" } } } }, "/auth/device/start": { "post": { "operationId": "startDeviceAuth", "summary": "Start a device sign-in and return the device and user codes.", "tags": [ "auth" ], "x-route-scope": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 1, "maxLength": 255 }, "clientName": { "type": "string", "minLength": 1, "maxLength": 80 }, "supportsAcknowledgement": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string" }, "userCode": { "type": "string" }, "verificationUri": { "type": "string" }, "verificationUriComplete": { "type": "string" }, "interval": { "type": "number" }, "expiresIn": { "type": "number" }, "acknowledgementRequired": { "type": "boolean" } }, "required": [ "deviceCode", "userCode", "verificationUri", "verificationUriComplete", "interval", "expiresIn" ], "additionalProperties": false } } } } } } }, "/auth/device/token": { "post": { "operationId": "pollDeviceAuthToken", "summary": "Poll a device sign-in for its result.", "description": "Responds 202 while approval is pending. On approval the minted API key remains replayable until the client acknowledges durable storage.", "tags": [ "auth" ], "x-route-scope": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceCode" ] } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "authorization_pending" } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "approved" }, "apiKey": { "type": "string" }, "organizationId": { "type": "string" } }, "required": [ "status", "apiKey", "organizationId" ], "additionalProperties": false } ] } } } } } } }, "/auth/identities": { "get": { "operationId": "listAuthIdentities", "summary": "List linked authentication identities", "tags": [ "auth" ], "x-route-scope": "user", "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "providerUserId": { "type": "string" }, "providerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerified": { "type": "boolean" }, "createdAt": { "type": "number" }, "lastUsedAt": { "type": "number" } }, "required": [ "id", "provider", "providerUserId", "providerEmail", "emailVerified", "createdAt", "lastUsedAt" ], "additionalProperties": false } } }, "required": [ "identities" ], "additionalProperties": false } } } } } } }, "/auth/identities/{id}": { "delete": { "operationId": "unlinkAuthIdentity", "summary": "Unlink an authentication identity", "tags": [ "auth" ], "x-route-scope": "user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/auth/logout": { "post": { "operationId": "logout", "summary": "Sign out the current session", "tags": [ "auth" ], "x-route-scope": "public", "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/auth/me": { "get": { "operationId": "getAuthStatus", "summary": "Get current authentication status", "tags": [ "auth" ], "x-route-scope": "public", "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "authEnabled": { "type": "boolean" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] }, "providers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string" }, "requiresStoredToken": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "oauth", "password" ] }, "hidden": { "type": "boolean" } }, "required": [ "label" ], "additionalProperties": false } }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "memberId": { "type": "string" }, "organization": { "$ref": "#/components/schemas/Organization" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope": { "type": "string", "enum": [ "org", "team" ] }, "isBuiltin": { "type": "boolean" }, "permissions": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" } } }, "required": [ "id", "slug", "name", "description", "scope", "isBuiltin", "permissions" ], "additionalProperties": false } }, "permissions": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultRoleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "permissions": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" } } }, "required": [ "id", "organizationId", "slug", "name", "description", "createdAt", "permissions" ], "additionalProperties": false } } }, "required": [ "memberId", "organization", "roles", "permissions", "teams" ], "additionalProperties": false } }, "activeOrganizationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orgsNeedingBootstrap": { "type": "array", "items": { "type": "string" } }, "isSuperAdmin": { "type": "boolean" }, "isAppAdmin": { "type": "boolean" }, "setupRequired": { "type": "boolean" }, "isProduction": { "type": "boolean" }, "devLogin": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "string" } }, "autoLoginEmail": { "type": "string" } }, "required": [ "users" ], "additionalProperties": false }, "allowSelfServeOrgCreation": { "type": "boolean" }, "ssoRequirements": { "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "organizationSlug": { "type": "string" }, "organizationName": { "type": "string" }, "satisfied": { "type": "boolean" } }, "required": [ "organizationId", "organizationSlug", "organizationName", "satisfied" ], "additionalProperties": false } } }, "required": [ "authenticated", "authEnabled", "user" ], "additionalProperties": false } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/settings": { "get": { "operationId": "getAuthSettings", "summary": "Get authentication settings", "tags": [ "auth" ], "x-route-scope": "platform-admin", "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowedEmailDomains": { "type": "array", "items": {} }, "allowedEmails": { "default": [], "type": "array", "items": {} }, "mode": { "type": "string", "enum": [ "off", "allow", "deny" ] }, "allowSelfServeOrgCreation": { "default": true, "type": "boolean" }, "updatedAt": { "type": "number" }, "updatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "allowedEmailDomains", "allowedEmails", "mode", "allowSelfServeOrgCreation", "updatedAt", "updatedBy" ], "additionalProperties": false } } } } } }, "put": { "operationId": "updateAuthSettings", "summary": "Update authentication settings", "tags": [ "auth" ], "x-route-scope": "platform-admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowedEmailDomains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?!-)[A-Za-z0-9-]{1,63}(?