x-xgen-IPA-exception: xgen-IPA-128: 'IPA-128-must-not-expect-preview-stability: Preview describes release maturity; this dated contract deliberately guarantees compatibility and requires a new date for breaking changes.' components: responses: ApiVersionNotAcceptable: content: application/json: examples: operationUnavailable: value: detail: This operation is not available in API version 2026-09-20-preview. error: 406 errorCode: OPERATION_NOT_IN_API_VERSION parameters: - Accept reason: Not Acceptable streamRefused: value: detail: This operation supports text/event-stream, which the Accept header excludes. Remove unsupported media-type parameters or accept this type with a positive q value. error: 406 errorCode: UNACCEPTABLE_MEDIA_TYPE parameters: - Accept reason: Not Acceptable unsupportedVersion: value: detail: 'The requested API version is not supported. Supported versions: 2026-09-20-preview.' error: 406 errorCode: UNSUPPORTED_API_VERSION parameters: - Accept reason: Not Acceptable schema: $ref: '#/components/schemas/ApiError' application/vnd.agent-engine-2026-09-20-preview+json: examples: operationUnavailable: value: detail: This operation is not available in API version 2026-09-20-preview. error: 406 errorCode: OPERATION_NOT_IN_API_VERSION parameters: - Accept reason: Not Acceptable schema: $ref: '#/components/schemas/ApiError' description: Unsupported or malformed API version, an operation unavailable in the selected published contract, or an unacceptable representation (including unsupported media-type parameters or excluded SSE). Existing authentication, authorization, and rate-limit failures take precedence. LegacyError400: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Bad Request x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError401: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Unauthorized x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError403: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Forbidden x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError404: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Not Found x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError409: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Conflict x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError410: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Gone x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError412: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Precondition Failed x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError413: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Request Entity Too Large x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError429: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError500: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Internal Server Error x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError501: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Not Implemented x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError502: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Bad Gateway x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError503: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' LegacyError504: content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Gateway Timeout x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' schemas: ApiError: properties: badRequestDetail: description: Optional validation details defined by the standard error schema; API negotiation errors do not emit this field. properties: fields: description: Fields with validation failures. items: description: A field and its validation failure. properties: description: description: Human-readable validation failure. readOnly: true type: string field: description: Name or path of the invalid request field. readOnly: true type: string required: - description - field type: object readOnly: true type: array readOnly: true type: object detail: description: Human-readable error details. readOnly: true type: string error: description: HTTP status code. example: 406 readOnly: true type: integer errorCode: description: Machine-readable error code. example: UNSUPPORTED_API_VERSION readOnly: true type: string parameters: description: Request parameter names associated with the error; omitted when none apply. items: type: string readOnly: true type: array reason: description: HTTP status reason phrase. example: Not Acceptable readOnly: true type: string required: - error - errorCode - detail - reason type: object atlasegress.ClusterEgressCluster: properties: hosts: items: type: string type: array uniqueItems: false name: type: string publicIpv4Addresses: items: type: string type: array uniqueItems: false type: type: string uniqueId: type: string type: object atlasegress.SnapshotSummary: properties: cluster_count: description: |- Number of clusters in the last successful stored snapshot. Zero means Atlas returned none (often paused or empty). Customer atlas-link responses include this count and omit cluster hosts/IPs. type: integer clusters: items: $ref: '#/components/schemas/atlasegress.ClusterEgressCluster' type: array uniqueItems: false clusters_differ: type: boolean last_success_at: type: string last_sync_at: type: string live_clusters: items: $ref: '#/components/schemas/atlasegress.ClusterEgressCluster' type: array uniqueItems: false live_fetch_error: type: string sync_error: type: string sync_status: type: string type: object auditevent.Action: enum: - agent.deploy - agent.rollback - agent.promote - secret.set - secret.delete - workspace_logs.view - data_viewer_access.grant - data_viewer_access.revoke - support_access.grant - support_access.revoke - service_account.create - service_account.rotate_secret - service_account.revoke - service_account.reactivate - service_account.replace_roles - service_account.token_mint - service_account.token_use - service_account.authz_denied - service_account.ip_access_list.update - oe_profile.capture - oe_profile.download - workspace.delete - project.delete - workspace.deletion_delivered - workspace.restoration_delivered - app_secrets.reclaim - project_secrets.reclaim - api_key_secrets.reclaim - ecr_repository.delete - namespace.delete - atlas_service_account.retire - workspace_records.purge - project_records.purge - project.reclaim - project_platform_target.select - project_staged_rollout.start - project_staged_rollout.resume - app_platform_update.accept - project_operation.force_cancel - project_operation.request_cancel - app_operation.request_cancel - project_operation.resume - runtime_config.set - runtime_config.clear - trace.view - application_secret.migrate - egress_allow_all.migrate - egress.save - guardrail.create - guardrail.update - guardrail.delete - policy.create - policy.update - policy.delete - credential_provider.create - credential_provider.update - credential_provider.delete type: string x-enum-varnames: - ActionAgentDeploy - ActionAgentRollback - ActionAgentPromote - ActionSecretSet - ActionSecretDelete - ActionWorkspaceLogsView - ActionDataViewerAccessGrant - ActionDataViewerAccessRevoke - ActionSupportAccessGrant - ActionSupportAccessRevoke - ActionServiceAccountCreate - ActionServiceAccountRotateSecret - ActionServiceAccountRevoke - ActionServiceAccountReactivate - ActionServiceAccountReplaceRoles - ActionServiceAccountTokenMint - ActionServiceAccountTokenUse - ActionServiceAccountAuthzDenied - ActionServiceAccountIPAccessListUpdate - ActionOEProfileCapture - ActionOEProfileDownload - ActionWorkspaceDelete - ActionProjectDelete - ActionWorkspaceDeletionDelivered - ActionWorkspaceRestorationDelivered - ActionAppSecretsReclaim - ActionProjectSecretsReclaim - ActionAPIKeySecretsReclaim - ActionECRRepositoryDelete - ActionNamespaceDelete - ActionAtlasServiceAccountRetire - ActionWorkspaceRecordsPurge - ActionProjectRecordsPurge - ActionProjectReclaim - ActionProjectPlatformTargetSelect - ActionProjectStagedRolloutStart - ActionProjectStagedRolloutResume - ActionAppPlatformUpdateAccept - ActionProjectOperationForceCancel - ActionProjectOperationRequestCancel - ActionAppOperationRequestCancel - ActionProjectOperationResume - ActionRuntimeConfigSet - ActionRuntimeConfigClear - ActionTraceView - ActionApplicationSecretMigrate - ActionEgressAllowAllMigrate - ActionEgressSave - ActionGuardrailCreate - ActionGuardrailUpdate - ActionGuardrailDelete - ActionPolicyCreate - ActionPolicyUpdate - ActionPolicyDelete - ActionCredentialProviderCreate - ActionCredentialProviderUpdate - ActionCredentialProviderDelete auditevent.Actor-bson_ObjectID: properties: client_id: description: |- ClientID is the global service account client id when Type is ActorTypeServiceAccount. type: string email: type: string roles: description: Roles are the actor's role(s) recorded at action time, if any. Optional. items: type: string type: array uniqueItems: false type: description: |- Type discriminates the actor kind. Empty or ActorTypeUser means a human identified by UserID/Email. ActorTypeServiceAccount means a GSA identified by ClientID (UserID/Email may be empty). type: string user_id: type: string type: object auditevent.Category: enum: - access - mutation type: string x-enum-varnames: - CategoryAccess - CategoryMutation auditevent.Outcome: enum: - success - failure type: string x-enum-varnames: - OutcomeSuccess - OutcomeFailure auditevent.Scope-bson_ObjectID: properties: org_id: type: string project_id: type: string workspace_id: type: string type: object auditevent.Target: properties: id: type: string name: type: string type: description: Type is the resource kind (e.g. "workspace_logs", "deployment", "secret"). type: string type: object main.APIRoleAssignment: properties: org_id: type: string project_id: type: string role: type: string type: object main.AdminComponentStatus: properties: available: type: boolean failure_message: type: string failure_reason: type: string name: type: string ready_replicas: type: integer replicas: description: |- Replicas is the desired pod count. Zero means the platform has not reported one; consumers must not treat zero as scale-to-zero. type: integer sandbox: description: |- Sandbox is the canonical sandbox name for known component values (agent, tool). Omitted for unknown upstream names. type: string type: type: string type: object main.AdminCondition: properties: last_transition_time: type: string message: type: string reason: type: string status: type: string type: type: string type: object main.AdminCreateDeploymentRequest: properties: build_id: type: string type: object main.AdminCreateDeploymentResponse: properties: deployment_id: type: string status: type: string type: object main.AdminCreatePromotionRequest: properties: confirmed: description: |- Confirmed must be true: promotion copies an artifact into another project, so the API requires the explicit confirmation the CLI/UI collect from the user. type: boolean force: description: |- Force bypasses ECP's deploy-proof gate; requires the target project owner role. type: boolean source_build_id: description: |- SourceBuildID identifies the succeeded build to promote. It may live in any project of the caller's org. type: string required: - confirmed - source_build_id type: object main.AdminDeploymentResponse: properties: aer_http_endpoint: description: AERHTTPEndpoint is the legacy name of the agent sandbox HTTP endpoint. type: string agent_http_endpoint: description: AgentHTTPEndpoint is the agent sandbox HTTP endpoint. Same value as aer_http_endpoint. type: string agent_stack_name: type: string app_id: type: string branch: type: string build_id: type: string commit_sha: type: string completed_at: type: string component_images: $ref: '#/components/schemas/main.ComponentImages' components: description: Per-component health — forwarded as-is from ECP for the detail view. items: $ref: '#/components/schemas/main.AdminComponentStatus' type: array uniqueItems: false conditions: items: $ref: '#/components/schemas/main.AdminCondition' type: array uniqueItems: false created_at: description: Timestamps. type: string deployment_id: description: Identity & core status (always present). type: string duration_ms: type: integer error_message: description: Failure context — surfaced so admin UIs can triage without going to Splunk first. type: string executor_type: type: string first_deploy: description: |- FirstDeploy is true for every attempt until (and including) the workspace's first successful deploy. Omitted when unknown. type: boolean health: $ref: '#/components/schemas/main.AdminHealthResponse' image_uri: description: Image / source. type: string language: description: |- Language is the agent runtime language ("python" | "typescript"), forwarded from ECP. Omitted when unset (older builds default to python downstream). type: string last_event_seq: type: integer memory_enabled: description: MemoryEnabled is the deployment's effective runtime memory setting. Omitted when unavailable. type: boolean missing_secrets: items: type: string type: array uniqueItems: false operator_namespace: type: string org_id: type: string post_deploy_error_message: type: string previous_image_uri: type: string project_deleted: description: |- True when the deployment's owning project has been soft-deleted. Always emitted so consumers can branch on the field, not its absence. type: boolean project_id: type: string release_number: description: |- ReleaseNumber is the per-workspace monotonic version identifier (drives the v{N} label in the UI). 0/omitted for legacy records before the backfill migration. type: integer requested_images: description: |- RequestedImages is digest-pinned deploy intent. Omitted for legacy deployments created before image digest tracking was enabled; [] means the writer ran but resolved nothing. items: $ref: '#/components/schemas/main.RequestedImage' type: array uniqueItems: false requested_target_id: description: |- RequestedTargetID is internal Fleet provenance and is intentionally not surfaced by Gateway responses. It remains empty for compatibility. type: string rollback_error: type: string rollback_from_id: description: set when this deployment was rolled back *from* type: string rollback_of: description: Rollback linkage. type: string shipped_in_release: description: |- ShippedInRelease is the release that shipped this deployment. Omitted when it belongs to none. Forwarded from ECP; derived at read time. type: string source_build_id: type: string source_project_id: type: string source_promotion_id: type: string source_workspace_id: type: string started_at: type: string status: type: string target_namespace: description: Kubernetes placement. type: string trigger: type: string updated_at: type: string version: description: |- Version is the developer-declared agent version forwarded from ECP. Omitted for unversioned records. type: string type: object main.AdminDeploymentVersionGroup: properties: deployment_count: type: integer release_build_ids: items: type: string type: array uniqueItems: false release_deployment_id: description: |- ReleaseDeploymentID is empty when the release was built but never deployed; the UI then parents the group on the build_only row for one of ReleaseBuildIDs. type: string release_version: type: string released_at: description: |- ReleasedAt is when this release was created (its cut). Membership of each deployment is shipped_in_release on the list row, not this timestamp. format: date-time type: string type: object main.AdminHealthComponentResponse: properties: name: type: string ready: type: boolean ready_replicas: type: integer sandbox: description: |- Sandbox is the canonical sandbox name for known component values (agent, tool). Omitted for unknown upstream names. type: string type: object main.AdminHealthResponse: description: Extended fields. properties: available: type: boolean checked_at: type: string components: items: $ref: '#/components/schemas/main.AdminHealthComponentResponse' type: array uniqueItems: false type: object main.AdminListBuildsResponse: properties: builds: type: object next_cursor: type: string total: type: integer type: object main.AdminListDeploymentVersionsResponse: properties: versions: items: $ref: '#/components/schemas/main.AdminDeploymentVersionGroup' type: array uniqueItems: false type: object main.AdminListDeploymentsResponse: properties: deployments: items: $ref: '#/components/schemas/main.AdminDeploymentResponse' type: array uniqueItems: false limit: description: |- Set by the offset-paginated platform-wide admin list. Per-workspace endpoints leave these zero-valued and they are omitted on the wire. type: integer next_cursor: description: |- Set by the cursor-paginated per-workspace admin list. Platform-wide endpoints leave it nil. type: string offset: type: integer total: type: integer type: object main.AdminPlatformProjectAtlasLinkResponse: properties: atlas_project: $ref: '#/components/schemas/main.AtlasProjectLinkResponse' egress_sync: $ref: '#/components/schemas/atlasegress.SnapshotSummary' name: type: string org_id: type: string project_id: type: string type: object main.AdminPromotionListResponse: properties: promotions: items: $ref: '#/components/schemas/main.AdminPromotionResponse' type: array uniqueItems: false total: type: integer type: object main.AdminPromotionResponse: properties: created_at: type: string failure_reason: type: string finished_at: type: string force: type: boolean initiated_by: type: string org_id: type: string promotion_id: type: string source_build_id: type: string status: description: |- Status is one of pending, copying, ready, or failed. Ready and failed are terminal outcomes; pending and copying are the observable non-terminal polling states. enum: - pending - copying - ready - failed type: string target_build_id: type: string target_project_id: type: string target_workspace_id: type: string type: object main.AdminPutSecretRequest: properties: description: type: string value: type: string value_unchanged: description: |- ValueUnchanged must be explicitly set by a caller editing only the description of an existing secret; it is what allows Value to be empty. Without it, an empty Value is always rejected - a caller that sends "" by mistake (e.g. a templating bug or unset env var) gets a clear 400 instead of silently leaving the old value in place. type: boolean type: object main.AdminRollbackRequest: properties: target_deployment_id: type: string required: - target_deployment_id type: object main.AdminSecretResponse: properties: created_at: type: string description: type: string name: type: string updated_at: type: string version: type: integer type: object main.AdminSecretsListResponse: properties: secrets: items: $ref: '#/components/schemas/main.AdminSecretResponse' type: array uniqueItems: false total: type: integer type: object main.AdminSecretsStatusResponse: properties: ready: type: boolean secrets: additionalProperties: type: boolean type: object type: object main.AffectedProjectDTO: properties: current_allowlist: items: type: string type: array uniqueItems: false project_id: type: string project_name: type: string type: object main.AgentCard: properties: a2a_allowed_callers: description: |- A2AAllowedCallers restricts which workspace IDs may invoke this agent via A2A. An empty list means any caller is permitted. items: type: string type: array uniqueItems: false a2a_enabled: description: A2AEnabled controls whether this agent is discoverable for A2A calls. type: boolean capabilities: items: type: string type: array uniqueItems: false input_modes: description: InputModes lists MIME types the agent accepts (e.g. "text/plain", "application/json"). items: type: string type: array uniqueItems: false output_modes: description: OutputModes lists MIME types the agent can produce. items: type: string type: array uniqueItems: false skills: description: Skills advertises discrete tasks the agent can perform. items: $ref: '#/components/schemas/main.AgentSkill' type: array uniqueItems: false summary: type: string type: object main.AgentLogEntry: properties: bootId: type: string executionId: type: string fields: additionalProperties: {} type: object level: type: string logger: type: string message: type: string podName: type: string service: type: string sessionId: type: string source: type: string tenantId: type: string timestamp: type: string traceId: type: string workspaceId: type: string type: object main.AgentLogsResponse: properties: hasMore: type: boolean logs: items: $ref: '#/components/schemas/main.AgentLogEntry' type: array uniqueItems: false nextCursor: type: string type: object main.AgentSkill: properties: description: type: string example_input: type: string example_output: type: string name: type: string type: object main.AtlasAccessListEntry: properties: cidr_block: type: string comment: type: string ip_address: type: string type: object main.AtlasAccessListResponse: properties: results: items: $ref: '#/components/schemas/main.AtlasAccessListEntry' type: array uniqueItems: false total_count: type: integer type: object main.AtlasClusterInfo: properties: connection_string_srv: type: string is_flex: type: boolean name: type: string provider: type: string region: type: string state_name: type: string tier: description: |- Tier is FLEX for Flex clusters and the Atlas instance size (M10, M0, ...) otherwise, including free/shared tiers. Surfaced unfiltered so clients can keep free/shared tiers out of cluster selection and refuse to adopt them; the platform does not gate selection server-side. type: string type: object main.AtlasClustersResponse: properties: results: items: $ref: '#/components/schemas/main.AtlasClusterInfo' type: array uniqueItems: false total_count: type: integer type: object main.AtlasDatabaseUserResponse: properties: username: type: string type: object main.AtlasFlexClusterResponse: properties: connection_string_srv: type: string id: type: string is_flex: type: boolean name: type: string provider: type: string region: type: string state_name: type: string tier: type: string type: object main.AtlasModelAPIKeyResponse: properties: id: type: string masked_secret: type: string name: type: string secret: type: string status: type: string type: object main.AtlasOrganization: properties: id: type: string is_deleted: type: boolean name: type: string type: object main.AtlasOrganizationMetadata: properties: environment: type: string id: type: string required: - environment - id type: object main.AtlasOrganizationsResponse: properties: results: items: $ref: '#/components/schemas/main.AtlasOrganization' type: array uniqueItems: false total_count: type: integer type: object main.AtlasProjectInfo: properties: cluster_count: type: integer created: type: string id: type: string name: type: string org_id: type: string type: object main.AtlasProjectLinkResponse: properties: environment: type: string project_id: type: string type: object main.AtlasProjectMetadata: properties: environment: type: string id: type: string organization_id: type: string required: - environment - id - organization_id type: object main.AtlasProjectsResponse: properties: results: items: $ref: '#/components/schemas/main.AtlasProjectInfo' type: array uniqueItems: false total_count: type: integer type: object main.AuditEvent: properties: action: $ref: '#/components/schemas/auditevent.Action' actor: $ref: '#/components/schemas/auditevent.Actor-bson_ObjectID' category: $ref: '#/components/schemas/auditevent.Category' failure_reason: type: string id: type: string metadata: additionalProperties: {} type: object outcome: $ref: '#/components/schemas/auditevent.Outcome' scope: $ref: '#/components/schemas/auditevent.Scope-bson_ObjectID' source_ip: type: string target: $ref: '#/components/schemas/auditevent.Target' timestamp: type: string type: object main.AuditEventsResponse: properties: audit_events: items: $ref: '#/components/schemas/main.AuditEvent' type: array uniqueItems: false has_more: type: boolean next_cursor: type: string type: object main.AuthToken: properties: created_at: type: string created_by: description: Who/what created this token type: string description: description: Human-readable description type: string expires_at: type: string id: type: string is_active: type: boolean last_used_at: description: Track usage type: string org_id: description: Org this token belongs to type: string project_id: description: Project this token belongs to type: string revoked_at: type: string revoked_by: type: string token_prefix: description: Bounded lookup prefix for identification (e.g., "agp_live_sk_") type: string user_id: description: User who owns this token type: string type: object main.CheckpointSession: properties: active_duration_ms: description: |- ActiveDurationMS sums each run's own elapsed time, so it agrees with the per-run durations the session's runs endpoint reports and excludes the gaps between turns. Zero from an orchestration engine that predates it. type: integer created_at: type: string first_message_preview: type: string last_activity: type: string latest_status: description: LatestStatus is the status of the session's most recent execution. type: string project_id: type: string session_id: type: string total_duration_ms: description: |- TotalDurationMS is wall-clock elapsed time from the session's first execution to its last activity, so it includes idle time between turns. type: integer total_tokens: description: |- TotalTokens is a lower bound: it sums the per-call counts recorded for LLM calls routed through the OE and excludes memory-extraction tokens. type: integer turns: type: integer user_id: type: string visibility: type: string wait_ms: description: |- WaitMS sums settled human-review wait across the session's runs, plus the open window so far on a currently suspended one. Zero from an orchestration engine that predates it. type: integer workspace_id: type: string type: object main.ComponentImages: properties: aer: description: AER is the legacy name of the agent sandbox image. type: string agent: description: Agent is the agent sandbox image. Same value as aer. type: string memory_server: type: string oe: type: string tool: type: string type: object main.CostByModel: properties: call_count: type: integer model: type: string percentage: type: number total_cost_usd: type: number total_tokens: type: integer type: object main.CostByWorkspace: properties: call_count: type: integer percentage: type: number total_cost_usd: type: number total_tokens: type: integer workspace_id: type: string type: object main.CostDashboardResponse: properties: by_model: items: $ref: '#/components/schemas/main.CostByModel' type: array uniqueItems: false by_workspace: items: $ref: '#/components/schemas/main.CostByWorkspace' type: array uniqueItems: false daily_trend: items: $ref: '#/components/schemas/main.DailyCostEntry' type: array uniqueItems: false success: type: boolean summary: $ref: '#/components/schemas/main.CostSummary' type: object main.CostSummary: properties: total_completion_tokens: type: integer total_cost_usd: type: number total_llm_calls: type: integer total_prompt_tokens: type: integer total_tokens: type: integer unpriced_llm_calls: type: integer type: object main.CreateAPIKeyRequest: properties: description: type: string expires_in: description: 'Optional: days until expiration (0 = never)' type: integer type: object main.CreateAtlasAccessListRequest: properties: cidr_block: type: string comment: type: string ip_address: type: string type: object main.CreateAtlasDatabaseUserRequest: properties: cluster_name: type: string password: type: string username: type: string required: - cluster_name - password - username type: object main.CreateAtlasFlexClusterRequest: properties: name: type: string provider: type: string region: type: string tier: type: string required: - name - provider - region type: object main.CreateAtlasModelAPIKeyRequest: properties: name: type: string required: - name type: object main.CreateInvitationRequest: properties: email: type: string role: type: string required: - email - role type: object main.DailyCostEntry: properties: call_count: type: integer date: type: string total_cost_usd: type: number total_tokens: type: integer type: object main.EffectivePolicyListResponse: properties: policies: items: $ref: '#/components/schemas/main.EffectivePolicyRowDTO' type: array uniqueItems: false type: object main.EffectivePolicyRowDTO: properties: effective_int_value: type: integer effective_string_list: description: |- The enforced allowlist. An empty array means nothing is allowed, which happens when the org and project lists are disjoint; null means no allowlist is enforced. The two must not collapse into one another. items: type: string type: array uniqueItems: false enabled: type: boolean organization: $ref: '#/components/schemas/main.effectivePolicySideDTO' project: $ref: '#/components/schemas/main.effectiveProjectSideDTO' source: description: organization | project | both | none type: string type: $ref: '#/components/schemas/main.PolicyType' type: object main.ErrorResponse: properties: code: type: string error: type: string success: type: boolean type: object main.Execution: properties: created_at: type: string error: type: string error_code: description: |- ErrorCode mirrors the OE's Execution.ErrorCode. Empty for an execution that never errored, or an older OE record predating this field. type: string execution_id: type: string message: type: string org_id: type: string project_id: type: string result: {} session_id: type: string startup_failure: $ref: '#/components/schemas/main.ExecutionStartupFailure' status: description: '"pending", "running", "suspended", "resuming", "completed", "error", "cancelled"' type: string suspend_context: additionalProperties: {} type: object suspend_reason: type: string updated_at: type: string user_id: type: string type: object main.ExecutionLog: properties: a2a_caller_workspace_id: type: string a2a_parent_execution_id: type: string a2a_target_agent_id: type: string a2a_target_agent_name: type: string completion_tokens: type: integer cost_usd: type: number decision: type: string duration_ms: type: number error: type: string execution_id: type: string guardrail_action: description: |- Guardrail decision fields (populated for kind="guardrail" logs by LogGuardrailDecision). These are top-level fields on the OE document; mapping them here ensures the API Gateway passes them through to the UI rather than dropping them during struct unmarshal. type: string guardrail_name: type: string guardrail_type: type: string id: type: string inputs: additionalProperties: {} type: object kind: description: |- Kind is "llm" for LLM calls, "tool" for ordinary tools, "memory" for memory operations, "a2a" for agent-to-agent calls, "guardrail" for guardrail decision events, and "policy" for platform-policy decision events. enum: - llm - tool - memory - a2a - guardrail - policy type: string log_source: description: |- LogSource identifies the platform component that recorded this log row (for example, "memory_proxy" for rows written by the platform's memory proxy). Empty for rows recorded from agent-driven calls. type: string matched_conditions: {} metadata: additionalProperties: {} type: object model: type: string org_id: type: string output: {} pod_name: description: Hostname/pod name where tool was executed type: string project_id: type: string prompt_tokens: description: Token usage and cost fields (populated for invoke_llm calls) type: integer root_execution_id: type: string root_session_id: type: string session_id: type: string span_id: type: string status: description: Step outcome; includes "cancelled" for caller-cancelled memory turn writes. type: string step_number: description: |- StepNumber identifies the step within its execution. It is what ties a log row to the step a client is looking at elsewhere — omit it here and the row still arrives, but nothing can say which step it belongs to. type: integer timestamp: format: date-time type: string tool: type: string tool_api_error: $ref: '#/components/schemas/main.ToolAPIError' tool_call_id: description: |- ToolCallID is the stable LLM tool-call id. Joins a tool call's start/result execution-log records to each other and to the session message. Empty for invoke_llm and other non-tool-call events. type: string total_tokens: type: integer trace_id: type: string triggered_policy_ids: items: type: string type: array uniqueItems: false user_id: type: string workspace_id: type: string type: object main.ExecutionLogsResponse: properties: count: type: integer has_more: type: boolean logs: items: $ref: '#/components/schemas/main.ExecutionLog' type: array uniqueItems: false next_cursor: description: |- NextCursor is the opaque after token for the next poll. Omitted when OE sent no position (empty first page). type: string success: type: boolean type: object main.ExecutionStartupFailure: properties: boot_id: type: string code: type: string component: type: string phase: type: string source: type: string type: object main.ExecutionStatusResponse: properties: error: type: string execution: $ref: '#/components/schemas/main.Execution' success: type: boolean type: object main.ExecutionsListResponse: properties: count: type: integer executions: items: $ref: '#/components/schemas/main.Execution' type: array uniqueItems: false success: type: boolean type: object main.FailedWorkspace: properties: error_message: type: string workspace_id: type: string workspace_name: type: string type: object main.HealthResponse: properties: status: type: string type: object main.InterruptExecutionRequest: properties: step_number: description: StepNumber is the execution step of the single tool/LLM call to interrupt. type: integer type: object main.InvokeWorkspaceRequest: additionalProperties: true properties: message: description: 'Optional when other agent fields are provided: chat input for chat agents. Reserved field name.' type: string resume_map: additionalProperties: {} description: |- ResumeMap contains per-interrupt answers resolved by OE. OE forwards it to the agent as ordinary input only when it starts a session's first execution, where no local suspended turn exists to answer. type: object session_id: description: Optional compatibility field. The gateway ignores it for session continuity. To continue a session, send X-Session-ID instead. Reserved field name. type: string user_id: description: Optional identity used for personalization and Memory isolation. Human and API key calls use this value, or default to the authenticated user. Service account calls always use the service account identity. Service accounts cannot yet act as another user. Reserved field name. type: string type: object main.InvokeWorkspaceResponse: properties: error: type: string error_code: type: string execution_id: type: string response: type: string status: type: string success: type: boolean suspend_context: additionalProperties: {} type: object suspend_reason: type: string type: object main.ListAPIKeysResponse: properties: count: type: integer keys: items: $ref: '#/components/schemas/main.AuthToken' type: array uniqueItems: false success: type: boolean type: object main.MemoryRuntimeStatusResponse: properties: blocked_on: type: string memory_image: description: MemoryImage is the image the runtime is currently pinned to. type: string message: type: string resolved_memory_image: description: ResolvedMemoryImage is the image this environment would pin right now. type: string state: type: string type: object main.Message: properties: additional_kwargs: additionalProperties: {} type: object content: type: string id: type: string name: description: Tool name for tool messages type: string role: type: string session_id: type: string timestamp: type: string tool_call_id: type: string tool_calls: items: $ref: '#/components/schemas/main.MessageToolCall' type: array uniqueItems: false type: object main.MessageToolCall: properties: args: {} id: type: string index: type: integer name: type: string type: type: string type: object main.NodeExecution: properties: description: description: Computed field, not stored in DB type: string duration_ms: type: number error: type: string execution_id: type: string id: type: string inputs: additionalProperties: {} type: object node: type: string org_id: type: string outputs: additionalProperties: {} type: object parent_run_id: type: string project_id: type: string root_execution_id: type: string root_session_id: type: string run_id: type: string session_id: type: string status: description: '"started", "success", "error"' type: string timestamp: format: date-time type: string user_id: type: string type: object main.NodeExecutionsResponse: properties: count: type: integer executions: items: $ref: '#/components/schemas/main.NodeExecution' type: array uniqueItems: false has_more: type: boolean next_cursor: description: |- NextCursor is the opaque after token for the next poll. Omitted when OE sent no position (empty first page). type: string success: type: boolean type: object main.OIDCTokenExchangeRequest: properties: code: description: Code is the one-time code received from the OIDC callback. type: string code_verifier: description: |- CodeVerifier is the optional PKCE code_verifier that redeems a code minted with a CLI-supplied code_challenge (browser login). Omitted by UI logins and older CLIs. type: string required: - code type: object main.OIDCTokenExchangeResponse: properties: access_token: type: string atlas_connection_status: enum: - connected - declined - failed type: string refresh_token: type: string token_type: type: string type: object main.OrgAdminDTO: properties: email: type: string name: type: string type: object main.OrgInvitationDTO: properties: created_at: type: string expires_at: type: string invitation_code: description: Only in environments where password signup is enabled. type: string invitation_id: description: Stable invitation _id (hex). type: string invitee_email: type: string role: type: string type: object main.OrgInvitationListResponse: properties: invitations: items: $ref: '#/components/schemas/main.OrgInvitationDTO' type: array uniqueItems: false total: type: integer type: object main.OrgMemberDTO: properties: created_at: type: string email: description: Resolved for display only. type: string role_assignments: items: $ref: '#/components/schemas/main.RoleAssignment' type: array uniqueItems: false updated_at: type: string user_id: description: Stable user _id (hex). type: string type: object main.OrgMemberListResponse: properties: members: items: $ref: '#/components/schemas/main.OrgMemberDTO' type: array uniqueItems: false total: type: integer type: object main.OrgPolicyPreviewRequest: properties: enabled: description: |- Whether the proposed policy would be enforced. Defaults to true when omitted, matching policy creation. type: boolean string_list: items: type: string type: array uniqueItems: false type: $ref: '#/components/schemas/main.PolicyType' type: object main.OrgPolicyPreviewResponse: properties: affected_projects: items: $ref: '#/components/schemas/main.AffectedProjectDTO' type: array uniqueItems: false type: object main.OrgSupportAccessGrantRequest: properties: duration_hours: type: integer type: object main.OrgSupportAccessStatusDTO: properties: active: type: boolean expires_at: type: string granted_at: type: string granted_by: type: string type: object main.OrganizationCreateRequest: properties: description: type: string name: description: |- Name is trimmed before validation. It must be 1-64 characters and may contain Unicode letters/numbers, spaces, and the characters - _ . ( ) , & @ + '. maxLength: 64 minLength: 1 type: string required: - name type: object main.OrganizationDTO: properties: admins: description: |- Admins lists the organization's ORG_ADMINs. Populated only by the platform admin listing; omitted on the member-facing organization endpoints. items: $ref: '#/components/schemas/main.OrgAdminDTO' type: array uniqueItems: false atlas: $ref: '#/components/schemas/main.AtlasOrganizationMetadata' created_at: type: string description: type: string id: type: string name: type: string source: $ref: '#/components/schemas/main.ResourceSource' updated_at: type: string type: object main.OrganizationListResponse: properties: atlas_reauth_required: description: |- AtlasReauthRequired is set on this 200 response when the Atlas grant is unusable but the gateway still returns the last reflected orgs as read-only. Clients should start recovery from this field; organization list does not return 401 PLATFORM_OAUTH_*. type: boolean limit: description: |- Limit and Offset echo the applied pagination. Set only by the paginated platform admin listing; omitted on the member-facing organization endpoints. type: integer offset: type: integer organizations: items: $ref: '#/components/schemas/main.OrganizationDTO' type: array uniqueItems: false total: type: integer type: object main.OrganizationUpdateRequest: properties: description: type: string name: description: |- Name is trimmed before validation. It must be 1-64 characters and may contain Unicode letters/numbers, spaces, and the characters - _ . ( ) , & @ + '. maxLength: 64 minLength: 1 type: string type: object main.PlatformOAuthCallbackRequest: properties: code: type: string error: type: string error_description: type: string state: type: string required: - state type: object main.PlatformOAuthCallbackResponse: properties: next: type: string type: object main.PlatformOAuthInitiateResponse: properties: authorize_url: type: string type: object main.PolicyCreateRequest: properties: enabled: type: boolean int_value: type: integer project_id: type: string scope: $ref: '#/components/schemas/main.PolicyScope' string_list: items: type: string type: array uniqueItems: false type: $ref: '#/components/schemas/main.PolicyType' required: - type type: object main.PolicyDTO: properties: created_at: type: string created_by: type: string enabled: type: boolean id: type: string int_value: type: integer org_id: type: string project_id: type: string scope: $ref: '#/components/schemas/main.PolicyScope' string_list: items: type: string type: array uniqueItems: false type: $ref: '#/components/schemas/main.PolicyType' updated_at: type: string updated_by: type: string type: object main.PolicyListResponse: properties: policies: items: $ref: '#/components/schemas/main.PolicyDTO' type: array uniqueItems: false total: type: integer type: object main.PolicyRolloutProject: properties: attempts: readOnly: true type: integer dead_lettered: readOnly: true type: boolean failure_kind: description: |- FailureKind is a stable classification, not the raw cause. The underlying error can carry driver and infrastructure detail and this route is reachable by any org member, so the raw text stays on the document and in logs for operators. readOnly: true type: string generation: description: |- Generation is the latest materialized runtime generation for the project, and ReceivedGeneration is the newest one ECP has acknowledged. They differ while a change is in flight to the data plane. readOnly: true type: integer project_id: readOnly: true type: string reason: readOnly: true type: string received_generation: readOnly: true type: integer type: object main.PolicyRolloutStatusResponse: properties: converged: readOnly: true type: integer dead_lettered: readOnly: true type: integer lagging_projects: description: |- LaggingProjects samples the projects behind the latest generation, capped at policyRolloutLaggingProjectLimit. Truncated reports whether the sample is partial. items: $ref: '#/components/schemas/main.PolicyRolloutProject' readOnly: true type: array uniqueItems: false missing_config: description: |- MissingConfig counts active projects with no runtime config at all. Expected when the org has no policies (there is nothing to materialize); otherwise it is a gap, which is why it is reported rather than folded into Converged. readOnly: true type: integer org_id: readOnly: true type: string pending_materialization: readOnly: true type: integer pending_publish: readOnly: true type: integer projects_total: description: |- ProjectsTotal counts the org's active projects, not its runtime-config rows, so a project that has never materialized still shows up in the denominator. readOnly: true type: integer truncated: readOnly: true type: boolean type: object main.PolicyScope: enum: - org - project type: string x-enum-varnames: - PolicyScopeOrg - PolicyScopeProject main.PolicyType: enum: - MAX_TOOL_CALLS_PER_EXECUTION - MAX_LLM_CALLS_PER_EXECUTION - MAX_EXECUTION_DURATION_MS - MAX_TOKENS_PER_EXECUTION - MAX_TOKENS_PER_SESSION - AUTHORIZED_TOOLS - AUTHORIZED_MODELS type: string x-enum-varnames: - TypeMaxToolCalls - TypeMaxLLMCalls - TypeMaxExecutionDuration - TypeMaxExecutionTokens - TypeMaxSessionTokens - TypeAuthorizedTools - TypeAuthorizedModels main.PolicyUpdateRequest: properties: enabled: type: boolean int_value: type: integer string_list: items: type: string type: array uniqueItems: false type: object main.ProjectCreateRequest: properties: allow_member_invites: type: boolean description: type: string name: description: |- Name is trimmed before validation. It must be 1-64 characters and may contain Unicode letters/numbers, spaces, and the characters - _ . ( ) , & @ + '. maxLength: 64 minLength: 1 type: string sharing_policy: $ref: '#/components/schemas/main.ProjectSharingPolicy' required: - name type: object main.ProjectDTO: properties: allow_member_invites: type: boolean atlas: $ref: '#/components/schemas/main.AtlasProjectMetadata' can_manage_deployments: type: boolean created_at: type: string description: type: string id: type: string name: type: string org_id: type: string sharing_policy: $ref: '#/components/schemas/main.ProjectSharingPolicy' source: $ref: '#/components/schemas/main.ResourceSource' updated_at: type: string workspace_count: description: |- WorkspaceCount is the number of non-deleted workspaces in the project. Included on list responses and omitted on single-project GET. type: integer type: object main.ProjectDeleteConflictDetails: properties: truncated: description: |- Truncated is true when WorkspaceCount exceeds the cap and the preview is partial. type: boolean workspace_count: description: WorkspaceCount is the total active workspace count in the project. type: integer workspace_ids: description: |- WorkspaceIDs is the first N (currently 10) active workspace IDs. Capped to keep the response bounded for projects with many workspaces. items: type: string type: array uniqueItems: false type: object main.ProjectDeleteConflictResponse: properties: code: type: string detail: description: alias of Error for UI ApiError compatibility type: string details: $ref: '#/components/schemas/main.ProjectDeleteConflictDetails' error: type: string success: type: boolean type: object main.ProjectInvitationDTO: properties: created_at: type: string expires_at: type: string invitation_code: type: string invitation_id: description: Stable invitation _id (hex). type: string invitee_email: type: string org_id: description: The project's parent org (hex). type: string role: type: string type: object main.ProjectInvitationListResponse: properties: invitations: items: $ref: '#/components/schemas/main.ProjectInvitationDTO' type: array uniqueItems: false total: type: integer type: object main.ProjectListResponse: properties: atlas_reauth_required: description: |- AtlasReauthRequired is set on this 200 response when the Atlas grant is unusable but the gateway still returns the last reflected projects as read-only. Clients should start recovery from this field; project list does not return 401 PLATFORM_OAUTH_*. type: boolean projects: items: $ref: '#/components/schemas/main.ProjectDTO' type: array uniqueItems: false total: type: integer type: object main.ProjectMemberDTO: properties: created_at: type: string email: description: Resolved for display only. type: string name: description: Display name; empty when the user record has none. type: string org_id: description: The project's parent org (hex). type: string roles: description: Effective project roles (direct + inherited). items: $ref: '#/components/schemas/main.RoleAssignment' type: array uniqueItems: false updated_at: type: string user_id: description: Stable user _id (hex). type: string type: object main.ProjectMemberListResponse: properties: members: items: $ref: '#/components/schemas/main.ProjectMemberDTO' type: array uniqueItems: false total: type: integer type: object main.ProjectSharingPolicy: properties: allowed_sources: items: type: string type: array uniqueItems: false share_modes: items: type: string type: array uniqueItems: false shareable: type: boolean type: object main.ProjectUpdateRequest: properties: allow_member_invites: type: boolean description: type: string name: description: |- Name is trimmed before validation. It must be 1-64 characters and may contain Unicode letters/numbers, spaces, and the characters - _ . ( ) , & @ + '. maxLength: 64 minLength: 1 type: string sharing_policy: $ref: '#/components/schemas/main.ProjectSharingPolicy' type: object main.ProjectWorkspaceSecretsResponse: properties: failed_workspaces: items: $ref: '#/components/schemas/main.FailedWorkspace' type: array uniqueItems: false secrets: items: $ref: '#/components/schemas/main.WorkspaceScopedSecret' type: array uniqueItems: false truncated: type: boolean type: object main.RequestedImage: properties: component: type: string digest: type: string sandbox: description: |- Sandbox is the canonical sandbox name for known component values. Omitted for unknown upstream names. type: string type: object main.ResourceSource: enum: - atlas - agent_engine type: string x-enum-varnames: - ResourceSourceAtlas - ResourceSourceAgentEngine main.ResumeExecutionRequest: properties: decision: example: approved type: string reviewer_notes: example: Reviewed and approved. type: string suspend_generation: description: |- SuspendGeneration pins the decision to the suspension snapshot the reviewer was shown (from the execution's suspend_generation). OE rejects the resume with a conflict when the current suspension differs, so an approval is never applied to review content the reviewer never saw. example: 1 minimum: 0 type: integer required: - decision type: object main.ResumeExecutionResponse: properties: error: type: string execution_id: type: string status: type: string success: type: boolean type: object main.RoleAssignment: properties: org_id: type: string project_id: type: string role: type: string type: object main.RuntimeSessionDTO: properties: is_test_session: type: boolean last_activity_at: type: string scheduled_release_at: type: string session_id: type: string status: type: string type: object main.RuntimeSessionStopResponse: properties: session_id: type: string status: type: string type: object main.RuntimeSessionsListResponse: properties: sessions: items: $ref: '#/components/schemas/main.RuntimeSessionDTO' type: array uniqueItems: false type: object main.SecretRuntimeStatusResponse: properties: ready: readOnly: true type: boolean reason: readOnly: true type: string source: readOnly: true type: string type: object main.SessionConflictResponse: properties: blocking_execution_id: type: string blocking_status: type: string code: type: string error: type: string last_activity_at: type: string type: object main.SessionMessagesResponse: properties: history_status: description: HistoryStatus reports whether Messages is authoritative or still warming. type: string latest_status: description: LatestStatus is the status of the session's most recent execution. type: string messages: items: $ref: '#/components/schemas/main.Message' type: array uniqueItems: false type: object main.SessionRun: properties: active_duration_ms: type: integer completion_tokens: type: integer duration_ms: description: DurationMS is wall-clock time from the run's start to its last update. type: integer error: type: string error_code: type: string execution_id: type: string invoker_user_id: type: string memory_recalls: description: |- MemoryRecalls and MemorySaves count settled memory steps, a lower bound on a truncated read. type: integer memory_saves: type: integer prompt_tokens: description: |- PromptTokens and CompletionTokens split TotalTokens. Both absent when the run has no settled llm step. type: integer run_number: description: |- RunNumber is the run's 1-based position in the session, oldest first. When truncated is true it is relative to the returned window instead: the oldest runs are the ones dropped at the cap, so run 1 is not the session's first. type: integer session_id: type: string slowest_step: $ref: '#/components/schemas/main.SessionRunStepRef' started_at: type: string startup_failure: $ref: '#/components/schemas/main.ExecutionStartupFailure' status: type: string steps: items: $ref: '#/components/schemas/main.SessionRunStep' type: array uniqueItems: false summary: description: Summary is the run's invoking message, truncated server-side. type: string time_to_first_event_ms: description: |- TimeToFirstEventMS is the first step's offset, absent when the run has no steps yet. type: integer total_tokens: description: |- TotalTokens sums the run's settled llm steps, so it is a lower bound on what the run actually spent. type: integer user_id: description: |- UserID and InvokerUserID mirror the run's execution identity: the delegation target the run executed as and the gateway-authenticated caller who started it. Either may be absent — see the OE's SessionRun. Both are omitted from the support-safe view. type: string wait_ms: description: |- WaitMS is the run's settled human-review wait, absent when the run never suspended. ActiveDurationMS excludes that wait; both absent from an orchestration engine that predates them. type: integer workspace_id: type: string type: object main.SessionRunStep: properties: completion_tokens: type: integer duration_ms: description: DurationMS is absent for a step that has not settled yet. type: number error: type: string kind: description: |- Kind is the step's category: llm, tool, memory, guardrail, policy, a2a, or agent_step. type: string memory_op: description: MemoryOp is "recall" or "save" on a settled memory step, absent otherwise. type: string name: type: string presented: type: string presented_truncated: type: boolean prompt_tokens: description: |- PromptTokens and CompletionTokens split TotalTokens, both present only on a settled llm step. type: integer review_outcome: description: |- ReviewOutcome, WaitMS and ReviewTrigger are present only on human_review steps: the wait's state ("pending", then "approved"/"rejected"), its settled length in ms (absent while pending), and the guardrail that routed the call to review. type: string review_trigger: type: string reviewer: description: |- Reviewer/ReviewerNotes/Presented mirror the OE review record: deciding human, their note, and a capped excerpt of what they reviewed. type: string reviewer_notes: type: string run_id: description: |- RunID is the graph node invocation's identifier, present only on agent_step. It is the only key that ties a node step to its node_executions row. type: string span_id: description: SpanID joins this step to its full trace detail in the spans collection. type: string start_offset_ms: description: StartOffsetMS is milliseconds from the run's start to this step's start. type: integer started_at: type: string status: type: string step_number: description: |- StepNumber is the value the interrupt endpoint targets. Absent on agent_step, which records graph structure and has no interruptible step. type: integer tool_call_id: type: string total_tokens: description: TotalTokens is present only on settled llm steps. type: integer wait_ms: type: integer type: object main.SessionRunStepRef: description: SlowestStep is absent when the run has no settled step. properties: duration_ms: type: number kind: type: string name: type: string step_number: type: integer type: object main.SessionRunsResponse: properties: count: type: integer runs: items: $ref: '#/components/schemas/main.SessionRun' type: array uniqueItems: false truncated: description: |- Truncated reports that the session had more rows than the OE returns in one read, so this is a partial view. Mirrored from the OE response. type: boolean type: object main.SessionsListResponse: properties: has_more: type: boolean limit: type: integer next_cursor: description: |- NextCursor is an opaque token to pass back as the `cursor` query param, nil when this page is the last. Opaque so the paging position can change shape without breaking clients, matching the convention the other paged endpoints on this gateway already use. type: string sessions: items: $ref: '#/components/schemas/main.CheckpointSession' type: array uniqueItems: false total_count: description: |- TotalCount is the number of sessions matching the filter. Present only on the first page: counting it means fetching every match, which is what cursor paging exists to avoid, and it cannot change mid-walk. type: integer truncated: type: boolean type: object main.SignupRequest: properties: email: type: string invitation_code: type: string name: type: string pwd: type: string required: - email - invitation_code - pwd type: object main.StartupFailureResponse: properties: boot_id: type: string code: type: string component: description: Component is the legacy internal component name (aer, tool, platform). type: string error: type: string execution_id: type: string sandbox: description: Sandbox is the canonical public sandbox name for known components. type: string source: type: string success: type: boolean type: object main.TokenPair: properties: access_token: type: string refresh_token: type: string token_type: type: string type: object main.ToolAPIError: properties: classification: type: string error_code: type: string http_status: type: integer provider_type: type: string reason: type: string retryable: description: True if a new provider call might succeed (429/503/timeout/connect). Must not replay this tool call. type: boolean type: object main.Trace: properties: attributes: additionalProperties: {} type: object duration_ns: type: integer end_time_ns: type: integer events: items: {} type: array uniqueItems: false kind: type: string name: type: string parent_span_id: type: string resource: additionalProperties: {} type: object root_execution_id: type: string root_session_id: type: string session_id: type: string span_id: type: string start_time_ns: type: integer status: additionalProperties: {} type: object trace_id: type: string type: object main.TracesResponse: properties: count: type: integer success: type: boolean traces: items: $ref: '#/components/schemas/main.Trace' type: array uniqueItems: false type: object main.UpdateAtlasDatabaseUserRequest: properties: cluster_name: type: string password: type: string required: - cluster_name - password type: object main.UpdateOrgUserRoleRequest: properties: role: type: string required: - role type: object main.UpdateProjectUserRequest: properties: role: description: New project-level role type: string required: - role type: object main.UpsertPlatformProjectAtlasLinkRequest: properties: environment: type: string project_id: type: string type: object main.UserDTO: properties: created_at: type: string email: description: User email, resolved for display only. type: string name: description: User-provided display name; empty when the record has none. type: string org_ids: items: type: string type: array uniqueItems: false organizations: description: Org memberships with display names; parallels OrgIDs. items: $ref: '#/components/schemas/main.UserOrgRef' type: array uniqueItems: false role_assignments: description: Scoped role assignments only items: $ref: '#/components/schemas/main.RoleAssignment' type: array uniqueItems: false updated_at: type: string user_id: description: Stable user _id (hex) — the canonical user identifier. type: string type: object main.UserInfo: properties: atlas_connection_required: description: |- AtlasConnectionRequired is true when Atlas IAM delegation is on and no usable Atlas OAuth grant is available — including a recorded auth failure or circuit-open token. Federated login brokers a nested Atlas grant; password login may still auto-start GET /api/v1/oauth/atlas/initiate. type: boolean atlas_iam_enabled: description: |- AtlasIAMEnabled is true while Atlas IAM delegation is active for the user, independent of Atlas connection state (AtlasConnectionRequired flips off once a grant exists). The UI uses it to hide creation actions the Gateway rejects under delegation, such as creating Agent Engine organizations. type: boolean email: type: string last_selected_org_id: description: |- LastSelectedOrgID is the user's most recently selected organization ID in the UI. Hint only; callers re-validate against current memberships. Omitted when unset. type: string last_selected_project_id: description: |- LastSelectedProjectID is the user's most recently selected project ID in the UI. Hint only; callers re-validate against current memberships. Omitted when unset. type: string name: type: string org_ids: items: type: string type: array uniqueItems: false role_assignments: items: $ref: '#/components/schemas/main.APIRoleAssignment' type: array uniqueItems: false user_id: type: string type: object main.UserInvitationDTO: properties: created_at: type: string expires_at: type: string id: type: string invitee_email: type: string org_id: type: string org_name: type: string project_id: type: string role: type: string type: description: '"org" or "project"' type: string type: object main.UserInvitationListResponse: properties: invitations: items: $ref: '#/components/schemas/main.UserInvitationDTO' type: array uniqueItems: false total: type: integer type: object main.UserOrgRef: properties: name: type: string org_id: type: string type: object main.WorkspaceDTO: properties: aer_http_endpoint: description: AERHTTPEndpoint is the legacy name of the agent sandbox HTTP endpoint. type: string agent_card: $ref: '#/components/schemas/main.AgentCard' agent_grpc_endpoint: type: string agent_http_endpoint: description: AgentHTTPEndpoint is the agent sandbox HTTP endpoint. Same value as aer_http_endpoint. type: string auto_deploy: description: |- AutoDeploy is the ECP-owned per-app auto-deploy toggle. ECP-owned, fetched on each detail GET (not persisted in the gateway DB). Absent when ECP has no value or is unreachable; the UI treats absent as off. type: boolean completion_rate: type: number created_date: type: string current_deployment_id: type: string current_payload_ref: type: string description: type: string features: $ref: '#/components/schemas/main.WorkspaceFeatures' framework: type: string github_installation_id: description: |- GithubInstallationID is the GitHub App installation that owns the repo. ECP-owned, fetched on each detail GET (not persisted in the gateway DB), so it works for workspaces created before this field existed. The UI needs it to list the repo's branches when editing the tracked branch. type: integer gitops: $ref: '#/components/schemas/main.WorkspaceGitOps' id: type: string instances: $ref: '#/components/schemas/main.WorkspaceInstancesDTO' invocations: description: |- Execution metrics over a rolling 24h window. All five fields are pointers so the wire can distinguish two cases the UI needs to render differently: (a) the OE metrics fetch failed (soft-fail — all five fields absent), or (b) the window contains zero invocations / no completed executions (Invocations is set to 0 and the latency/rate fields are absent). UI distinguishes "—" from "0 invocations" via Invocations != nil. type: integer language: type: string last_invoked_at: format: date-time type: string metrics_computed_at: format: date-time type: string metrics_window_start: format: date-time type: string name: type: string org_id: type: string p95_latency_ms: type: number project_id: type: string release_mode: description: |- ReleaseMode is the ECP-owned webhook release policy ("push" | "tag-release" | "api-only"). Fetched on each detail GET; absent when ECP has no value or is unreachable. type: string status: description: |- Status is the ECP-owned active/paused signal. The gateway fetches it from ECP on each detail GET — it is not persisted locally. Absent when ECP is unreachable; UI treats absent as not-paused. enum: - active - paused - error - disconnected - deleting type: string subdirectory: type: string updated_date: type: string workspace_id: type: string workspace_name: type: string type: object main.WorkspaceFeatures: properties: guardrails: type: boolean memory: type: boolean playground: description: |- Playground reports whether playground UI is provisioned for the workspace (nil/true = provisioned, today's behavior). When false, callers use the invoke API directly. type: boolean use_custom_parser: description: |- UseCustomParser, when true, makes the Gateway emit only the agent's output-parser custom events on the invoke stream (dropping platform frames). Persisted from agent.yaml features at agentengine init. type: boolean type: object main.WorkspaceGitOps: properties: branch: type: string connection_ref: type: string github_installation_id: format: int64 type: integer manifest_path: type: string provider: type: string repo_url: type: string type: object main.WorkspaceGitOpsUpdateRequest: properties: branch: type: string connection_ref: type: string manifest_path: type: string provider: type: string repo_url: type: string type: object main.WorkspaceInstancesDTO: description: |- Instances reports the workspace's instance counts (active, standby, and starting), fetched read-time from the workspace's OE cell. Absent when OE is unreachable or the workspace does not run pooled (e.g. container mode). Deliberately free of any internal implementation naming: this is a customer-facing field. properties: active: type: integer pooled: type: boolean standby: type: integer starting: type: integer type: object main.WorkspaceListResponse: properties: total: type: integer workspaces: items: $ref: '#/components/schemas/main.WorkspaceDTO' type: array uniqueItems: false type: object main.WorkspaceScopedSecret: properties: created_at: type: string description: type: string name: type: string updated_at: type: string version: type: integer workspace_id: type: string workspace_name: type: string type: object main.WorkspaceStatusEntry: properties: status: type: string workspace_id: type: string type: object main.WorkspaceStatusListResponse: properties: statuses: items: $ref: '#/components/schemas/main.WorkspaceStatusEntry' type: array uniqueItems: false total: type: integer type: object main.WorkspaceStatusPatchResponse: properties: app_id: type: string org_id: type: string project_id: type: string status: example: active type: string warnings: items: type: string type: array uniqueItems: false type: object main.WorkspaceUpdateRequest: properties: agent_card: $ref: '#/components/schemas/main.AgentCard' auto_deploy: description: |- AutoDeploy is an app-level ECP field (not persisted in the gateway DB); forwarded verbatim to ECP's app PATCH. type: boolean description: type: string features: $ref: '#/components/schemas/main.WorkspaceFeatures' framework: type: string gitops: $ref: '#/components/schemas/main.WorkspaceGitOpsUpdateRequest' name: type: string release_mode: description: |- ReleaseMode is an app-level ECP field (not persisted in the gateway DB); forwarded verbatim to ECP's app PATCH. Controls webhook-triggered builds only — API-triggered releases are available in every mode. type: string status: description: |- Status is a pause/resume signal ("active" | "paused"). The gateway does not persist it locally; the handler forwards a status-only patch straight to ECP, which runs pause-teardown / resume-redeploy. type: string subdirectory: type: string workspace_name: type: string type: object main.agentEgressIPsResponse: properties: egress_ips: items: type: string type: array uniqueItems: false type: object main.buildContext2Request: properties: format_style: type: string include_memories: type: boolean max_tokens: description: |- MaxTokens is the gross context-construction budget (not a fetch cost), interpreted like build_context: the server subtracts a 500-token formatting reserve, then greedily selects whole memory chunks that fit. minimum: 1 type: integer model_type: type: string query: type: string query_embedding: items: type: number type: array uniqueItems: false rerank: description: Rerank reorders the merged results by a relevance rerank when available. type: boolean session_id: type: string sources: description: |- Sources is the explicit, per-source-configured set to search; the memory server enforces the count bounds (1..MAX_CONTEXT2_SOURCES), each source's top_k bounds, and the no-duplicate-source rule. items: $ref: '#/components/schemas/main.sourceSpec' type: array uniqueItems: false user_id: type: string visibility: type: string required: - query - sources - user_id type: object main.buildContextRequest: properties: enabled_sources: description: |- EnabledSources selects memory sources (stm, episodic, semantic, taxonomic, procedural); omitted defaults to episodic, semantic. items: type: string type: array uniqueItems: false format_style: type: string include_memories: type: boolean max_tokens: description: |- MaxTokens is the gross context-construction budget (not a fetch cost). After retrieval and ranking the memory server subtracts a 500-token formatting reserve, then greedily selects whole memory chunks that fit. Positive values at or below 500 leave no budget for memories. Values above 500 can still yield empty context when no chunk fits. minimum: 1 type: integer metadata_filter: additionalProperties: {} type: object model_type: type: string query: type: string query_embedding: items: type: number type: array uniqueItems: false session_id: type: string similarity_threshold: type: number top_k: maximum: 200 minimum: 1 type: integer user_id: type: string visibility: type: string required: - query - user_id type: object main.ecrTokenResponse: properties: expires_at: type: string password: type: string registry_url: type: string repositories: items: type: string type: array uniqueItems: false username: type: string type: object main.effectivePolicySideDTO: properties: enabled: type: boolean int_value: type: integer string_list: items: type: string type: array uniqueItems: false type: object main.effectiveProjectSideDTO: properties: enabled: type: boolean id: type: string int_value: type: integer string_list: items: type: string type: array uniqueItems: false type: object main.featureFlagsResponse: properties: flags: additionalProperties: type: boolean type: object type: object main.memoryConfigGetResponse: properties: config: $ref: '#/components/schemas/memoryconfig.MemoryConfigSchema' generation: type: integer received_generation: type: integer updated_at: type: string type: object main.memoryConfigPutResponse: properties: config: $ref: '#/components/schemas/memoryconfig.MemoryConfigSchema' generation: type: integer updated_at: type: string type: object main.oauthErrorResponse: properties: error: type: string error_description: type: string type: object main.oauthTokenRequest: properties: client_id: description: ClientID may also be sent as the HTTP Basic username (preferred). type: string client_secret: description: ClientSecret may also be sent as the HTTP Basic password (preferred). type: string grant_type: description: GrantType must be "client_credentials". enum: - client_credentials type: string required: - grant_type type: object main.oauthTokenResponse: properties: access_token: type: string expires_in: type: integer token_type: type: string type: object main.platformEgressIPsResponse: properties: outbound: additionalProperties: additionalProperties: items: type: string type: array type: object type: object type: object main.recordTurnRequest: properties: agent_id: type: string content: type: string idempotency_key: type: string is_error: type: boolean metadata: additionalProperties: {} type: object model_name: type: string role: type: string session_id: type: string tool_call_id: type: string tool_calls: items: additionalProperties: {} type: object type: array uniqueItems: false tool_name: type: string user_id: type: string required: - role - session_id - user_id type: object main.searchRequest: properties: dedup_threshold: type: number deduplicate: type: boolean domain: type: string metadata_filter: additionalProperties: {} type: object query: type: string rank: type: boolean session_id: type: string similarity_threshold: type: number tags: items: type: string type: array uniqueItems: false top_k: maximum: 500 minimum: 1 type: integer type: type: string user_id: type: string visibility: type: string required: - query - type type: object main.serviceAccountDTO: properties: active_secret: $ref: '#/components/schemas/main.serviceAccountSecretDTO' client_id: type: string created_at: type: string description: type: string id: type: string ip_access_list: items: type: string type: array uniqueItems: false is_active: type: boolean is_system_managed: type: boolean name: type: string org_id: type: string owner: type: string project_id: type: string role_assignments: items: $ref: '#/components/schemas/main.RoleAssignment' type: array uniqueItems: false type: type: string updated_at: type: string type: object main.serviceAccountIPAccessListRequest: properties: ip_access_list: description: Required. Explicit [] clears to unrestricted; omit/null is 400. At most 100 entries. items: type: string maxItems: 100 type: array uniqueItems: false required: - ip_access_list type: object main.serviceAccountListResponse: properties: caller_ip: description: |- CallerIP is the admin's IP as the gateway sees it (Gin ClientIP / trusted proxy). Omitted when unknown. Piggybacked here so the IP Access List UI can read it from the cached list response (Atlas-style; no dedicated echo API). type: string next_cursor: description: |- NextCursor is the keyset cursor for the following page; empty when this page is the last. total always counts the whole scope, ignoring cursor. type: string service_accounts: items: $ref: '#/components/schemas/main.serviceAccountDTO' type: array uniqueItems: false total: type: integer type: object main.serviceAccountPatchRequest: properties: roles: items: type: string type: array uniqueItems: false required: - roles type: object main.serviceAccountResponse: properties: service_account: $ref: '#/components/schemas/main.serviceAccountDTO' type: object main.serviceAccountRotateRequest: properties: secret_expires_after_hours: description: |- Optional secret TTL in hours. Defaults to 2160 (90 days) when omitted, including an empty rotate body. type: integer type: object main.serviceAccountSecretDTO: properties: created_at: type: string expires_at: type: string last_used_at: type: string masked_value: type: string type: object main.serviceAccountSecretResponse: properties: client_secret: type: string service_account: $ref: '#/components/schemas/main.serviceAccountDTO' type: object main.sourceSpec: properties: metadata_filter: additionalProperties: {} type: object mode: type: string source: type: string top_k: type: integer required: - source type: object main.traceExportConfigGetResponse: properties: config: $ref: '#/components/schemas/traceexportconfig.TraceExportConfigSchema' generation: type: integer received_generation: type: integer updated_at: type: string type: object main.traceExportConfigPutResponse: properties: generation: type: integer updated_at: type: string type: object main.traceExportPresetsResponse: properties: presets: items: $ref: '#/components/schemas/traceexportconfig.Preset' type: array uniqueItems: false type: object main.updateLastSelectedOrgRequest: properties: org_id: type: string type: object main.updateLastSelectedProjectRequest: properties: project_id: type: string type: object main.userServiceAccountCreateRequest: properties: description: maxLength: 500 type: string ip_access_list: description: Optional IP/CIDR allowlist. Empty or omitted means unrestricted. At most 100 entries. items: type: string maxItems: 100 type: array uniqueItems: false name: maxLength: 100 type: string roles: description: |- Roles is the initial role set. Exactly one role is required. Organization accounts accept ORG_GROUP_CREATOR or ORG_READ_ONLY. Project accounts accept PROJECT_OWNER, PROJECT_READ_ONLY, or AGENT_DEVELOPER. Legacy Agent Engine names (ORG_ADMIN, ORG_MEMBER, PROJECT_MEMBER) are still accepted. role_assignments echoes the stored Agent Engine role those names resolve to. items: type: string maxItems: 1 minItems: 1 type: array uniqueItems: false secret_expires_after_hours: description: Optional secret TTL in hours. Defaults to 2160 (90 days) when omitted. type: integer required: - name - roles type: object memoryconfig.BackgroundExtractionConfig: properties: snapshot: $ref: '#/components/schemas/memoryconfig.SnapshotConfig' type: object memoryconfig.CapacitySpec: description: |- Capacity sets memory-server's replica count for this project. Infra-only: never mounted into the memory-server container itself. properties: max_replicas: maximum: 10 minimum: 1 type: integer min_replicas: maximum: 10 minimum: 1 type: integer type: object memoryconfig.CustomMemoryType: properties: collection: type: string name: type: string tags: items: $ref: '#/components/schemas/memoryconfig.CustomTagDeclaration' maxItems: 10 type: array uniqueItems: false required: - collection - name type: object memoryconfig.CustomTagDeclaration: properties: name: type: string type: object memoryconfig.ExtractionLLMConfig: properties: api_key_secret: description: |- APIKeySecret is the project-scoped secret name that holds the extraction credential. One of: LLM_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, CEREBRAS_API_KEY. Omit to auto-detect from those env vars. enum: - LLM_API_KEY - OPENAI_API_KEY - ANTHROPIC_API_KEY - GEMINI_API_KEY - CEREBRAS_API_KEY type: string auth_header: description: |- AuthHeader is the HTTP header the gateway expects for the API key. "authorization" sends Bearer auth (LiteLLM default). "api-key" sends the Azure / Grove style header. Omit for the provider default. enum: - authorization - api-key type: string base_url: description: |- BaseURL is an optional gateway endpoint. HTTPS is required except for loopback HTTP. Userinfo (embedded credentials) is rejected. When set, extraction calls this URL instead of the public provider API. maxLength: 2048 type: string model: maxLength: 256 type: string provider: description: 'Provider must be one of: openai, anthropic, gemini, cerebras.' enum: - openai - anthropic - gemini - cerebras type: string type: object memoryconfig.ExtractionPipelineConfig: properties: enabled: description: |- Enabled lists which extraction types to run. Each element must be one of: semantic, episodic, taxonomic, preferences, procedural. items: type: string type: array uniqueItems: false episodic: $ref: '#/components/schemas/memoryconfig.ExtractionTypeConfig' preferences: $ref: '#/components/schemas/memoryconfig.ExtractionTypeConfig' procedural: $ref: '#/components/schemas/memoryconfig.ExtractionTypeConfig' semantic: $ref: '#/components/schemas/memoryconfig.ExtractionTypeConfig' taxonomic: $ref: '#/components/schemas/memoryconfig.ExtractionTypeConfig' type: object memoryconfig.ExtractionTypeConfig: properties: prompt: maxLength: 4096 type: string type: object memoryconfig.MemoryConfigSchema: properties: background_extraction: $ref: '#/components/schemas/memoryconfig.BackgroundExtractionConfig' capacity: $ref: '#/components/schemas/memoryconfig.CapacitySpec' custom_memory_types: description: |- CustomMemoryTypes declares user-defined memory types the memory server provisions. Create-only: the gateway rejects edits or removals of previously accepted declarations. The count limit is enforced by ValidateCustomMemoryTypes, not a struct tag, so the constant stays the single source of truth. The binding:"max" tag is doc-only — the handler decodes with json.Decoder, not gin binding, so it has no runtime effect; it exists solely to surface the limit in the generated OpenAPI spec. items: $ref: '#/components/schemas/memoryconfig.CustomMemoryType' maxItems: 5 type: array uniqueItems: false extraction: $ref: '#/components/schemas/memoryconfig.ExtractionPipelineConfig' extraction_llm: $ref: '#/components/schemas/memoryconfig.ExtractionLLMConfig' log_level: description: |- LogLevel sets the memory-server root log level for the project. One of: debug, info, warning, error, critical. Omit the field to leave the server default (info); an explicit empty string is rejected. enum: - debug - info - warning - error - critical type: string metadata_partition_index: additionalProperties: items: type: string type: array description: |- MetadataPartitionIndex selects, per in-scope memory type, which search index legs carry the partition filter fields: "vector", "text", or "both". A type omitted from the map defaults to the vector leg only. Freely mutable — it only affects which legs newly-provisioned indexes get. type: object metadata_partition_key: description: |- MetadataPartitionKey declares filterable metadata attributes that every in-scope memory type (semantic, episodic, procedural, short_term) indexes as a partition filter field. Create-only: the gateway rejects removing or retyping a previously accepted key (adds are allowed). The count limit is enforced by ValidateMetadataPartition, not a struct tag, so the constant stays the single source of truth. The binding:"max" tag is doc-only — the handler decodes with json.Decoder, not gin binding, so it has no runtime effect; it exists solely to surface the limit in the OpenAPI spec. items: $ref: '#/components/schemas/memoryconfig.MetadataPartitionKey' maxItems: 10 type: array uniqueItems: false short_term: $ref: '#/components/schemas/memoryconfig.ShortTermConfig' tasks: $ref: '#/components/schemas/memoryconfig.TasksConfig' voyage: $ref: '#/components/schemas/memoryconfig.VoyageConfig' type: object memoryconfig.MetadataPartitionKey: properties: name: type: string type: type: string required: - name - type type: object memoryconfig.ShortTermConfig: properties: embed_on_write: description: |- EmbedOnWrite makes the memory server embed a turn's content synchronously at write time when the caller supplies no embedding, so the turn is searchable by relevance immediately instead of waiting for background embedding. Defaults to false (fast write path). Distinct from SnapshotConfig.EmbedSTMBeforePromotion, which batch-embeds in the worker before a promotion check. type: boolean type: object memoryconfig.SnapshotConfig: properties: delete_promoted: type: boolean embed_stm_before_promotion: type: boolean max_messages: type: integer stale_minutes: type: integer topic_shift_enabled: type: boolean topic_shift_threshold: type: number ttl_days: type: integer type: object memoryconfig.TasksConfig: description: Tasks tunes the memory server's background task processing. properties: legacy_retry: description: |- LegacyRetry reverts task-failure settlement to the legacy bounded retry budget (three retries, then dead-letter) instead of retrying transient failures until task expiry. Emergency brake: enabling it can mass-terminalize an accumulated retry backlog. Defaults to false. type: boolean type: object memoryconfig.VoyageConfig: properties: dimension: type: integer model: maxLength: 256 type: string type: object traceexportconfig.Preset: properties: display_name: type: string docs_url: type: string endpoint_template: type: string headers: additionalProperties: type: string description: |- Headers are the NON-SECRET fields a customer fills in for this destination (e.g. a workspace id). Keys map to header names; values are placeholders. type: object id: type: string protocol: type: string resource_attributes: additionalProperties: type: string description: |- ResourceAttributes names the OTLP resource attribute(s) this destination requires (e.g. a project identifier), as placeholder keys with empty values. Unlike Headers these attributes ride inside the span data itself, not an HTTP header line; a customer always supplies the value, since it typically names a project on the destination's own side. type: object secret_header_keys: description: |- SecretHeaderKeys names the header(s) supplied via headers_secret_ref. These are never stored inline. items: type: string type: array uniqueItems: false type: object traceexportconfig.SamplingPolicy: description: SamplingPolicy selects the head sampler applied before export. properties: ratio: description: Ratio is the sampling probability (0..1); required and used only when Type is ratio. maximum: 1 minimum: 0 type: number type: description: Type is one of always_on, always_off, ratio, parent_based. enum: - always_on - always_off - ratio - parent_based type: string type: object traceexportconfig.TraceExportConfigSchema: properties: content_mode: description: ContentMode selects span content redaction. Empty means metadata_only. enum: - metadata_only - full type: string egress_mode: description: EgressMode selects where spans are delivered. Empty means platform_only. enum: - platform_only - platform_and_customer_mirror - customer_only type: string enabled: description: |- Enabled is a pointer so the handler can distinguish an omitted field (nil, rejected) from an explicit false (a valid "disable export" request). type: boolean endpoint: description: |- Endpoint is the customer's OTLP/HTTP endpoint. Required when enabled. Must be https and must not point at an internal/loopback address (see Validate). maxLength: 2048 type: string headers: additionalProperties: type: string description: |- Headers holds NON-SECRET export headers a preset requires (e.g. a workspace id). Secret values must never be placed here — use HeadersSecretRef. type: object headers_secret_ref: description: |- HeadersSecretRef is a pointer to the single stored auth secret (typically an API key). It is a reference — never the secret value. Must be scoped to the caller's project (see Validate). maxLength: 512 type: string insecure_skip_verify: description: |- InsecureSkipVerify disables TLS verification of the customer endpoint. A pointer so nil (verify, the default) is distinct from an explicit opt-out; the UI surfaces enabling this as a deliberate reduction in security. type: boolean protocol: description: Protocol is the outbound OTLP protocol. v1 supports http/protobuf only. enum: - http/protobuf type: string resource_attributes: additionalProperties: type: string description: |- ResourceAttributes are extra OTLP resource attributes stamped onto every span sent to the customer endpoint (e.g. a destination-required project/model identifier). Which keys a given destination requires comes from its preset (see pkg/traceexportconfig/presets); values are always customer-supplied, since they typically name a project on the destination's own side that this platform has no way to look up. type: object sampling_policy: $ref: '#/components/schemas/traceexportconfig.SamplingPolicy' secret_header_name: description: |- SecretHeaderName is the header name the referenced secret's value is sent as (e.g. "api_key"), taken from the preset's secret_header_keys or entered by the user for a custom destination. The platform composes the outbound ": " header line, so the stored secret is always the bare value (never a pre-formatted header line). Required when HeadersSecretRef is set (see Validate). maxLength: 128 type: string required: - enabled type: object securitySchemes: BearerAuth: description: Bearer token (JWT or API key) in: header name: Authorization type: apiKey externalDocs: description: "" url: "" info: description: |- User-facing REST API for MongoDB Atlas Agent Engine. API contract negotiation Stability: preview. Send Accept: application/vnd.agent-engine-2026-09-20-preview+json to pin the API contract. Omission, application/json, or */* selects the latest published contract (currently 2026-09-20-preview). Breaking API changes require a new date and preservation of the earlier contract. Malformed or unsupported versions return 406. Errors before contract selection can retain application/json. For streams, send Accept: text/event-stream, application/vnd.agent-engine-2026-09-20-preview+json; successful responses remain SSE. Explicitly excluding SSE returns 406 even with a positive dated selector. Operations without dated response types retain their native protocols; scoped exceptions document compatibility requirements. title: Atlas Agent Engine API Gateway (External) version: "1.0" openapi: 3.1.0 paths: /api/v1/atlas/orgs: get: description: Proxies Atlas Admin API GET /orgs. Humans and API keys use the caller's delegated OAuth token; an Agent Engine ORG/PROJECT service account with an active Atlas pairing uses that service account's own credential. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasOrganizationsResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasOrganizationsResponse' description: OK "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_REQUIRED or PLATFORM_OAUTH_RESOURCE_REJECTED — delegated Atlas authorization unusable; do not replay "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_SERVICE_ACCOUNT_NOT_PAIRED — machine principal has no active pairing; FORBIDDEN — ineligible type or machine feature flag off "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR — pairing lookup failed "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_SERVICE_ACCOUNT_CREDENTIAL_UNAVAILABLE or Atlas unreachable / non-OK response "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED — platform OAuth or machine credential path not configured; SERVICE_UNAVAILABLE — delegated token refresh already in progress summary: List Atlas organizations for the authenticated principal tags: - Atlas /api/v1/atlas/projects: get: description: Lists Atlas projects available for delegated setup. Signed-in users see only projects where they are Project Owner. Organization and project service accounts with an active Atlas pairing see the projects that pairing can access. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasProjectsResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasProjectsResponse' description: OK "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_REQUIRED or PLATFORM_OAUTH_RESOURCE_REJECTED — delegated Atlas authorization unusable; do not replay "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_SERVICE_ACCOUNT_NOT_PAIRED — machine principal has no active pairing; FORBIDDEN — ineligible type or machine feature flag off "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR — pairing lookup failed "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_SERVICE_ACCOUNT_CREDENTIAL_UNAVAILABLE or Atlas unreachable / non-OK response "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED — platform OAuth or machine credential path not configured; SERVICE_UNAVAILABLE — delegated token refresh already in progress summary: List Atlas projects for the authenticated principal tags: - Atlas /api/v1/atlas/projects/{project_id}/access-list: post: description: Proxies Atlas Admin API POST /groups/{id}/accessList using a human caller's delegated token or a paired Agent Engine service account. Agent Engine API keys are not accepted. CIDRs broader than /8 (IPv4) or /32 (IPv6), including IPv4-mapped IPv6, are rejected before any Atlas call. Invalid project_id is rejected before any Atlas call. parameters: - description: Atlas project ID in: path name: project_id required: true schema: type: string requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/main.CreateAtlasAccessListRequest' description: Access-list entry to add summary: body description: Access-list entry to add required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasAccessListResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasAccessListResponse' description: Created "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "402": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PAYMENT_METHOD_REQUIRED "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PERMISSION_REQUIRED, ATLAS_SERVICE_ACCOUNT_NOT_PAIRED, or FORBIDDEN "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: NOT_FOUND "409": $ref: '#/components/responses/LegacyError409' "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: request body too large "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED or SERVICE_UNAVAILABLE when a delegated token refresh is already in progress summary: Add an Atlas project IP access-list entry tags: - Atlas /api/v1/atlas/projects/{project_id}/clusters: get: description: Proxies Atlas Admin API GET /groups/{id}/clusters and GET /groups/{id}/flexClusters using a human caller's delegated token or a paired Agent Engine service account. Agent Engine API keys are not accepted. Invalid project_id is rejected before any Atlas call. parameters: - description: Atlas project ID in: path name: project_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasClustersResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasClustersResponse' description: OK "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INVALID_ID — project_id is not a 24-hex Atlas project ID "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_REQUIRED or PLATFORM_OAUTH_RESOURCE_REJECTED "402": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PAYMENT_METHOD_REQUIRED "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PERMISSION_REQUIRED, ATLAS_SERVICE_ACCOUNT_NOT_PAIRED, or FORBIDDEN "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: NOT_FOUND "409": $ref: '#/components/responses/LegacyError409' "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Atlas unreachable / non-OK response "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED or SERVICE_UNAVAILABLE when a delegated token refresh is already in progress summary: List Atlas clusters in a project tags: - Atlas post: description: Creates a Flex cluster when tier is omitted or FLEX, or a dedicated replica set for a dedicated instance size such as M10. Uses a human caller's delegated token or a paired Agent Engine service account. Agent Engine API keys are not accepted. Invalid project_id is rejected before any Atlas call. Atlas 402 (no payment method) and 403 (insufficient Atlas permission) are mapped to distinct Agent Engine error codes. parameters: - description: Atlas project ID in: path name: project_id required: true schema: type: string requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/main.CreateAtlasFlexClusterRequest' description: Cluster to create summary: body description: Cluster to create required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasFlexClusterResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasFlexClusterResponse' description: Created "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "402": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PAYMENT_METHOD_REQUIRED "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PERMISSION_REQUIRED, ATLAS_SERVICE_ACCOUNT_NOT_PAIRED, or FORBIDDEN "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: NOT_FOUND "409": $ref: '#/components/responses/LegacyError409' "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: request body too large "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED or SERVICE_UNAVAILABLE when a delegated token refresh is already in progress summary: Create an Atlas cluster in a project tags: - Atlas /api/v1/atlas/projects/{project_id}/clusters/{cluster_name}: get: description: Looks up an Atlas Flex cluster first, then a dedicated cluster, using a human caller's delegated token or a paired Agent Engine service account. The detail response includes the connection string that Atlas omits from list responses for idle Flex clusters. Agent Engine API keys are not accepted. Invalid project_id or cluster_name is rejected before any Atlas call. parameters: - description: Atlas project ID in: path name: project_id required: true schema: type: string - description: Atlas cluster name in: path name: cluster_name required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasFlexClusterResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasFlexClusterResponse' description: OK "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INVALID_ID or INVALID_REQUEST "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_REQUIRED or PLATFORM_OAUTH_RESOURCE_REJECTED "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PERMISSION_REQUIRED, ATLAS_SERVICE_ACCOUNT_NOT_PAIRED, or FORBIDDEN "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: NOT_FOUND "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Atlas unreachable / non-OK response "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED or SERVICE_UNAVAILABLE when a delegated token refresh is already in progress summary: Get an Atlas cluster in a project tags: - Atlas /api/v1/atlas/projects/{project_id}/database-users: post: description: Proxies Atlas Admin API POST /groups/{id}/databaseUsers using a human caller's delegated token or a paired Agent Engine service account. Agent Engine API keys are not accepted. Grants readWriteAnyDatabase on admin, scoped to the selected cluster, so the platform runtime can initialize its project-scoped store and memory databases without granting access to other clusters. The password is never echoed in error responses or logs. Invalid project_id is rejected before any Atlas call. parameters: - description: Atlas project ID in: path name: project_id required: true schema: type: string requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/main.CreateAtlasDatabaseUserRequest' description: Database user to create summary: body description: Database user to create required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasDatabaseUserResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasDatabaseUserResponse' description: Created "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "402": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PAYMENT_METHOD_REQUIRED "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PERMISSION_REQUIRED, ATLAS_SERVICE_ACCOUNT_NOT_PAIRED, or FORBIDDEN "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: NOT_FOUND "409": $ref: '#/components/responses/LegacyError409' "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: request body too large "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED or SERVICE_UNAVAILABLE when a delegated token refresh is already in progress summary: Create an Atlas database user in a project tags: - Atlas /api/v1/atlas/projects/{project_id}/database-users/{username}: patch: description: Proxies Atlas Admin API PATCH /groups/{id}/databaseUsers/admin/{username} using a human caller's delegated token or a paired Agent Engine service account. Agent Engine API keys are not accepted. Rotates the password and grants readWriteAnyDatabase on admin, scoped to the selected cluster, so setup can reuse an existing workspace-named user instead of creating a colliding replacement. The password is never echoed in error responses or logs. Invalid project_id or username is rejected before any Atlas call. Requires the same Atlas Project Owner gate as create. parameters: - description: Atlas project ID in: path name: project_id required: true schema: type: string - description: Atlas database username in: path name: username required: true schema: type: string requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/main.UpdateAtlasDatabaseUserRequest' description: Database user update summary: body description: Database user update required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasDatabaseUserResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasDatabaseUserResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "402": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PAYMENT_METHOD_REQUIRED "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PERMISSION_REQUIRED, ATLAS_SERVICE_ACCOUNT_NOT_PAIRED, or FORBIDDEN "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: NOT_FOUND "409": $ref: '#/components/responses/LegacyError409' "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: request body too large "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED or SERVICE_UNAVAILABLE when a delegated token refresh is already in progress summary: Update an Atlas database user in a project tags: - Atlas /api/v1/atlas/projects/{project_id}/model-api-keys: post: description: Proxies Atlas Admin API POST /groups/{id}/aiModelApiKeys using a human caller's delegated token or a paired Agent Engine service account. Agent Engine API keys are not accepted. The one-time secret is returned to the caller and never echoed in error responses or logs. Invalid project_id is rejected before any Atlas call. parameters: - description: Atlas project ID in: path name: project_id required: true schema: type: string requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/main.CreateAtlasModelAPIKeyRequest' description: Model API key to create summary: body description: Model API key to create required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AtlasModelAPIKeyResponse' application/json: schema: $ref: '#/components/schemas/main.AtlasModelAPIKeyResponse' description: Created "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "402": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PAYMENT_METHOD_REQUIRED "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PERMISSION_REQUIRED, ATLAS_SERVICE_ACCOUNT_NOT_PAIRED, or FORBIDDEN "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: NOT_FOUND "409": $ref: '#/components/responses/LegacyError409' "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: request body too large "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: INTERNAL_ERROR "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: PLATFORM_OAUTH_NOT_CONFIGURED or SERVICE_UNAVAILABLE when a delegated token refresh is already in progress summary: Create an Atlas Voyage / AI model API key tags: - Atlas /api/v1/ecr/token: post: description: Assumes the pull-only CLI image role and returns a short-lived docker registry credential for the platform's first-party image repositories. Requires a valid platform JWT; no additional roles. Rate limited per user. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ecrTokenResponse' application/json: schema: $ref: '#/components/schemas/main.ecrTokenResponse' description: OK "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "429": $ref: '#/components/responses/LegacyError429' "502": $ref: '#/components/responses/LegacyError502' "503": $ref: '#/components/responses/LegacyError503' security: - BearerAuth: [] summary: Mint ECR pull credentials for CLI images tags: - Platform /api/v1/feature-flags: get: description: 'Returns the environment-scoped feature flags served by the gateway, evaluated server-side, as {"flags": {"": }}. Requires a session JWT; service-account and token-less clients read the identical payload from GET /api/v1/feature-flags/global. Most of the key set is not a compatibility surface: it changes as flags are added and retired, so treat an absent key as its own default. The CLI-facing key is the exception — released CLI binaries poll the key name they were built with and cannot be upgraded in lockstep with the gateway, so that key is versioned.' responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.featureFlagsResponse' application/json: schema: $ref: '#/components/schemas/main.featureFlagsResponse' description: OK "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid authentication security: - BearerAuth: [] summary: Evaluate global feature flags tags: - FeatureFlags /api/v1/feature-flags/global: get: description: 'Returns the environment-scoped feature flags served by the gateway, evaluated server-side, as {"flags": {"": }}. Unauthenticated: global flags carry no identity. Most of the key set is not a compatibility surface: it changes as flags are added and retired, so treat an absent key as its own default. The CLI-facing key is the exception — released CLI binaries poll the key name they were built with and cannot be upgraded in lockstep with the gateway, so that key is versioned.' responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.featureFlagsResponse' application/json: schema: $ref: '#/components/schemas/main.featureFlagsResponse' description: OK summary: Evaluate global feature flags (public bootstrap) tags: - FeatureFlags /api/v1/oauth/{resource}/disconnect: delete: description: Deletes the stored access/refresh token for the authenticated user against the named resource. The user must initiate a new grant to reconnect. parameters: - description: Configured resource name (e.g. atlas) in: path name: resource required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "401": $ref: '#/components/responses/LegacyError401' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Platform OAuth not configured summary: Disconnect a delegated OAuth resource tags: - Platform OAuth /api/v1/oauth/{resource}/initiate: get: description: Persists a pending grant for the authenticated user and returns the URL the UI should navigate the browser to in order to reach the resource authorization server. parameters: - description: Configured resource name (e.g. atlas) in: path name: resource required: true schema: type: string - description: Path on this gateway to redirect the user to after callback (must start with /) in: query name: next schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PlatformOAuthInitiateResponse' application/json: schema: $ref: '#/components/schemas/main.PlatformOAuthInitiateResponse' description: OK "401": $ref: '#/components/responses/LegacyError401' "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Resource not registered "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Platform OAuth not configured summary: Begin a delegated OAuth grant tags: - Platform OAuth /api/v1/oauth/callback: post: description: Exchanges an authorization code (or records an authorization-server-reported error) from a SPA-handled callback and returns the in-app navigation target. requestBody: content: application/json: schema: oneOf: - type: object - $ref: '#/components/schemas/main.PlatformOAuthCallbackRequest' description: State and AS-returned code or error summary: body description: State and AS-returned code or error required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PlatformOAuthCallbackResponse' application/json: schema: $ref: '#/components/schemas/main.PlatformOAuthCallbackResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: State does not belong to the current user "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Platform OAuth not configured summary: Complete a delegated OAuth grant tags: - Platform OAuth /api/v1/oauth/token: post: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Exchanges a service account client ID and secret for a short-lived bearer token. Only grant_type=client_credentials is supported. requestBody: content: application/json: schema: $ref: '#/components/schemas/main.oauthTokenRequest' description: OAuth token request. Prefer HTTP Basic auth for client credentials. summary: body application/x-www-form-urlencoded: schema: type: object required: [grant_type] properties: grant_type: type: string enum: [client_credentials] client_id: type: string client_secret: type: string description: OAuth token request. Prefer HTTP Basic auth for client credentials. required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/main.oauthTokenResponse' description: OK "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.oauthErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.oauthErrorResponse' description: Bad Request "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.oauthErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.oauthErrorResponse' description: Unauthorized "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.oauthErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.oauthErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.oauthErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.oauthErrorResponse' description: Internal Server Error summary: Issue a service account access token tags: - Auth /api/v1/organizations: get: description: Returns only organizations where the caller has a membership. When the Atlas grant is unusable, the last reflected orgs are still returned as read-only with atlas_reauth_required=true. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrganizationListResponse' application/json: schema: $ref: '#/components/schemas/main.OrganizationListResponse' description: OK "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List organizations tags: - Organizations post: description: Creates a new organization. The caller is automatically assigned the ORG_ADMIN role. requestBody: content: application/json: schema: $ref: '#/components/schemas/main.OrganizationCreateRequest' description: Organization to create summary: body description: Organization to create required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrganizationDTO' application/json: schema: $ref: '#/components/schemas/main.OrganizationDTO' description: Created "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Create an organization tags: - Organizations /api/v1/organizations/{id}: delete: description: Sets deleted_at timestamp instead of removing the document. Returns 204 whether the org was just soft-deleted or was already soft-deleted (re-running the idempotent cascade); returns 404 only when the org does not exist. parameters: - description: Organization ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "409": $ref: '#/components/responses/LegacyError409' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Soft-delete an organization tags: - Organizations get: description: Returns details of a specific organization by its ID. parameters: - description: Organization ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrganizationDTO' application/json: schema: $ref: '#/components/schemas/main.OrganizationDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get an organization tags: - Organizations put: description: Updates organization fields such as name or description. parameters: - description: Organization ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.OrganizationUpdateRequest' description: Fields to update summary: body description: Fields to update required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrganizationDTO' application/json: schema: $ref: '#/components/schemas/main.OrganizationDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Update an organization tags: - Organizations /api/v1/organizations/{id}/audit-events: get: description: Returns the organization activity feed (actions taken across the org's projects), newest first. Keyset/cursor paginated. parameters: - description: Organization whose audit feed to read in: path name: id required: true schema: type: string - description: Filter by project in: query name: project_id schema: type: string - description: Max events per page (default 50, max 200) in: query name: limit schema: type: integer - description: Opaque keyset cursor for the next page in: query name: cursor schema: type: string - description: Filter by action (e.g. agent.deploy) in: query name: action schema: type: string - description: 'Filter by category: access or mutation' in: query name: category schema: type: string - description: Filter by actor email in: query name: actor_email schema: type: string - description: 'Filter by outcome: success or failure' in: query name: outcome schema: type: string - description: Start of time range (RFC3339) in: query name: start_time schema: type: string - description: End of time range (RFC3339) in: query name: end_time schema: type: string - description: Include admin events (operator actions and GSA runtime events); default false hides them in: query name: show_admin_events schema: type: boolean responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AuditEventsResponse' application/json: schema: $ref: '#/components/schemas/main.AuditEventsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List audit events tags: - Audit /api/v1/organizations/{id}/invitations: get: description: Returns pending (non-expired, non-rejected) invitations for the organization. parameters: - description: Organization ID (hex ObjectID) in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgInvitationListResponse' application/json: schema: $ref: '#/components/schemas/main.OrgInvitationListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List organization invitations tags: - Organizations post: description: Creates a pending invitation for the given email to join the organization with the specified role. parameters: - description: Organization ID (hex ObjectID) in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.CreateInvitationRequest' description: Invitee email and role summary: body description: Invitee email and role required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgInvitationDTO' application/json: schema: $ref: '#/components/schemas/main.OrgInvitationDTO' description: Created "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "409": $ref: '#/components/responses/LegacyError409' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Create an organization invitation tags: - Organizations /api/v1/organizations/{id}/invitations/{invitationId}: delete: description: Deletes a pending invitation identified by hex invitation _id. parameters: - description: Organization ID (hex ObjectID) in: path name: id required: true schema: type: string - description: Invitation ID (hex ObjectID) in: path name: invitationId required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Revoke an organization invitation tags: - Organizations patch: description: Changes the role of a pending invitation identified by hex invitation _id. parameters: - description: Organization ID (hex ObjectID) in: path name: id required: true schema: type: string - description: Invitation ID (hex ObjectID) in: path name: invitationId required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.UpdateOrgUserRoleRequest' description: New role summary: body description: New role required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgInvitationDTO' application/json: schema: $ref: '#/components/schemas/main.OrgInvitationDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Update an organization invitation tags: - Organizations /api/v1/organizations/{id}/members: get: description: Returns active members (existing users) of the organization. user_id is the stable hex user ObjectID; email is for display only. parameters: - description: Organization ID (hex ObjectID) in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgMemberListResponse' application/json: schema: $ref: '#/components/schemas/main.OrgMemberListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List organization members tags: - Organizations /api/v1/organizations/{id}/members/{userId}: delete: description: Removes an active member (and their org/project roles) identified by hex user _id. parameters: - description: Organization ID (hex ObjectID) in: path name: id required: true schema: type: string - description: User ID (hex ObjectID) in: path name: userId required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Remove an organization member tags: - Organizations patch: description: Changes the org-level role for an active member identified by hex user _id. parameters: - description: Organization ID (hex ObjectID) in: path name: id required: true schema: type: string - description: User ID (hex ObjectID) in: path name: userId required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.UpdateOrgUserRoleRequest' description: New role summary: body description: New role required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgMemberDTO' application/json: schema: $ref: '#/components/schemas/main.OrgMemberDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Update an organization member's role tags: - Organizations /api/v1/organizations/{id}/policies: get: description: Lists organization-scoped platform policies. The organization is carried by the route id path parameter. parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Policy scope (if provided, must be org) in: query name: scope schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyListResponse' application/json: schema: $ref: '#/components/schemas/main.PolicyListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List organization platform policies tags: - Policies post: description: Creates an organization-scoped platform policy, which applies across every project in the organization. The organization is carried by the route id path parameter. parameters: - description: Organization ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.PolicyCreateRequest' description: Policy to create summary: body description: Policy to create required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyDTO' application/json: schema: $ref: '#/components/schemas/main.PolicyDTO' description: Created "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "409": $ref: '#/components/responses/LegacyError409' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Create organization platform policy tags: - Policies /api/v1/organizations/{id}/policies/{policy_id}: delete: description: Deletes an organization-scoped platform policy by ID. The organization is carried by the route id path parameter. parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Policy ID in: path name: policy_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": {} "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Delete organization platform policy tags: - Policies get: description: Returns a single organization-scoped platform policy by ID. The organization is carried by the route id path parameter. parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Policy ID in: path name: policy_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyDTO' application/json: schema: $ref: '#/components/schemas/main.PolicyDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get organization platform policy tags: - Policies put: description: Updates the value or enabled state of an existing organization-scoped platform policy. The organization is carried by the route id path parameter. parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Policy ID in: path name: policy_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.PolicyUpdateRequest' description: Fields to update summary: body description: Fields to update required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyDTO' application/json: schema: $ref: '#/components/schemas/main.PolicyDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Update organization platform policy tags: - Policies /api/v1/organizations/{id}/policies/preview: post: description: Returns the projects whose effective allowlist would become empty if the given organization allowlist policy is saved, so an admin is warned before tightening a tool or model allowlist to a disjoint set. Non-allowlist or disabled policies have no blast radius. parameters: - description: Organization ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.OrgPolicyPreviewRequest' description: Proposed org policy summary: body description: Proposed org policy required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgPolicyPreviewResponse' application/json: schema: $ref: '#/components/schemas/main.OrgPolicyPreviewResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Preview an organization allowlist policy's blast radius tags: - Policies /api/v1/organizations/{id}/policies/rollout: get: description: Reports whether every project in the organization is running the latest platform policy generation, separating projects the gateway has not yet materialized from projects the data plane has not yet acknowledged. parameters: - description: Organization ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyRolloutStatusResponse' application/json: schema: $ref: '#/components/schemas/main.PolicyRolloutStatusResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get organization policy rollout status tags: - Policies /api/v1/organizations/{id}/service-accounts: get: description: Lists org-scoped customer service accounts. Requires ORG_ADMIN or ORG_MEMBER (read-only). parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Page size (default 50, max 200) in: query name: limit schema: type: integer - description: Keyset cursor from a previous response's next_cursor in: query name: cursor schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountListResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List org service accounts tags: - ServiceAccounts post: description: 'Creates an org-scoped customer service account and returns its secret once. roles is required and accepts at most one non-blank name: ORG_GROUP_CREATOR or ORG_READ_ONLY. Legacy Agent Engine names (ORG_ADMIN, ORG_MEMBER) are still accepted. role_assignments echoes the stored Agent Engine role. Requires ORG_ADMIN.' parameters: - description: Organization ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.userServiceAccountCreateRequest' description: Create request summary: body description: Create request required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountSecretResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountSecretResponse' description: Created "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "409": $ref: '#/components/responses/LegacyError409' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Create org service account tags: - ServiceAccounts /api/v1/organizations/{id}/service-accounts/{client_id}: delete: description: Soft-deletes an org-scoped customer service account (sets is_active=false). Requires ORG_ADMIN. parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Deactivate org service account tags: - ServiceAccounts get: description: Returns an org-scoped customer service account by client ID. Requires ORG_ADMIN or ORG_MEMBER (read-only). parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get org service account tags: - ServiceAccounts patch: description: 'Replaces the full role set on an org-scoped customer service account. roles is required and accepts at most one non-blank name: ORG_GROUP_CREATOR or ORG_READ_ONLY. Legacy Agent Engine names (ORG_ADMIN, ORG_MEMBER) are still accepted. role_assignments echoes the stored Agent Engine role. An explicit empty array clears all roles. Requires ORG_ADMIN.' parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.serviceAccountPatchRequest' description: Patch request (roles required) summary: body description: Patch request (roles required) required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Replace org service account roles tags: - ServiceAccounts /api/v1/organizations/{id}/service-accounts/{client_id}/ip-access-list: put: description: Fully replaces the IP/CIDR Access List for an org-scoped customer service account. ip_access_list is required; explicit empty array means unrestricted. Requires ORG_ADMIN. parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.serviceAccountIPAccessListRequest' description: Full-replace IP access list (ip_access_list required) summary: body description: Full-replace IP access list (ip_access_list required) required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Replace org service account IP access list tags: - ServiceAccounts /api/v1/organizations/{id}/service-accounts/{client_id}/rotate: post: description: Mints a new secret for an org-scoped customer service account. The previous secret keeps working for up to 7 days (or until its own expiration, if sooner) so callers can roll over without downtime. Body and secret_expires_after_hours are optional; omitted values default to 2160 (90 days). Requires ORG_ADMIN. parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.serviceAccountRotateRequest' description: Optional rotate request; defaults secret expiry to 90 days when omitted summary: body description: Optional rotate request; defaults secret expiry to 90 days when omitted responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountSecretResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountSecretResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Rotate org service account secret tags: - ServiceAccounts /api/v1/organizations/{id}/service-accounts/aggregate: get: description: Lists every customer service account in the org, including project-scoped accounts with their project identity and role assignments. Requires ORG_ADMIN — plain org members use the scoped list, which excludes project accounts. parameters: - description: Organization ID in: path name: id required: true schema: type: string - description: Page size (default 50, max 200) in: query name: limit schema: type: integer - description: Keyset cursor from a previous response's next_cursor in: query name: cursor schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountListResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List all org service accounts tags: - ServiceAccounts /api/v1/organizations/{id}/support-access: delete: description: Closes this org's support-access window immediately. Requires ORG_ADMIN. Idempotent — succeeds even if no window is open. parameters: - description: Organization ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' application/json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Revoke temporary support access tags: - Organizations get: description: Returns whether a support-access window is currently open for this org and, if so, when it expires. Requires ORG_MEMBER or ORG_ADMIN. parameters: - description: Organization ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' application/json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get temporary support access status tags: - Organizations post: description: Opens a time-bound window during which platform support (PLATFORM_DATA_VIEWER) may read this org's data plane. Requires ORG_ADMIN. duration_hours is optional (omit for 24h default); when supplied it must be 1–168 (7d) or the request is rejected with 400. Re-granting replaces the current window. parameters: - description: Organization ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.OrgSupportAccessGrantRequest' description: Grant options summary: body description: Grant options responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' application/json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' description: Created "400": $ref: '#/components/responses/LegacyError400' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Grant temporary support access tags: - Organizations /api/v1/orgs/{orgId}/projects: get: description: List projects visible to the authenticated user based on their role assignments, scoped to the organization in the URL path. parameters: - description: Organization ID in: path name: orgId required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectListResponse' application/json: schema: $ref: '#/components/schemas/main.ProjectListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List projects tags: - Projects post: description: Create a new project within the organization in the URL path. Agent Engine-native organizations require ORG_ADMIN or SYSTEM_ADMIN and insert an Agent Engine project. Atlas-backed organizations create the project in Atlas using the caller's delegated Atlas grant (ORG_ADMIN on that org; Atlas ORG_OWNER or ORG_GROUP_CREATOR) and return an Agent Engine project record. Agent Engine-owned children under Atlas organizations are not created. parameters: - description: Organization ID in: path name: orgId required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.ProjectCreateRequest' description: Project to create summary: body description: Project to create required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectDTO' application/json: schema: $ref: '#/components/schemas/main.ProjectDTO' description: Created "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "402": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ATLAS_PAYMENT_METHOD_REQUIRED "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "409": $ref: '#/components/responses/LegacyError409' "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' "503": $ref: '#/components/responses/LegacyError503' security: - BearerAuth: [] summary: Create a project tags: - Projects /api/v1/orgs/{orgId}/projects/{projectId}/workspace-secrets: get: description: Aggregates workspace-scoped secret metadata across every workspace in the project. Secret values are never returned. Returns 200 with a partial-failure list when individual workspaces cannot be read. parameters: - description: Organization ID in: path name: orgId required: true schema: type: string - description: Project ID in: path name: projectId required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectWorkspaceSecretsResponse' application/json: schema: $ref: '#/components/schemas/main.ProjectWorkspaceSecretsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List project workspace secrets tags: - Secrets /api/v1/platform/agent-egress-ips: get: description: Returns the Agent Engine egress NAT CIDRs for this environment. These are the addresses agent workloads egress from when reaching non-Atlas destinations such as LLM providers or third-party SaaS — allowlist them on external services, not on Atlas projects. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.agentEgressIPsResponse' application/json: schema: $ref: '#/components/schemas/main.agentEgressIPsResponse' description: OK summary: Get Agent Engine egress IPs tags: - Platform /api/v1/platform/egress-ips: get: deprecated: true description: Deprecated — returns the Atlas-lane NAT CIDRs only. Use /api/v1/platform/agent-egress-ips for the addresses non-Atlas destinations observe. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.platformEgressIPsResponse' application/json: schema: $ref: '#/components/schemas/main.platformEgressIPsResponse' description: OK summary: Get platform egress NAT CIDRs (deprecated) tags: - Platform /api/v1/projects/{id}: delete: description: Soft-delete a project. Returns 409 PROJECT_HAS_ACTIVE_WORKSPACES if any active workspace exists in the project (the user must delete those workspaces first); otherwise tears down the per-project TenantEnvironment and cleans up role assignments / API keys / policies. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "409": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ProjectDeleteConflictResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectDeleteConflictResponse' application/json: schema: $ref: '#/components/schemas/main.ProjectDeleteConflictResponse' description: Conflict "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Delete a project tags: - Projects get: description: Retrieve a single project by its identifier. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectDTO' application/json: schema: $ref: '#/components/schemas/main.ProjectDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get project by ID tags: - Projects put: description: Update an existing project's name, description, or settings. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.ProjectUpdateRequest' description: Fields to update summary: body description: Fields to update required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectDTO' application/json: schema: $ref: '#/components/schemas/main.ProjectDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "409": $ref: '#/components/responses/LegacyError409' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Update a project tags: - Projects /api/v1/projects/{id}/agent-logs: get: description: Retrieve gzipped JSONL log batches written by the agent runtime to S3 for a workspace. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace identifier in: query name: workspace_id required: true schema: type: string - description: 'RFC3339 start time (default: 1 hour ago; range must not exceed 6 hours)' in: query name: start_time schema: type: string - description: 'RFC3339 end time (default: now; range must not exceed 6 hours)' in: query name: end_time schema: type: string - description: Max entries (default 500, max 5000) in: query name: limit schema: type: integer - description: Opaque pagination cursor from a previous response in: query name: cursor schema: type: string - description: 'Log levels to match exactly, comma- or space-separated (DEBUG, INFO, WARNING, ERROR; warn/err aliases also accepted). Breaking change from the prior minimum-severity filter: level=INFO now returns INFO only, not INFO+WARNING+ERROR.' in: query name: level schema: type: string - description: Filter by execution ID (exact match) in: query name: execution_id schema: type: string - description: Filter by session ID (exact match) in: query name: session_id schema: type: string - description: Source(s) to match exactly, comma- or space-separated (stdout, stderr, python-logging, node-logging) in: query name: source schema: type: string - description: Service(s) to match exactly, comma- or space-separated (agent-execution-runtime, tool-executor; agent/tool aliases also accepted) in: query name: service schema: type: string - description: Case-insensitive substring match on message or boot ID in: query name: search schema: type: string - description: 'Sort order: asc (default, oldest-first) or desc (newest-first)' in: query name: order schema: type: string - description: Return only the latest entries as a single page (mutually exclusive with cursor) in: query name: tail schema: type: boolean responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AgentLogsResponse' application/json: schema: $ref: '#/components/schemas/main.AgentLogsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds before retrying schema: type: string security: - BearerAuth: [] summary: Get agent runtime logs tags: - observability /api/v1/projects/{id}/agent-logs/export: get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Streams customer-visible workspace log records for one required service and up to 24 hours from at most 20 MiB of compressed source objects as normalized AgentLogEntry gzip JSON Lines. The end-to-end export timeout is 30 minutes. Processing is capped at 100 MiB of decoded input and 20 MiB of compressed response output. Records are filtered to the authorized project, workspace, and service; other interactive filters are not supported. Clients must consume and validate the gzip stream to EOF because an interrupted stream can retain HTTP 200 but have an invalid gzip trailer. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace identifier in: query name: workspace_id required: true schema: type: string - description: 'Runtime service: agent-execution-runtime or tool-executor (agent and tool aliases accepted)' in: query name: service required: true schema: type: string - description: 'RFC3339 start time (default: 1 hour ago)' in: query name: start_time schema: type: string - description: 'RFC3339 end time (default: now)' in: query name: end_time schema: type: string responses: "200": content: application/gzip: schema: format: binary type: string description: OK headers: Content-Disposition: description: Attachment filename schema: type: string "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Bad Request "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Forbidden "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Not Found "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Request Entity Too Large "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds before retrying schema: type: string "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Internal Server Error "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds before retrying schema: type: string "504": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Gateway Timeout security: - BearerAuth: [] summary: Download raw agent runtime logs tags: - observability /api/v1/projects/{id}/atlas-link: delete: description: Clears the Atlas project link from a project. Requires the project-owner role. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminPlatformProjectAtlasLinkResponse' application/json: schema: $ref: '#/components/schemas/main.AdminPlatformProjectAtlasLinkResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Remove the caller's Atlas project link tags: - Atlas get: description: Returns the project's Atlas egress link and sync status. Requires a project read role. Cluster topology (hosts/IPs) is omitted — status only. egress_sync.cluster_count is the number of clusters in the last successful stored snapshot (0 means Atlas returned none — often paused, serverless, or an empty project). parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminPlatformProjectAtlasLinkResponse' application/json: schema: $ref: '#/components/schemas/main.AdminPlatformProjectAtlasLinkResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get the caller's Atlas project link tags: - Atlas put: description: Links a project to an Atlas project for egress sync. Requires the project-owner role. When the platform enforces the Atlas access proof (the default), the request must carry an X-Atlas-Service-Account-Token header whose service account can read the Atlas project, and the Atlas project must belong to the organization's Atlas organization. The response reports sync status only — Atlas cluster topology (hosts/IPs) and raw sync errors are omitted. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Short-lived Atlas service-account access token used as a group-access proof (never the SA client secret); required when the platform enforces the Atlas access proof, which is the default in: header name: X-Atlas-Service-Account-Token schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.UpsertPlatformProjectAtlasLinkRequest' description: Atlas project link summary: body description: Atlas project link required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminPlatformProjectAtlasLinkResponse' application/json: schema: $ref: '#/components/schemas/main.AdminPlatformProjectAtlasLinkResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Link the caller's Atlas project for egress sync tags: - Atlas /api/v1/projects/{id}/builds: get: description: Lists all builds across the caller's org/project. Supports limit and offset query params. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Page size in: query name: limit schema: type: integer - description: Page offset in: query name: offset schema: type: integer responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List builds tags: - Builds /api/v1/projects/{id}/cost/dashboard: get: description: Returns aggregated cost and token usage data via the Orchestration Engine. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Time period (e.g. 7d, 30d, 90d) in: query name: period schema: type: string - description: Filter by workspace in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.CostDashboardResponse' application/json: schema: $ref: '#/components/schemas/main.CostDashboardResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get cost dashboard data tags: - Cost /api/v1/projects/{id}/deployments: get: description: Lists all deployments across the caller's org/project. Supports status, limit, and offset query params. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Comma-separated deployment statuses (queued, in_progress, succeeded, failed, rolled_back, cancelled) in: query name: status schema: type: string - description: Page size in: query name: limit schema: type: integer - description: Page offset in: query name: offset schema: type: integer responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List deployments tags: - Deployments /api/v1/projects/{id}/deployments/{deployment_id}: get: description: Proxies to ECP to retrieve a single deployment by ID with field transformations (e.g. pending -> queued). The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Deployment ID in: path name: deployment_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminDeploymentResponse' application/json: schema: $ref: '#/components/schemas/main.AdminDeploymentResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get deployment tags: - Deployments /api/v1/projects/{id}/deployments/{deployment_id}/events: get: description: Proxies to ECP to list the structured event log for a deployment. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Deployment ID in: path name: deployment_id required: true schema: type: string - description: 'Cursor: return events with sequence > after' in: query name: after schema: type: integer - description: Page size in: query name: limit schema: type: integer responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List deployment events tags: - Deployments /api/v1/projects/{id}/deployments/{deployment_id}/events/stream: get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain SSE framing; accept text/event-stream alongside the dated selector.' description: Proxies an SSE stream from ECP for real-time deployment event updates. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Deployment ID in: path name: deployment_id required: true schema: type: string - description: Resume from sequence number in: query name: after_seq schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: text/event-stream: example: |+ : connected data: {"message":"Example event payload"} schema: type: string description: SSE event stream "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Bad Request "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Forbidden "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Not Found "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Bad Gateway "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable security: - BearerAuth: [] summary: Stream deployment events tags: - Deployments /api/v1/projects/{id}/events: get: description: Fetches a session's observability events via the workspace Orchestration Engine. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Session ID in: query name: session_id schema: type: string - description: Execution ID in: query name: execution_id schema: type: string - description: Event kind filter in: query name: kind schema: type: string - description: Max events returned in: query name: limit schema: type: integer - description: Opaque cursor returned as next_cursor by the previous response in: query name: after schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "425": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Workspace orchestration engine is not ready "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get observability events tags: - Observability /api/v1/projects/{id}/events/stream: get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain SSE framing; accept text/event-stream alongside the dated selector.' description: Streams observability events from the workspace Orchestration Engine within the caller's project and workspace scope. Successful responses retain SSE framing. Gateway errors use JSON; upstream failures retain their response type. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Session ID in: query name: session_id schema: type: string - description: Execution ID in: query name: execution_id schema: type: string - description: Event kind filter in: query name: kind schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: text/event-stream: example: |+ : connected data: {"message":"Example event payload"} schema: type: string description: SSE event stream "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Bad Request "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Unauthorized "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Forbidden "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Internal Server Error "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Bad Gateway "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain plain-text error string for compatibility.' content: text/plain: schema: type: string description: No healthy workspace orchestration engine upstream; plaintext response from the mesh security: - BearerAuth: [] summary: Stream observability events tags: - Observability /api/v1/projects/{id}/execution-logs: get: description: Fetches execution logs for a session via the workspace Orchestration Engine. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Session ID in: query name: session_id required: true schema: type: string - description: RFC3339 timestamp filter in: query name: since schema: type: string - description: Opaque cursor returned as next_cursor by the previous response in: query name: after schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ExecutionLogsResponse' application/json: schema: $ref: '#/components/schemas/main.ExecutionLogsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "425": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Workspace orchestration engine is not ready "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get execution logs tags: - Observability /api/v1/projects/{id}/executions: get: description: Lists executions with optional status and session filters. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Filter by status in: query name: status schema: type: string - description: Filter by session in: query name: session_id schema: type: string - description: Max results (default 50) in: query name: limit schema: type: integer - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ExecutionsListResponse' application/json: schema: $ref: '#/components/schemas/main.ExecutionsListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "425": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Workspace orchestration engine is not ready "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List executions tags: - Executions /api/v1/projects/{id}/executions/{execution_id}: get: description: Retrieves execution status by ID. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Execution ID in: path name: execution_id required: true schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ExecutionStatusResponse' application/json: schema: $ref: '#/components/schemas/main.ExecutionStatusResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get execution status tags: - Executions /api/v1/projects/{id}/executions/{execution_id}/cancel: post: description: 'Halts an execution across all replicas and tears down its pods. Idempotent: canceling an already-terminal execution returns cancelled=false.' parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Execution ID in: path name: execution_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: Not Found "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: Bad Gateway security: - BearerAuth: [] summary: Cancel an in-progress execution tags: - Executions /api/v1/projects/{id}/executions/{execution_id}/interrupt: post: description: 'Aborts in-flight tool or LLM calls for an execution without canceling the session, so the agent continues. Send step_number to interrupt a single named call; omit the body to interrupt every call currently in flight. The response''s outcome reports exactly what happened: "aborted" (something in flight was stopped), "armed" (nothing in flight; armed for the execution''s next call, pending=true), "already_armed" (an unexpired arm already existed; the TTL was not extended), "noop_terminal" (the execution is already terminal, possibly on another replica), "in_flight_elsewhere" (the durable step record shows the call in flight but not on this OE replica; nothing was aborted here, and a backstop scoped to the stamped steps stops the call at dispatch if that dispatch completes on this replica — it can never trap a later call), or "noop" (a named step_number matched nothing in flight). Idempotent: repeated requests are safe.' parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Execution ID in: path name: execution_id required: true schema: type: string - description: Workspace ID that owns the execution, needed to route the interrupt to that workspace's OE in: query name: workspace_id schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.InterruptExecutionRequest' description: Optional single-call target summary: request description: Optional single-call target responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: Not Found "413": $ref: '#/components/responses/LegacyError413' "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: Bad Gateway security: - BearerAuth: [] summary: Interrupt an in-flight tool or LLM call tags: - Executions /api/v1/projects/{id}/executions/{execution_id}/resume: post: description: Resumes a suspended execution (e.g., after human-in-the-loop approval). The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Execution ID in: path name: execution_id required: true schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.ResumeExecutionRequest' description: Resume payload summary: body description: Resume payload required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ResumeExecutionResponse' application/json: schema: $ref: '#/components/schemas/main.ResumeExecutionResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "404": $ref: '#/components/responses/LegacyError404' "409": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.SessionConflictResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.SessionConflictResponse' application/json: schema: $ref: '#/components/schemas/main.SessionConflictResponse' description: Conflict "422": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: 'PROJECT_SECRET_INVALID: the workspace cannot start because a project secret is invalid or unreachable (fix the secret and redeploy)' "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse, main.ResumeExecutionResponse, main.StartupFailureResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: anyOf: - $ref: '#/components/schemas/main.ResumeExecutionResponse' - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: anyOf: - $ref: '#/components/schemas/main.ResumeExecutionResponse' - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' description: ResumeExecutionResponse, StartupFailureResponse for an AGENT_STARTUP_FAILED/STARTUP_FAILED startup failure, or ErrorResponse for a workflow-branch activation failure "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ResumeExecutionResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ResumeExecutionResponse' application/json: schema: $ref: '#/components/schemas/main.ResumeExecutionResponse' description: Bad Gateway "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse, main.StartupFailureResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: anyOf: - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: anyOf: - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' description: StartupFailureResponse for a POOL_EXHAUSTED/EXECUTOR_BOOT_FAILED/PLATFORM_DEPENDENCY_FAILED/POOL_UNREACHABLE startup failure; ErrorResponse otherwise. POOL_EXHAUSTED carries a Retry-After header headers: Retry-After: description: Seconds to wait before retrying (POOL_EXHAUSTED only) schema: type: string "504": $ref: '#/components/responses/LegacyError504' security: - BearerAuth: [] summary: Resume execution tags: - Executions /api/v1/projects/{id}/feature-flags: get: description: 'Returns the project-scoped feature flags served by the gateway for the path project, evaluated server-side with the project as the targeting entity, as {"flags": {"": }}. Any caller with a read role on the project may read this. The key set is not a compatibility surface: it changes as flags are added and retired, so treat an absent key as its own default.' parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.featureFlagsResponse' application/json: schema: $ref: '#/components/schemas/main.featureFlagsResponse' description: OK "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Project ID is not a valid ObjectID "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid authentication "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller is not a member of the project security: - BearerAuth: [] summary: Evaluate project feature flags tags: - FeatureFlags /api/v1/projects/{id}/guardrails: get: description: Lists OE-owned guardrail policy metadata. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Policy status in: query name: status schema: type: string - description: Policy type in: query name: type schema: type: string - description: Maximum policies returned in: query name: limit schema: type: integer responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List guardrail policies tags: - Guardrails post: description: Creates OE-owned guardrail policy metadata. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: additionalProperties: {} title: body type: object description: Guardrail policy metadata required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: Created "400": $ref: '#/components/responses/LegacyError400' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Create guardrail policy tags: - Guardrails /api/v1/projects/{id}/guardrails/{guardrail_id}: delete: description: Disables one OE-owned guardrail policy. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Guardrail ID in: path name: guardrail_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Disable guardrail policy tags: - Guardrails get: description: Gets one OE-owned guardrail policy. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Guardrail ID in: path name: guardrail_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get guardrail policy tags: - Guardrails put: description: Updates one OE-owned guardrail policy. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Guardrail ID in: path name: guardrail_id required: true schema: type: string requestBody: content: application/json: schema: additionalProperties: {} title: body type: object description: Guardrail policy patch required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Update guardrail policy tags: - Guardrails /api/v1/projects/{id}/invitations: get: description: Returns pending (non-expired, non-rejected) invitations for the project. parameters: - description: Project ID (hex ObjectID) in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectInvitationListResponse' application/json: schema: $ref: '#/components/schemas/main.ProjectInvitationListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List project invitations tags: - Projects post: description: Creates a pending invitation for the given email to join the project with the specified role. parameters: - description: Project ID (hex ObjectID) in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.CreateInvitationRequest' description: Invitee email and role summary: body description: Invitee email and role required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectInvitationDTO' application/json: schema: $ref: '#/components/schemas/main.ProjectInvitationDTO' description: Created "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "409": $ref: '#/components/responses/LegacyError409' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Create a project invitation tags: - Projects /api/v1/projects/{id}/invitations/{invitationId}: delete: description: Deletes a pending invitation identified by hex invitation _id. parameters: - description: Project ID (hex ObjectID) in: path name: id required: true schema: type: string - description: Invitation ID (hex ObjectID) in: path name: invitationId required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Revoke a project invitation tags: - Projects patch: description: Changes the role of a pending invitation identified by hex invitation _id. parameters: - description: Project ID (hex ObjectID) in: path name: id required: true schema: type: string - description: Invitation ID (hex ObjectID) in: path name: invitationId required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.UpdateProjectUserRequest' description: New role summary: body description: New role required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectInvitationDTO' application/json: schema: $ref: '#/components/schemas/main.ProjectInvitationDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Update a project invitation tags: - Projects /api/v1/projects/{id}/keys: get: description: Lists all API keys for the project. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Include inactive keys in: query name: include_inactive schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ListAPIKeysResponse' application/json: schema: $ref: '#/components/schemas/main.ListAPIKeysResponse' description: OK "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List API keys tags: - APIKeys post: deprecated: true description: API key creation is no longer supported. This endpoint is deprecated in favor of service accounts. Create a service account via POST /api/v1/projects/{id}/service-accounts or the CLI's `service-account create` command. Existing keys still work; list and revoke remain available. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.CreateAPIKeyRequest' description: Ignored. Creation is unsupported. summary: body description: Ignored. Creation is unsupported. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "410": $ref: '#/components/responses/LegacyError410' security: - BearerAuth: [] summary: Create API key (unsupported) tags: - APIKeys /api/v1/projects/{id}/keys/{key_id}: delete: description: Revokes an API key by its ID. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: API key ID in: path name: key_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: additionalProperties: {} type: object application/json: schema: additionalProperties: {} type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Revoke API key tags: - APIKeys /api/v1/projects/{id}/mcp: delete: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: 'The MCP endpoint is a stateless server: only POST is supported. DELETE (session teardown) is rejected.' parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: MCP access not enabled for this project "405": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Method not allowed security: - BearerAuth: [] summary: MCP endpoint method not allowed (DELETE) tags: - Memory get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: 'The MCP endpoint is a stateless server: only POST is supported. GET (SSE streaming) is rejected.' parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: MCP access not enabled for this project "405": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Method not allowed security: - BearerAuth: [] summary: MCP endpoint method not allowed (GET) tags: - Memory post: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Forwards an MCP (Model Context Protocol) request to the project's memory tool server. The project scope is carried by the route id path parameter and the org is derived from that project. The body is a single JSON-RPC message; JSON-RPC batch requests are rejected. The upstream response is proxied back verbatim. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: type: object text/plain: schema: title: body type: object description: JSON-RPC message (forwarded to the project runtime as-is) required: true responses: "200": content: application/json: schema: type: object description: MCP response, proxied verbatim "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Project runtime not available, or a JSON-RPC batch request "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks deployment-management permission "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: MCP access not enabled for this project "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Request body exceeds the size limit "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Project runtime unreachable "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Project runtime does not serve MCP yet security: - BearerAuth: [] summary: Invoke project memory MCP endpoint tags: - Memory /api/v1/projects/{id}/members: get: description: Returns active members of the project. user_id is the stable hex user ObjectID; email and name are for display only. parameters: - description: Project ID (hex ObjectID) in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectMemberListResponse' application/json: schema: $ref: '#/components/schemas/main.ProjectMemberListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List project members tags: - Projects /api/v1/projects/{id}/members/{userId}: delete: description: Removes an active member (and their project roles) identified by hex user _id. parameters: - description: Project ID (hex ObjectID) in: path name: id required: true schema: type: string - description: User ID (hex ObjectID) in: path name: userId required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Remove a project member tags: - Projects patch: description: Changes the project role for an active member identified by hex user _id. parameters: - description: Project ID (hex ObjectID) in: path name: id required: true schema: type: string - description: User ID (hex ObjectID) in: path name: userId required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.UpdateProjectUserRequest' description: New role summary: body description: New role required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ProjectMemberDTO' application/json: schema: $ref: '#/components/schemas/main.ProjectMemberDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Update a project member's role tags: - Projects /api/v1/projects/{id}/memory/config: get: description: Returns the current project-level memory server configuration. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.memoryConfigGetResponse' application/json: schema: $ref: '#/components/schemas/main.memoryConfigGetResponse' description: OK "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks read permission "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: No config stored for project security: - BearerAuth: [] summary: Get project memory configuration tags: - Memory put: description: Stores the project-level memory server configuration (voyage, extraction, snapshot settings). The project scope is carried by the route id path parameter and the org is derived from that project. Takes effect after the next memory-config sync. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/memoryconfig.MemoryConfigSchema' description: Typed JSON config summary: body description: Typed JSON config required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.memoryConfigPutResponse' application/json: schema: $ref: '#/components/schemas/main.memoryConfigPutResponse' description: OK "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: 'Invalid config: unknown field, wrong type, or invalid enum value' "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks deployment-management permission "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Config exceeds 64 KB security: - BearerAuth: [] summary: Set project memory configuration tags: - Memory /api/v1/projects/{id}/memory/config/sync: post: description: Triggers ECP to immediately deliver the stored memory config to the operator. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: No config stored for project "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ECP unreachable security: - BearerAuth: [] summary: Sync project memory configuration tags: - Memory /api/v1/projects/{id}/memory/context: post: description: 'Assembles conversation context from memory (default sources: episodic, semantic; include stm in enabled_sources for recent turns). The project scope is carried by the route id path parameter and the org is derived from that project. Provide a non-empty query (typically the latest user message) and the user_id whose memory to assemble.' parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.buildContextRequest' description: Context build request summary: body description: Context build request required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: Assembled context payload "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Invalid request body, missing user_id/query, or top_k outside 1-200 "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks read access to the project "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Internal error "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Memory service unreachable security: - BearerAuth: [] summary: Build conversation context tags: - Memory /api/v1/projects/{id}/memory/retrieval/context-from-sources: post: description: Assembles conversation context from an explicit, per-source-configured set of sources — each source declares its own retrieval mode (text, semantic, hybrid), metadata filter, and candidate count. Results are merged and de-duplicated across sources, optionally reranked, then formatted and budgeted like build_context. The project scope is carried by the route id path parameter and the org is derived from that project. Provide a non-empty query, the user_id whose memory to assemble, and a non-empty sources list. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.buildContext2Request' description: Per-source context build request summary: body description: Per-source context build request required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: Assembled context payload with per-source metadata "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Invalid request body or missing user_id/query/sources "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks read access to the project "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Internal error "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Memory service unreachable security: - BearerAuth: [] summary: Build conversation context from per-source specs tags: - Memory /api/v1/projects/{id}/memory/runtime: get: description: Retrieves the status of the independent memory-only project TenantEnvironment runtime. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.MemoryRuntimeStatusResponse' application/json: schema: $ref: '#/components/schemas/main.MemoryRuntimeStatusResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "412": $ref: '#/components/responses/LegacyError412' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get project memory runtime status tags: - Projects post: description: Provisions the independent memory-only project TenantEnvironment runtime and requests a best-effort project runtime secret refresh. The response does not prove ESO fetched values or pods restarted. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.MemoryRuntimeStatusResponse' application/json: schema: $ref: '#/components/schemas/main.MemoryRuntimeStatusResponse' description: Already provisioned — current status returned "202": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.MemoryRuntimeStatusResponse' application/json: schema: $ref: '#/components/schemas/main.MemoryRuntimeStatusResponse' description: Provisioning requested — poll GET to track progress "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "412": $ref: '#/components/responses/LegacyError412' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Provision project memory runtime tags: - Projects /api/v1/projects/{id}/memory/runtime/restart: post: description: Triggers a rolling restart of the memory-server Deployment so the latest memory config takes effect. Requires deployment-management permission (PROJECT_OWNER, AGENT_DEVELOPER, ORG_ADMIN, or SYSTEM_ADMIN). parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Memory server not found for project "412": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Memory server not configured for this project "501": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Memory server restart not enabled on this deployment "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Restart the memory-server for a project tags: - Memory /api/v1/projects/{id}/memory/search: post: description: Searches long-term memory by type (semantic, episodic, procedural, or taxonomic). The project scope is carried by the route id path parameter and the org is derived from that project. The type selects the retrieval endpoint; per-type field validation rejects fields the target type does not accept. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Accepted but ignored — search is read-only (no dedup) in: header name: Idempotency-Key schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.searchRequest' description: Search request with type, query, and user_id (type-specific fields allowed) summary: body description: Search request with type, query, and user_id (type-specific fields allowed) required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: Search results "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Invalid type, missing type, disallowed fields, or top_k outside 1-500 "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks read access to the project "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Internal error "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Memory service unreachable security: - BearerAuth: [] summary: Search memory tags: - Memory /api/v1/projects/{id}/memory/turns: post: description: Records a single conversation turn to long-term memory. The project scope is carried by the route id path parameter and the org is derived from that project. The caller supplies user_id (required) and an optional agent_id to identify the end user. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.recordTurnRequest' description: Turn to record summary: body description: Turn to record required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: Turn already recorded (idempotent replay of a previously-supplied idempotency_key) "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: Turn recorded "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Invalid request body "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks deployment-management permission on the project "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Internal error "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Memory service unreachable security: - BearerAuth: [] summary: Record a conversation turn tags: - Memory /api/v1/projects/{id}/node-executions: get: description: Fetches node-level execution details for a session via the workspace Orchestration Engine. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Session ID in: query name: session_id required: true schema: type: string - description: RFC3339 timestamp filter in: query name: since schema: type: string - description: Opaque cursor returned as next_cursor by the previous response in: query name: after schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.NodeExecutionsResponse' application/json: schema: $ref: '#/components/schemas/main.NodeExecutionsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "425": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Workspace orchestration engine is not ready "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get node executions tags: - Observability /api/v1/projects/{id}/policies: get: description: Lists project-scoped platform policies. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Policy scope (if provided, must be project) in: query name: scope schema: type: string - description: Project ID (if provided, must match the route project) in: query name: project_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyListResponse' application/json: schema: $ref: '#/components/schemas/main.PolicyListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List platform policies tags: - Policies post: description: Creates a project-scoped platform policy. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.PolicyCreateRequest' description: Policy to create summary: body description: Policy to create required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyDTO' application/json: schema: $ref: '#/components/schemas/main.PolicyDTO' description: Created "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "409": $ref: '#/components/responses/LegacyError409' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Create platform policy tags: - Policies /api/v1/projects/{id}/policies/{policy_id}: delete: description: Deletes a project-scoped platform policy by ID. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Policy ID in: path name: policy_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": {} "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Delete platform policy tags: - Policies get: description: Returns a single project-scoped platform policy by ID. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Policy ID in: path name: policy_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyDTO' application/json: schema: $ref: '#/components/schemas/main.PolicyDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get platform policy tags: - Policies put: description: Updates the value or enabled state of an existing project-scoped platform policy. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Policy ID in: path name: policy_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.PolicyUpdateRequest' description: Fields to update summary: body description: Fields to update required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.PolicyDTO' application/json: schema: $ref: '#/components/schemas/main.PolicyDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Update platform policy tags: - Policies /api/v1/projects/{id}/policies/effective: get: description: 'Returns each policy type resolved for the project: the merged effective value, each scope''s own value, and which scope(s) are in force. The org values are read server-side, so the caller needs only project read access.' parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.EffectivePolicyListResponse' application/json: schema: $ref: '#/components/schemas/main.EffectivePolicyListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List effective platform policies for a project tags: - Policies /api/v1/projects/{id}/promotions: get: description: Returns promotion history targeting this project, newest first across all target workspaces. parameters: - description: Target project ID in: path name: id required: true schema: type: string - description: Page size (1-100, default 20) in: query name: limit schema: default: 20 maximum: 100 minimum: 1 type: integer - description: Page offset (0-10000, default 0) in: query name: offset schema: default: 0 maximum: 10000 minimum: 0 type: integer responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminPromotionListResponse' application/json: schema: $ref: '#/components/schemas/main.AdminPromotionListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' "503": $ref: '#/components/responses/LegacyError503' security: - BearerAuth: [] summary: List promotions for a project tags: - Builds /api/v1/projects/{id}/secrets: get: description: Lists all org-scoped secrets (metadata only). Secret values are never returned. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminSecretsListResponse' application/json: schema: $ref: '#/components/schemas/main.AdminSecretsListResponse' description: OK "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List org secrets tags: - Secrets /api/v1/projects/{id}/secrets/{name}: delete: description: Validates the secret name and proxies the project-scoped delete request to ECP. Requires ownership rights for the project in the route. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Secret name (uppercase env-var style) in: path name: name required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Delete project secret tags: - Secrets put: description: 'Validates the secret name and proxies the upsert request to ECP. Secret values are never returned. The project scope is carried by the route id path parameter and the org is derived from that project. Accepts either a session JWT or a project-scoped API key, so CI/CD can seed short-lived build credentials without an interactive login; an API key must be scoped to the project named in the path. A project secret is shared by every workspace in the project, so writing one requires project-ownership rights: PROJECT_OWNER, ORG_ADMIN on Agent Engine-native projects, or SYSTEM_ADMIN. AGENT_DEVELOPER is not sufficient here — use the workspace-scoped secret endpoint for per-workspace credentials.' parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Secret name (uppercase env-var style) in: path name: name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.AdminPutSecretRequest' description: Secret value and optional description summary: body description: Secret value and optional description required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminSecretResponse' application/json: schema: $ref: '#/components/schemas/main.AdminSecretResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Create or update org secret tags: - Secrets /api/v1/projects/{id}/secrets/runtime: get: description: Reports whether the project runtime has rolled onto the currently stored secret generations. Secret sync waits on this signal before reporting success. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.SecretRuntimeStatusResponse' application/json: schema: $ref: '#/components/schemas/main.SecretRuntimeStatusResponse' description: OK "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get project secret runtime readiness tags: - Secrets /api/v1/projects/{id}/secrets/status: get: description: Returns which required org-level secrets are configured without exposing values. Available to all project members. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID — when provided, VOYAGE_API_KEY is not required if the workspace has memory disabled in: query name: app_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminSecretsStatusResponse' application/json: schema: $ref: '#/components/schemas/main.AdminSecretsStatusResponse' description: OK "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get org secrets status tags: - Secrets /api/v1/projects/{id}/secrets/sync: post: description: Forces the platform to reload project-scoped secrets and perform rolling restarts of all affected agent workloads. Active conversations may be briefly interrupted while running pods restart. Requires ownership rights for the project in the route. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "403": $ref: '#/components/responses/LegacyError403' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "501": $ref: '#/components/responses/LegacyError501' "502": $ref: '#/components/responses/LegacyError502' "503": $ref: '#/components/responses/LegacyError503' security: - BearerAuth: [] summary: Sync project secrets tags: - Secrets /api/v1/projects/{id}/service-accounts: get: description: Lists project-scoped customer service accounts. Requires PROJECT_OWNER, PROJECT_MEMBER, or AGENT_DEVELOPER (read-only); ORG_ADMIN for the owning org also passes. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Page size (default 50, max 200) in: query name: limit schema: type: integer - description: Keyset cursor from a previous response's next_cursor in: query name: cursor schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountListResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List project service accounts tags: - ServiceAccounts post: description: 'Creates a project-scoped customer service account and returns its secret once. roles accepts exactly one name: PROJECT_OWNER, PROJECT_READ_ONLY, or AGENT_DEVELOPER. PROJECT_MEMBER is still accepted. role_assignments echoes the stored Agent Engine role. Requires PROJECT_OWNER; ORG_ADMIN for the owning org also passes.' parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.userServiceAccountCreateRequest' description: Create request summary: body description: Create request required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountSecretResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountSecretResponse' description: Created "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "409": $ref: '#/components/responses/LegacyError409' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Create project service account tags: - ServiceAccounts /api/v1/projects/{id}/service-accounts/{client_id}: delete: description: Soft-deletes a project-scoped customer service account (sets is_active=false). Requires PROJECT_OWNER; ORG_ADMIN for the owning org also passes. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Deactivate project service account tags: - ServiceAccounts get: description: Returns a project-scoped customer service account by client ID. Requires PROJECT_OWNER, PROJECT_MEMBER, or AGENT_DEVELOPER (read-only); ORG_ADMIN for the owning org also passes. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get project service account tags: - ServiceAccounts patch: description: 'Replaces the full role set on a project-scoped customer service account. roles is required and accepts at most one non-blank name: PROJECT_OWNER, PROJECT_READ_ONLY, or AGENT_DEVELOPER. PROJECT_MEMBER is still accepted. role_assignments echoes the stored Agent Engine role. An explicit empty array clears all roles. Requires PROJECT_OWNER; ORG_ADMIN for the owning org also passes.' parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.serviceAccountPatchRequest' description: Patch request (roles required) summary: body description: Patch request (roles required) required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Replace project service account roles tags: - ServiceAccounts /api/v1/projects/{id}/service-accounts/{client_id}/ip-access-list: put: description: Fully replaces the IP/CIDR Access List for a project-scoped customer service account. ip_access_list is required; explicit empty array means unrestricted. Requires PROJECT_OWNER. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.serviceAccountIPAccessListRequest' description: Full-replace IP access list (ip_access_list required) summary: body description: Full-replace IP access list (ip_access_list required) required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Replace project service account IP access list tags: - ServiceAccounts /api/v1/projects/{id}/service-accounts/{client_id}/rotate: post: description: Mints a new secret for a project-scoped customer service account. The previous secret keeps working for up to 7 days (or until its own expiration, if sooner) so callers can roll over without downtime. Body and secret_expires_after_hours are optional; omitted values default to 2160 (90 days). Requires PROJECT_OWNER; ORG_ADMIN for the owning org also passes. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Service account client ID (ae_sa_id_*, legacy agp_sa_id_*) in: path name: client_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.serviceAccountRotateRequest' description: Optional rotate request; defaults secret expiry to 90 days when omitted summary: body description: Optional rotate request; defaults secret expiry to 90 days when omitted responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.serviceAccountSecretResponse' application/json: schema: $ref: '#/components/schemas/main.serviceAccountSecretResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Rotate project service account secret tags: - ServiceAccounts /api/v1/projects/{id}/sessions: get: description: Lists durable conversation sessions across every workspace in the project, with the most recently active first. These sessions contain messages and execution runs. They are separate from runtime sessions, which track reserved sandbox capacity. To get the next page, pass next_cursor from the response as cursor. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Max results (default 50, max 200) in: query name: limit schema: type: integer - description: Restrict to a single workspace in: query name: workspace_id schema: type: string - description: Filter by the session's latest execution status in: query name: status schema: type: string - description: Only sessions with activity at or after this RFC3339 time in: query name: since schema: type: string - description: Only sessions with activity before this RFC3339 time in: query name: until schema: type: string - description: Opaque paging token from a previous response's next_cursor in: query name: cursor schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.SessionsListResponse' application/json: schema: $ref: '#/components/schemas/main.SessionsListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List sessions tags: - Sessions /api/v1/projects/{id}/sessions/{session_id}/messages: get: description: Fetches all messages for a specific session via the workspace Orchestration Engine. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Session ID in: path name: session_id required: true schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.SessionMessagesResponse' application/json: schema: $ref: '#/components/schemas/main.SessionMessagesResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "422": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: 'PROJECT_SECRET_INVALID: the workspace cannot start because a project secret is invalid or unreachable (fix the secret and redeploy)' "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get session messages tags: - Sessions /api/v1/projects/{id}/sessions/{session_id}/runs: get: description: Returns the session's runs oldest-first, each with its steps in order. A step carries its kind, start offset within the run, duration, token count, status, and step_number. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Session ID in: path name: session_id required: true schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.SessionRunsResponse' application/json: schema: $ref: '#/components/schemas/main.SessionRunsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get a session's runs tags: - Observability /api/v1/projects/{id}/trace-export/config: get: description: Returns the current project-level OTLP trace-export settings. The auth secret is returned by reference only (headers_secret_ref); the raw value is never returned. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.traceExportConfigGetResponse' application/json: schema: $ref: '#/components/schemas/main.traceExportConfigGetResponse' description: OK "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks read permission "404": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: No config stored for project security: - BearerAuth: [] summary: Get project trace-export configuration tags: - Observability put: description: Stores the project-level OTLP trace-export settings. The auth secret is referenced only (headers_secret_ref); the raw value is never accepted or stored. Bumps the generation counter and marks the config pending for downstream delivery. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/traceexportconfig.TraceExportConfigSchema' description: Typed JSON config summary: body description: Typed JSON config required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.traceExportConfigPutResponse' application/json: schema: $ref: '#/components/schemas/main.traceExportConfigPutResponse' description: OK "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Invalid config "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks project-owner permission "413": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Config exceeds 16 KB security: - BearerAuth: [] summary: Set project trace-export configuration tags: - Observability /api/v1/projects/{id}/trace-export/presets: get: description: Returns the vendor-blind preset catalog that drives the settings UI (endpoint template, protocol, required non-secret header fields, docs link). Contains no secrets. The project scope is carried by the route id path parameter. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.traceExportPresetsResponse' application/json: schema: $ref: '#/components/schemas/main.traceExportPresetsResponse' description: OK "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Missing or invalid credentials "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Caller lacks read permission security: - BearerAuth: [] summary: List trace-export vendor presets tags: - Observability /api/v1/projects/{id}/traces: get: description: Fetches distributed traces for a session via the workspace Orchestration Engine. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Session ID in: query name: session_id required: true schema: type: string - description: Workspace ID for workspace resolution in: query name: workspace_id schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.TracesResponse' application/json: schema: $ref: '#/components/schemas/main.TracesResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "425": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Workspace orchestration engine is not ready "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get traces tags: - Observability /api/v1/projects/{id}/workspace-statuses: get: description: 'Returns the ECP-owned active/paused status for every workspace in the project identified by the route id path parameter. Always fetches live from ECP (concurrent identical requests are deduplicated, not cached across requests). Soft-fails: if ECP is unreachable, or if a page beyond the first fails, returns the last known-good response (up to 10 minutes old) if one exists; otherwise returns 200 with an empty list (or, for a partial multi-page failure with no fallback available, the partial results collected so far).' parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.WorkspaceStatusListResponse' application/json: schema: $ref: '#/components/schemas/main.WorkspaceStatusListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' security: - BearerAuth: [] summary: List workspace statuses tags: - Workspaces /api/v1/projects/{id}/workspaces: get: description: Returns all workspaces in the project identified by the route id path parameter. Requires a valid Bearer token and project role. parameters: - description: Project ID in: path name: id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.WorkspaceListResponse' application/json: schema: $ref: '#/components/schemas/main.WorkspaceListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List workspaces tags: - Workspaces post: description: Proxies to ECP to create a new workspace (app). The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string requestBody: content: text/plain: schema: title: body type: object description: Workspace creation request (forwarded to ECP as-is) required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: Created "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "409": $ref: '#/components/responses/LegacyError409' "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Create workspace tags: - Workspaces /api/v1/projects/{id}/workspaces/{workspace_id}: delete: description: Soft-deletes a workspace and triggers ECP app teardown. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Delete workspace tags: - Workspaces get: description: Retrieves a single workspace by its ID. The project scope is carried by the route id path parameter. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.WorkspaceDTO' application/json: schema: $ref: '#/components/schemas/main.WorkspaceDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get workspace tags: - Workspaces patch: description: Partially updates a workspace. The project scope is carried by the route id path parameter. Field-only patches return 204; a status-only patch (pause/resume) is mutually exclusive with other fields and returns 200 with ECP's app body (including any `warnings`). parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.WorkspaceUpdateRequest' description: Fields to update summary: body description: Fields to update required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.WorkspaceStatusPatchResponse' application/json: schema: $ref: '#/components/schemas/main.WorkspaceStatusPatchResponse' description: Returned for status-only patches; proxied from ECP. "204": description: Returned for field-update patches. "400": $ref: '#/components/responses/LegacyError400' "404": $ref: '#/components/responses/LegacyError404' "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "502": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: ECP transport or pause-teardown failure. "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Update workspace tags: - Workspaces /api/v1/projects/{id}/workspaces/{workspace_id}/builds: get: description: Proxies to ECP to list builds for a workspace with cursor-based pagination and optional status filter. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Opaque pagination cursor in: query name: cursor schema: type: string - description: Page size (1-100, default 20) in: query name: limit schema: type: integer - description: Build status filter in: query name: status schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminListBuildsResponse' application/json: schema: $ref: '#/components/schemas/main.AdminListBuildsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List workspace builds tags: - Builds post: description: Proxies to ECP to trigger a new build for a workspace. Request and response are forwarded as-is. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string requestBody: content: text/plain: schema: title: body type: object description: Optional build parameters (forwarded to ECP as-is) responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: Created "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Trigger workspace build tags: - Builds /api/v1/projects/{id}/workspaces/{workspace_id}/builds/{build_id}: delete: description: Proxies to ECP to delete a build record. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Build ID in: path name: build_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Delete build tags: - Builds get: description: Proxies to ECP to retrieve build status. Used by the CLI to poll until a terminal state is reached. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Build ID in: path name: build_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get build tags: - Builds /api/v1/projects/{id}/workspaces/{workspace_id}/builds/{build_id}/cancel: post: description: Proxies to ECP to cancel an in-progress build. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Build ID in: path name: build_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Cancel build tags: - Builds /api/v1/projects/{id}/workspaces/{workspace_id}/builds/{build_id}/logs: get: description: Proxies to ECP to retrieve build logs. Forwards query parameters for pagination and time-range filtering. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Build ID in: path name: build_id required: true schema: type: string - description: Pagination token for next page of logs in: query name: next_token schema: type: string - description: Start time filter in: query name: start_time schema: type: string - description: End time filter in: query name: end_time schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "499": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Client closed the request before the gateway responded "502": $ref: '#/components/responses/LegacyError502' "504": $ref: '#/components/responses/LegacyError504' security: - BearerAuth: [] summary: Get build logs tags: - Builds /api/v1/projects/{id}/workspaces/{workspace_id}/builds/{build_id}/start: post: description: Proxies to ECP to start a build after archive upload. ECP verifies the S3 archive before starting CodeBuild. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Build ID in: path name: build_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Start build tags: - Builds /api/v1/projects/{id}/workspaces/{workspace_id}/builds/archive-init: post: description: Proxies to ECP to initialize an archive-based build. Returns a presigned S3 upload URL and build_id. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string requestBody: content: text/plain: schema: title: body type: object description: Archive init request (forwarded to ECP as-is) responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "409": $ref: '#/components/responses/LegacyError409' "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Initialize archive build tags: - Builds /api/v1/projects/{id}/workspaces/{workspace_id}/deployments: get: description: Proxies to ECP to list deployments for a workspace with cursor-based pagination and optional status filter. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Opaque pagination cursor in: query name: cursor schema: type: string - description: Page size (1-100, default 20) in: query name: limit schema: type: integer - description: Deployment status filter (queued, in_progress, cleaning_up, succeeded, failed, rolled_back, cancelled) in: query name: status schema: type: string - description: 'Return the deployments that shipped in this release: its own artifact deploys plus the non-release deploys that landed before its cut. Rollbacks are excluded.' in: query name: shipped_in_release schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminListDeploymentsResponse' application/json: schema: $ref: '#/components/schemas/main.AdminListDeploymentsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List workspace deployments tags: - Deployments post: description: Proxies to ECP to create a new deployment for a workspace. Translates ECP status (pending -> queued). The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.AdminCreateDeploymentRequest' description: Optional deployment parameters summary: body description: Optional deployment parameters responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "202": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminCreateDeploymentResponse' application/json: schema: $ref: '#/components/schemas/main.AdminCreateDeploymentResponse' description: Accepted "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "409": $ref: '#/components/responses/LegacyError409' "412": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Project runtime not provisioned (PROJECT_RUNTIME_NOT_READY, proxied from ECP) "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Create deployment tags: - Deployments /api/v1/projects/{id}/workspaces/{workspace_id}/deployments/{deployment_id}/cancel: post: description: Proxies to ECP to cancel an in-progress deployment. Returns 400 if the deployment is already in a terminal state. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Deployment ID in: path name: deployment_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Cancel deployment tags: - Deployments /api/v1/projects/{id}/workspaces/{workspace_id}/deployments/current: get: description: Proxies to ECP to get the current active deployment for a workspace. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get current deployment tags: - Deployments /api/v1/projects/{id}/workspaces/{workspace_id}/deployments/versions: get: description: 'Proxies to ECP for one entry per release version: how many deployments that release shipped, when its code froze, and which deployment was the release event. A release is a boundary in the timeline, so a deployment belongs to the release that was open when it landed, or to the release whose artifact it deploys.' parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminListDeploymentVersionsResponse' application/json: schema: $ref: '#/components/schemas/main.AdminListDeploymentVersionsResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List workspace deployment release versions tags: - Deployments /api/v1/projects/{id}/workspaces/{workspace_id}/health: get: description: Proxies to ECP to retrieve live component health for a workspace. The project scope is carried by the route id path parameter. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Get workspace health tags: - Workspaces /api/v1/projects/{id}/workspaces/{workspace_id}/invoke: post: description: 'Invokes a workspace agent and returns its response. To continue a session, send the X-Session-ID value returned by the previous response. If you omit the header, the gateway starts a new session and returns its ID in the response header. The body session_id field does not continue a session. The body can include extra top-level fields. The gateway forwards every field except these reserved fields: message, session_id, user_id, and resume_map. resume_map continues a suspended turn. For a session with no history, resume_map becomes the initial agent input. Requires a valid Bearer token.' parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Session ID returned by a previous response. Send it to continue that session. Valid IDs match ^[A-Za-z0-9_-]{1,128}$. If omitted, the gateway starts a new session. Body session_id does not continue a session in: header name: X-Session-ID schema: type: string - description: Classify a newly created session as a testing session; existing classification is unchanged in: header name: X-Agent-Engine-Test-Session schema: type: boolean - description: Per-request wait budget in seconds for this blocking invoke (1-120). Defaults to the deployment's INVOKE_WORKSPACE_TIMEOUT_SECONDS when omitted in: header name: X-Agent-Engine-Invoke-Timeout-Seconds schema: maximum: 120 minimum: 1 type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/main.InvokeWorkspaceRequest' description: Invoke request summary: body description: Invoke request required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.InvokeWorkspaceResponse' application/json: schema: $ref: '#/components/schemas/main.InvokeWorkspaceResponse' description: OK headers: X-Session-ID: description: Session ID matching ^[A-Za-z0-9_-]{1,128}$. Send this value in the next request to continue the session schema: type: string "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "409": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.SessionConflictResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.SessionConflictResponse' application/json: schema: $ref: '#/components/schemas/main.SessionConflictResponse' description: Conflict "422": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: 'PROJECT_SECRET_INVALID: the workspace cannot start because a project secret is invalid or unreachable (fix the secret and redeploy)' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse, main.InvokeWorkspaceResponse, main.StartupFailureResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: anyOf: - $ref: '#/components/schemas/main.InvokeWorkspaceResponse' - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: anyOf: - $ref: '#/components/schemas/main.InvokeWorkspaceResponse' - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' description: InvokeWorkspaceResponse when the agent's own execution settled with an error (Success:false with an execution_id/status); StartupFailureResponse for an AGENT_STARTUP_FAILED/STARTUP_FAILED startup failure; ErrorResponse otherwise "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse, main.StartupFailureResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: anyOf: - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: anyOf: - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' description: StartupFailureResponse for a POOL_EXHAUSTED/EXECUTOR_BOOT_FAILED/PLATFORM_DEPENDENCY_FAILED/POOL_UNREACHABLE startup failure; ErrorResponse otherwise. POOL_EXHAUSTED carries a Retry-After header headers: Retry-After: description: Seconds to wait before retrying (POOL_EXHAUSTED only) schema: type: string "504": $ref: '#/components/responses/LegacyError504' security: - BearerAuth: [] summary: Invoke workspace tags: - Workspaces /api/v1/projects/{id}/workspaces/{workspace_id}/invokeStream: post: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain SSE framing; accept text/event-stream alongside the dated selector.' description: 'Invokes a workspace agent and streams its response as Server-Sent Events. To continue a session, send the X-Session-ID value returned by the previous response. If you omit the header, the gateway starts a new session and returns its ID in the response header. The body session_id field does not continue a session. The body can include extra top-level fields. The gateway forwards every field except these reserved fields: message, session_id, user_id, and resume_map. resume_map continues a suspended turn. For a session with no history, resume_map becomes the initial agent input. Requires a valid Bearer token.' parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Session ID returned by a previous response. Send it to continue that session. Valid IDs match ^[A-Za-z0-9_-]{1,128}$. If omitted, the gateway starts a new session. Body session_id does not continue a session in: header name: X-Session-ID schema: type: string - description: Classify a newly created session as a testing session; existing classification is unchanged in: header name: X-Agent-Engine-Test-Session schema: type: boolean requestBody: content: application/json: schema: $ref: '#/components/schemas/main.InvokeWorkspaceRequest' description: Invoke request summary: body description: Invoke request required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: text/event-stream: example: |+ : connected data: {"message":"Example event payload"} schema: type: string description: SSE stream. A pre-header failure (before the first frame) renders as one of the JSON error bodies below; a mid-stream failure instead renders as a terminal SSE chunk carrying the same code/error, plus source/component/sandbox/boot_id in a metadata object for a startup-failure envelope headers: X-Session-ID: description: Session ID matching ^[A-Za-z0-9_-]{1,128}$. Send this value in the next request to continue the session schema: type: string "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "409": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.SessionConflictResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.SessionConflictResponse' application/json: schema: $ref: '#/components/schemas/main.SessionConflictResponse' description: Conflict "422": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: 'PROJECT_SECRET_INVALID: the workspace cannot start because a project secret is invalid or unreachable (fix the secret and redeploy); mid-stream it appears as a terminal SSE chunk carrying code=PROJECT_SECRET_INVALID' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse, main.StartupFailureResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: anyOf: - $ref: '#/components/schemas/main.ErrorResponse' - $ref: '#/components/schemas/main.StartupFailureResponse' application/json: schema: anyOf: - $ref: '#/components/schemas/main.ErrorResponse' - $ref: '#/components/schemas/main.StartupFailureResponse' description: ErrorResponse, or StartupFailureResponse for an AGENT_STARTUP_FAILED/STARTUP_FAILED startup failure "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse, main.StartupFailureResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: anyOf: - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: anyOf: - $ref: '#/components/schemas/main.StartupFailureResponse' - $ref: '#/components/schemas/main.ErrorResponse' description: StartupFailureResponse for a POOL_EXHAUSTED/EXECUTOR_BOOT_FAILED/PLATFORM_DEPENDENCY_FAILED/POOL_UNREACHABLE startup failure; ErrorResponse otherwise. POOL_EXHAUSTED carries a Retry-After header headers: Retry-After: description: Seconds to wait before retrying (POOL_EXHAUSTED only) schema: type: string "504": $ref: '#/components/responses/LegacyError504' security: - BearerAuth: [] summary: Invoke workspace (streaming) tags: - Workspaces /api/v1/projects/{id}/workspaces/{workspace_id}/promotions: get: description: Returns promotion history targeting this workspace, newest first. parameters: - description: Target project ID in: path name: id required: true schema: type: string - description: Target workspace ID in: path name: workspace_id required: true schema: type: string - description: Page size (1-100, default 20) in: query name: limit schema: default: 20 maximum: 100 minimum: 1 type: integer - description: Page offset (0-10000, default 0) in: query name: offset schema: default: 0 maximum: 10000 minimum: 0 type: integer responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminPromotionListResponse' application/json: schema: $ref: '#/components/schemas/main.AdminPromotionListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' "503": $ref: '#/components/responses/LegacyError503' security: - BearerAuth: [] summary: List promotions for a workspace tags: - Builds post: description: Copies an existing succeeded build's image from another workspace in the same org into this workspace and creates a deployable build. Requires deployment management on both the source build's project and the target project; force additionally requires the target project owner role. Processing is asynchronous — poll the returned promotion until ready or failed. parameters: - description: Target project ID in: path name: id required: true schema: type: string - description: Target workspace ID in: path name: workspace_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.AdminCreatePromotionRequest' description: Promotion request summary: request description: Promotion request required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "202": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminPromotionResponse' application/json: schema: $ref: '#/components/schemas/main.AdminPromotionResponse' description: Accepted "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "409": $ref: '#/components/responses/LegacyError409' "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying after a capacity rejection schema: type: string security: - BearerAuth: [] summary: Promote a build into this workspace tags: - Builds /api/v1/projects/{id}/workspaces/{workspace_id}/promotions/{promotion_id}: get: description: Returns a single promotion scoped to this workspace. parameters: - description: Target project ID in: path name: id required: true schema: type: string - description: Target workspace ID in: path name: workspace_id required: true schema: type: string - description: Promotion ID in: path name: promotion_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.AdminPromotionResponse' application/json: schema: $ref: '#/components/schemas/main.AdminPromotionResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' "503": $ref: '#/components/responses/LegacyError503' security: - BearerAuth: [] summary: Get a promotion tags: - Builds /api/v1/projects/{id}/workspaces/{workspace_id}/rollback: post: description: Proxies to ECP to rollback to the previous deployment. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.AdminRollbackRequest' description: Rollback target deployment summary: body description: Rollback target deployment required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "409": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: 'Conflict proxied from ECP: DEPLOY_IN_PROGRESS, APP_OPERATION_IN_PROGRESS, APP_DELETING, or PROJECT_UPDATE_IN_PROGRESS' "412": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Project runtime not provisioned (PROJECT_RUNTIME_NOT_READY, proxied from ECP) "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Rollback deployment tags: - Deployments /api/v1/projects/{id}/workspaces/{workspace_id}/runtime-sessions: get: description: Lists runtime sessions that reserve agent or tool sandbox capacity for the workspace, including sessions still releasing capacity. Runtime sessions are separate from durable conversation sessions, which store conversation history. Status is active while the session holds capacity and stopping while release is in progress. last_activity_at and scheduled_release_at follow the workspace idle timeout. scheduled_release_at is omitted while a component is still releasing. is_test_session identifies Playground and CLI test sessions. The list is empty when no runtime capacity is reserved. An accepted stop or unconfirmed release remains visible after a restart and from every runtime replica. Concurrent list requests share one executor status refresh. A successful refresh is reused for about one second. If the two-second refresh fails or returns incomplete data, the endpoint uses the current replica's cached snapshot. last_activity_at uses the serving replica's clock. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.RuntimeSessionsListResponse' application/json: schema: $ref: '#/components/schemas/main.RuntimeSessionsListResponse' description: OK "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "425": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Workspace orchestration engine is not ready "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List runtime sessions tags: - Sessions /api/v1/projects/{id}/workspaces/{workspace_id}/runtime-sessions/{session_id}/stop: post: description: Starts releasing the agent and tool sandbox capacity reserved for a runtime session, then returns immediately with status stopping. This does not delete the conversation session, messages, or execution records. Repeating the request while release is in progress returns the same accepted state without starting another release. Returns 404 when the workspace has no reserved or releasing runtime for the session. Retry-After suggests when to list runtime sessions again. Release continues in the background. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Runtime session ID in: path name: session_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "202": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.RuntimeSessionStopResponse' application/json: schema: $ref: '#/components/schemas/main.RuntimeSessionStopResponse' description: Accepted headers: Retry-After: description: Seconds to wait before polling the runtime-session list schema: type: string "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "425": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Workspace orchestration engine is not ready "500": $ref: '#/components/responses/LegacyError500' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: Stop a runtime session tags: - Sessions /api/v1/projects/{id}/workspaces/{workspace_id}/secrets: get: description: Lists all secrets scoped to a workspace (metadata only). Secret values are never returned. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "502": $ref: '#/components/responses/LegacyError502' security: - BearerAuth: [] summary: List workspace secrets tags: - Secrets /api/v1/projects/{id}/workspaces/{workspace_id}/secrets/{name}: delete: description: Validates the secret name and proxies the delete request to ECP scoped to a workspace. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Secret name (uppercase env-var style) in: path name: name required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Delete workspace secret tags: - Secrets put: description: Validates the secret name and proxies the upsert request to ECP scoped to a workspace. The project scope is carried by the route id path parameter and the org is derived from that project. Accepts either a session JWT or a project-scoped API key, so CI/CD can seed short-lived build credentials without an interactive login; an API key must be scoped to the project named in the path. The caller needs deployment-management rights on that project (PROJECT_OWNER, AGENT_DEVELOPER, ORG_ADMIN on Agent Engine-native projects, or SYSTEM_ADMIN). parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string - description: Secret name (uppercase env-var style) in: path name: name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.AdminPutSecretRequest' description: Secret value and optional description summary: body description: Secret value and optional description required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "413": $ref: '#/components/responses/LegacyError413' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Create or update workspace secret tags: - Secrets /api/v1/projects/{id}/workspaces/{workspace_id}/secrets/sync: post: description: Proxies to ECP to trigger a secrets sync for a specific workspace, forcing the operator to reload secrets and restart the workspace's running pods. Active conversations may be briefly interrupted while the restart completes. The project scope is carried by the route id path parameter and the org is derived from that project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: type: object application/json: schema: type: object description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "429": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Too Many Requests headers: Retry-After: description: Seconds to wait before retrying schema: type: string "502": $ref: '#/components/responses/LegacyError502' "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.ErrorResponse' application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable headers: Retry-After: description: Seconds to wait before retrying schema: type: string security: - BearerAuth: [] summary: Sync workspace secrets tags: - Secrets /api/v1/projects/{id}/workspaces/{workspace_id}/support-access: delete: description: Closes this workspace's support-access window immediately. Requires PROJECT_OWNER on the path project or ORG_ADMIN of that project's organization. Idempotent — succeeds even if no window is open. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' application/json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Revoke temporary workspace support access tags: - Workspaces get: description: Returns whether a support-access window is currently open for this workspace and, if so, when it expires. Requires a project read role on the path project. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' application/json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' description: OK "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get temporary workspace support access status tags: - Workspaces post: description: Opens a time-bound window during which platform support (PLATFORM_DATA_VIEWER) may read this workspace's data plane. Requires PROJECT_OWNER on the path project or ORG_ADMIN of that project's organization. duration_hours is optional (omit for 24h default); when supplied it must be 1–168 (7d) or the request is rejected with 400. Re-granting replaces the current window. Available on Atlas-managed projects. parameters: - description: Project ID in: path name: id required: true schema: type: string - description: Workspace ID in: path name: workspace_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/main.OrgSupportAccessGrantRequest' description: Grant options summary: body description: Grant options responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "201": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' application/json: schema: $ref: '#/components/schemas/main.OrgSupportAccessStatusDTO' description: Created "400": $ref: '#/components/responses/LegacyError400' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Grant temporary workspace support access tags: - Workspaces /api/v1/users/me: get: description: Returns the current user's profile information from the database. Requires a valid Bearer token. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.UserInfo' application/json: schema: $ref: '#/components/schemas/main.UserInfo' description: OK "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Get current user tags: - Users /api/v1/users/me/invitations: get: description: Returns the authenticated user's pending, non-expired invitations. Invitations whose organization or project has been deleted are omitted. responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "200": content: application/vnd.agent-engine-2026-09-20-preview+json: schema: $ref: '#/components/schemas/main.UserInvitationListResponse' application/json: schema: $ref: '#/components/schemas/main.UserInvitationListResponse' description: OK "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: List my pending invitations tags: - Invitations /api/v1/users/me/invitations/{invitationId}/accept: post: description: Accepts a pending invitation, granting the user the associated org or project role. parameters: - description: Invitation ID in: path name: invitationId required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "403": $ref: '#/components/responses/LegacyError403' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Accept an invitation tags: - Invitations /api/v1/users/me/invitations/{invitationId}/decline: post: description: Declines a pending invitation by marking it as rejected. parameters: - description: Invitation ID in: path name: invitationId required: true schema: type: string responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "404": $ref: '#/components/responses/LegacyError404' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Decline an invitation tags: - Invitations /api/v1/users/me/last-selected-org: put: description: Persists the authenticated user's most recently selected organization. The org must be one the user belongs to. requestBody: content: application/json: schema: $ref: '#/components/schemas/main.updateLastSelectedOrgRequest' description: Org to remember summary: body description: Org to remember required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Set current user's last selected org tags: - Users /api/v1/users/me/last-selected-project: put: description: Persists the authenticated user's most recently selected project. The project must belong to one of the user's organizations. requestBody: content: application/json: schema: $ref: '#/components/schemas/main.updateLastSelectedProjectRequest' description: Project to remember summary: body description: Project to remember required: true responses: "406": $ref: '#/components/responses/ApiVersionNotAcceptable' "204": description: No Content "400": $ref: '#/components/responses/LegacyError400' "401": $ref: '#/components/responses/LegacyError401' "500": $ref: '#/components/responses/LegacyError500' security: - BearerAuth: [] summary: Set current user's last selected project tags: - Users /auth/logout: post: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Revokes the server-side login session bound to the bearer token, immediately invalidating its access and refresh tokens, and clears the UI session gate cookie. responses: "204": description: Session revoked "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Unauthorized "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Service Unavailable security: - BearerAuth: [] summary: Logout tags: - Auth /auth/oauth/callback: get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Public browser callback for PLATFORM_OAUTH_REDIRECT_URI. Validates state and browser-binding cookie, exchanges the code, reconciles Atlas roles when applicable, and either resumes Agent Engine OIDC login or redirects to the in-app next path. parameters: - description: Opaque pending-grant state in: query name: state required: true schema: type: string - description: Authorization code in: query name: code schema: type: string - description: Authorization-server error in: query name: error schema: type: string - description: Authorization-server error description in: query name: error_description schema: type: string responses: "302": content: application/json: schema: type: string description: Redirect to Agent Engine OTC callback, in-app next, or coarse error destination "409": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain plain-text error string for compatibility.' content: application/json: schema: type: string description: Authorization or login finalization already in progress "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain plain-text error string for compatibility.' content: application/json: schema: type: string description: Platform OAuth not configured summary: Complete hosted platform OAuth callback tags: - Platform OAuth /auth/oidc/callback: get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Handles the identity provider callback. Validates the CSRF state, exchanges the authorization code for tokens via PKCE, finds or creates a user, and redirects to the UI with a one-time code. parameters: - description: Authorization code in: query name: code required: true schema: type: string - description: CSRF state in: query name: state required: true schema: type: string responses: "302": content: application/json: schema: type: string description: Redirect to UI with one-time code summary: OIDC callback endpoint tags: - Auth /auth/oidc/exchange: post: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: The frontend or CLI calls this endpoint with a one-time code received from the OIDC callback to obtain local JWT access and refresh tokens. requestBody: content: application/json: schema: $ref: '#/components/schemas/main.OIDCTokenExchangeRequest' description: One-time code and optional PKCE verifier summary: body description: One-time code and optional PKCE verifier required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/main.OIDCTokenExchangeResponse' description: JWT tokens "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Bad Request "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Unauthorized "503": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Service Unavailable summary: Exchange one-time code for JWT tokens tags: - Auth /auth/oidc/start: get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Validates the auth_start transaction ID, generates PKCE/nonce/state, stores them in a cookie, and redirects to the identity provider. parameters: - description: Transaction ID (hash of auth_start state) in: query name: tx required: true schema: type: string responses: "302": content: application/json: schema: type: string description: Redirect to identity provider "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Bad Request "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Internal Server Error summary: Start OIDC login flow tags: - Auth /auth/signup: post: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Creates a password user in local/dev only, requiring an invitation code before applying the code-matched pending invitation. requestBody: content: application/json: schema: $ref: '#/components/schemas/main.SignupRequest' description: Signup request summary: body description: Signup request required: true responses: "201": content: application/json: schema: $ref: '#/components/schemas/main.UserDTO' description: Created "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Bad Request "403": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Forbidden "409": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Conflict "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain main.ErrorResponse for compatibility.' content: application/json: schema: $ref: '#/components/schemas/main.ErrorResponse' description: Internal Server Error summary: Sign up with pending invitation tags: - Auth /auth/start: get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Starts login through the account app when configured, or directly through the identity provider for local deployments. parameters: - description: Post-login redirect URI in: query name: post_login_uri schema: type: string - description: Relative UI route to restore after Account login in: query name: "n" schema: type: string - description: Forward signed-out state to the account app in: query name: signedOut schema: type: string responses: "302": content: application/json: schema: type: string description: Redirect to account app or identity provider "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Bad Request "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Internal Server Error summary: Start authentication flow tags: - Auth /auth/token: post: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Authenticates a user with username and password and returns a JWT token pair. requestBody: content: application/x-www-form-urlencoded: schema: oneOf: - title: username type: string - title: password type: string description: Username | Password required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/main.TokenPair' description: OK "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Bad Request "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Unauthorized "500": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Internal Server Error summary: Login tags: - Auth /auth/token/next: post: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Exchanges a refresh token for a new JWT token pair. requestBody: content: text/plain: schema: title: body type: object description: Refresh token request required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/main.TokenPair' description: OK "400": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Bad Request "401": x-xgen-IPA-exception: xgen-IPA-114-error-responses-refer-to-api-error: 'IPA-114-must-return-apierror: retain object with unconstrained properties for compatibility.' content: application/json: schema: additionalProperties: {} type: object description: Unauthorized summary: Refresh token tags: - Auth /health: get: x-xgen-IPA-exception: xgen-IPA-103: 'IPA-103-must-support-versioned-json: retain this operation''s native protocol and contract.' description: Returns the process-level health status of the API Gateway. responses: "200": content: application/json: schema: $ref: '#/components/schemas/main.HealthResponse' description: OK summary: Health check tags: - Health security: - BearerAuth: [] servers: - url: https://agentengine.mongodb.com/