{ "openapi": "3.1.0", "info": { "title": "Introspection API — Control Plane", "description": "Public control API for runtimes, recipes, projects, connectors, endpoints, channels, and evaluation settings.", "version": "0.1.0" }, "paths": { "/v1/integrations/{integration_id}/channels": { "get": { "tags": [ "integrations" ], "summary": "Get Integration Channels", "description": "List channels visible to the Slack app for project channel selection.", "operationId": "get_integration_channels_v1_integrations__integration_id__channels_get", "parameters": [ { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Integration Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackChannelsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/projects": { "get": { "tags": [ "projects" ], "summary": "List Projects", "description": "List projects in the user's organization.", "operationId": "list_projects_v1_projects_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by project slug or id.", "title": "Project" }, "description": "Filter by project slug or id." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_ProjectResponse_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "projects" ], "summary": "Create Project", "description": "Create a new project in the user's organization.", "operationId": "create_project_v1_projects_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/projects/{project}": { "get": { "tags": [ "projects" ], "summary": "Get Project", "description": "Get a project by slug or UUID id.", "operationId": "get_project_v1_projects__project__get", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "projects" ], "summary": "Update Project", "description": "Update a project's mutable fields.", "operationId": "update_project_v1_projects__project__patch", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "projects" ], "summary": "Delete Project", "description": "Soft delete a project and its project-scoped resources.", "operationId": "delete_project_v1_projects__project__delete", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/api-keys": { "get": { "tags": [ "api-keys" ], "summary": "List Api Keys", "description": "List API keys for a project.", "operationId": "list_api_keys_v1_api_keys_get", "parameters": [ { "name": "expiring", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include keys with a future expiry (a key lifetime or a grace-period revoke). Defaults to false, so only permanent keys are returned. Expired keys are never returned.", "default": false, "title": "Expiring" }, "description": "Include keys with a future expiry (a key lifetime or a grace-period revoke). Defaults to false, so only permanent keys are returned. Expired keys are never returned." }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "api-keys" ], "summary": "Create Api Key", "description": "Create a new API key for SDK/CLI access.\n\nThe full API key is returned exactly once, on creation. Only its SHA-256\nhash is stored, so it can never be retrieved again — the user must save it.\nAn optional ``expires_at`` sets a key lifetime (the UI offers 1h / 1d / 7d or\nunlimited). The JWT is resolved on first use via the on-demand CP lookup path.", "operationId": "create_api_key_v1_api_keys_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/api-keys/{api_key_id}": { "patch": { "tags": [ "api-keys" ], "summary": "Update Api Key", "description": "Update mutable API key metadata.\n\nThe key's environment, secret material, and lifetime are creation-time\nchoices and are intentionally immutable.", "operationId": "update_api_key_v1_api_keys__api_key_id__patch", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Api Key Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKey" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "api-keys" ], "summary": "Delete Api Key", "description": "Revoke an API key, immediately or after a grace period.\n\nWith no ``expires_in`` (or ``0``) the key is soft-deleted and its DP cache\nentry invalidated, so it stops working at once. With ``expires_in`` > 0 the\nkey is scheduled to expire that many seconds from now and keeps working until\nthen; lookups exclude it once it expires.", "operationId": "delete_api_key_v1_api_keys__api_key_id__delete", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Api Key Id" } }, { "name": "expires_in", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Grace period in seconds before the key stops working. Omit or pass 0 to revoke immediately. When > 0 the key keeps working until then, after which it is treated as expired (the UI offers 1h / 1d / 7d).", "title": "Expires In" }, "description": "Grace period in seconds before the key stops working. Omit or pass 0 to revoke immediately. When > 0 the key keeps working until then, after which it is treated as expired (the UI offers 1h / 1d / 7d)." }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/api-keys/{api_key_id}/acknowledge": { "post": { "tags": [ "api-keys" ], "summary": "Acknowledge Api Key", "description": "Acknowledge that the user has saved the API key.\n\nRecords that the creation-time key display has been acknowledged. The full\nkey is never stored, so it cannot be retrieved after this point.", "operationId": "acknowledge_api_key_v1_api_keys__api_key_id__acknowledge_post", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Api Key Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/repositories/pull-requests": { "post": { "tags": [ "repositories" ], "summary": "Get Pull Request Metadata", "operationId": "get_pull_request_metadata_v1_repositories_pull_requests_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullRequestMetadataRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "title": "Response Get Pull Request Metadata V1 Repositories Pull Requests Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/repositories": { "get": { "tags": [ "repositories" ], "summary": "List Repositories", "description": "List repositories linked to a project.", "operationId": "list_repositories_v1_repositories_get", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RepositoryResponse" }, "title": "Response List Repositories V1 Repositories Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "repositories" ], "summary": "Add Repository", "description": "Link a GitHub repository to a project, or create one hosted on its data plane.", "operationId": "add_repository_v1_repositories_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AddRepositoryRequest" }, { "$ref": "#/components/schemas/HostedRepositoryCreate" } ], "title": "Data" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryResponse" } } } }, "409": { "description": "`repository_already_registered` — this project already has a live registration for the same URL. Nothing was changed." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/repositories/{repository_id}": { "get": { "tags": [ "repositories" ], "summary": "Get Repository", "operationId": "get_repository_v1_repositories__repository_id__get", "parameters": [ { "name": "repository_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Repository Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "repositories" ], "summary": "Update Repository", "operationId": "update_repository_v1_repositories__repository_id__patch", "parameters": [ { "name": "repository_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Repository Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "repositories" ], "summary": "Delete Repository", "description": "Unregister a repository from a project.\n\nRefused while a recipe is still pinned in it: the soft delete would leave\nthat recipe pointing at a tombstone and hard-fail every cold task launch,\nand `ON DELETE RESTRICT` cannot see a soft delete.", "operationId": "delete_repository_v1_repositories__repository_id__delete", "parameters": [ { "name": "repository_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Repository Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "204": { "description": "Successful Response" }, "409": { "description": "`repository_in_use` — a recipe is still pinned in this repository; the body names them. Removing it would leave those recipes pointing at a tombstone, and a task cannot spawn against a deleted recipe." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/recipes": { "get": { "tags": [ "recipes" ], "summary": "List Recipes", "description": "List recipes for a project, cursor-paginated.", "operationId": "list_recipes_v1_recipes_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by Recipe name (groups versions across commits).", "title": "Name" }, "description": "Filter by Recipe name (groups versions across commits)." }, { "name": "repository_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by source Repository.", "title": "Repository Id" }, "description": "Filter by source Repository." }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Recipe_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "recipes" ], "summary": "Create Recipe", "description": "Create a new Recipe row pinning a specific commit.\n\nIdempotent on the immutable pin: re-posting an identical\n(repository, name, commit, sub_path) returns the existing Recipe with\n``200 OK`` instead of ``201 Created``, so callers never pre-check.", "operationId": "create_recipe_v1_recipes_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recipe" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/recipes/{recipe_id}": { "get": { "tags": [ "recipes" ], "summary": "Get Recipe", "operationId": "get_recipe_v1_recipes__recipe_id__get", "parameters": [ { "name": "recipe_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Recipe Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recipe" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "recipes" ], "summary": "Update Recipe", "description": "Update presentation or retry failed validation. The git pin is immutable.", "operationId": "update_recipe_v1_recipes__recipe_id__patch", "parameters": [ { "name": "recipe_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Recipe Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recipe" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "recipes" ], "summary": "Delete Recipe", "description": "Soft-delete a Recipe. Not gated on Runtimes: this is a soft delete, so the\n`ON DELETE RESTRICT` FK never fires and Runtimes keep referencing the row.\nWhat does change is that a task can no longer spawn against it — `/run`\nreturns 404 — so take dependent Runtimes out of service first as hygiene\n(`DELETE /v1/runtimes/{id}`, or `PATCH {\"yanked\": true}` to withdraw them\nfrom staging/production resolution; there is no archive verb on runtimes).", "operationId": "delete_recipe_v1_recipes__recipe_id__delete", "parameters": [ { "name": "recipe_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Recipe Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/runtimes": { "get": { "tags": [ "runtimes" ], "summary": "List Runtimes", "description": "List runtimes for a project, cursor-paginated.", "operationId": "list_runtimes_v1_runtimes_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "runtime", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by runtime slug or runtime group id.", "title": "Runtime" }, "description": "Filter by runtime slug or runtime group id." }, { "name": "recipe_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by Recipe.", "title": "Recipe Id" }, "description": "Filter by Recipe." }, { "name": "environment", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ], "description": "Filter by the environment selecting this row.", "title": "Environment" }, "description": "Filter by the environment selecting this row." }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Runtime_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "runtimes" ], "summary": "Create Runtime", "description": "Create a new Runtime row.", "operationId": "create_runtime_v1_runtimes_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Runtime" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/runtimes/{runtime_id}": { "get": { "tags": [ "runtimes" ], "summary": "Get Runtime", "operationId": "get_runtime_v1_runtimes__runtime_id__get", "parameters": [ { "name": "runtime_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Runtime Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Runtime" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "runtimes" ], "summary": "Update Runtime", "description": "Update presentation / config fields and environment assignment.\n\nThe `recipe_id` is immutable — create a new Runtime row to pin a different\nRecipe. Lanes are steered through `environment_ref` (per-key merge): a branch\nor PR ref advances the lane onto the newest build of that ref, a commit sha\npins the lane to this row, and `null` unpins it back to tracking the default\nbranch. Both `staging` and `production` are pinnable (production pins are the\nrollback path); an unpinned production still auto-advances on main pushes.", "operationId": "update_runtime_v1_runtimes__runtime_id__patch", "parameters": [ { "name": "runtime_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Runtime Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Runtime" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "runtimes" ], "summary": "Delete Runtime", "description": "Soft-delete a stable Runtime and all of its concrete versions.\n\nThe path still accepts a concrete version id for compatibility, but that\nversion resolves the stable Runtime group. Durable DP offboarding is\naccepted before the CP transaction tombstones the group and its\noperational resources.", "operationId": "delete_runtime_v1_runtimes__runtime_id__delete", "parameters": [ { "name": "runtime_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Runtime Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/runtimes/{runtime_id}/run": { "post": { "tags": [ "runtimes" ], "summary": "Open Runtime Runner", "description": "Open a runner for normal traffic to this Runtime's group.\n\nThe authenticated credential's environment is authoritative. CP routes an identified caller\nthrough the group's running experiment when eligible; otherwise it serves\nthe Runtime active for that environment. The resolved Runtime and optional\nexperiment attribution are pinned into the returned RunnerSpec.\n\nSee `docs/design/sdk-api.md` \"The two CP /run endpoints\".", "operationId": "open_runtime_runner_v1_runtimes__runtime_id__run_post", "parameters": [ { "name": "runtime_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Runtime Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional defence-in-depth project slug or id. If omitted, resolved from the runtime row.", "title": "Project" }, "description": "Optional defence-in-depth project slug or id. If omitted, resolved from the runtime row." }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Deprecated alias for `project` (slug or id)", "title": "Project Id" }, "description": "Deprecated alias for `project` (slug or id)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerSpec" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/experiments": { "get": { "tags": [ "experiments" ], "summary": "List Experiments", "description": "List experiments for a project, cursor-paginated.", "operationId": "list_experiments_v1_experiments_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "runtime", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by Runtime slug or group id.", "title": "Runtime" }, "description": "Filter by Runtime slug or group id." }, { "name": "environment", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ], "description": "Filter by Environment.", "title": "Environment" }, "description": "Filter by Environment." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentStatus" }, { "type": "null" } ], "description": "Filter by lifecycle status.", "title": "Status" }, "description": "Filter by lifecycle status." }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Experiment_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "experiments" ], "summary": "Create Experiment", "description": "Create a new Experiment in `draft` status.\n\nThe arms must all reference Runtime rows in this project sharing\nthe experiment's runtime group. Routing is not live until `start` is\ncalled.", "operationId": "create_experiment_v1_experiments_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/experiments/{experiment_id}": { "get": { "tags": [ "experiments" ], "summary": "Get Experiment", "operationId": "get_experiment_v1_experiments__experiment_id__get", "parameters": [ { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Experiment Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "experiments" ], "summary": "Update Experiment", "description": "Update mutable fields. Drafts are fully editable. Once running, the\nrouting/statistical fields (name/scoring_interval/hash_key_fields/\ngoal_json/sample_rate) are frozen so sticky assignment, the sampled\npopulation, and accumulated evidence stay coherent. Only the description\nstays editable while running. Terminal experiments are immutable.", "operationId": "update_experiment_v1_experiments__experiment_id__patch", "parameters": [ { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Experiment Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "experiments" ], "summary": "Delete Experiment", "description": "Soft-delete. Refuses to delete a running experiment — end or\ncancel first to stop routing, then delete.", "operationId": "delete_experiment_v1_experiments__experiment_id__delete", "parameters": [ { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Experiment Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/experiments/{experiment_id}/run": { "post": { "tags": [ "experiments" ], "summary": "Open Experiment Runner", "description": "Open a runner against this experiment — CP picks the arm for the\ncaller's identity and returns a `RunnerSpec` carrying the resolved\nruntime_id in the JWT claims.\n\nThe beta_sample bandit requires `identity` (the consistent-hash subject).\n\nErrors: 409 if the experiment is not `running`; 503 if no arm is\npickable (no positive weights, or identity missing for a hash-based\nstrategy). See `docs/design/sdk-api.md` \"The two CP /run endpoints\".", "operationId": "open_experiment_runner_v1_experiments__experiment_id__run_post", "parameters": [ { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Experiment Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerSpec" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/experiments/{experiment_id}/start": { "post": { "tags": [ "experiments" ], "summary": "Start Experiment", "description": "Transition draft → running. Activates routing for this experiment's\nruntime group and Environment. The partial unique index enforces\nat-most-one-running per (project_id, runtime_group_id, environment): starting\na draft while the slot is taken returns 409 (end the running one first).", "operationId": "start_experiment_v1_experiments__experiment_id__start_post", "parameters": [ { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Experiment Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/experiments/{experiment_id}/end": { "post": { "tags": [ "experiments" ], "summary": "End Experiment", "description": "Transition running → ended.\n\nThis records that the operator is done collecting experiment evidence.\nProduction does not change here; the user ships the winner by manually\nmerging the winning recipe PR.", "operationId": "end_experiment_v1_experiments__experiment_id__end_post", "parameters": [ { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Experiment Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/experiments/{experiment_id}/cancel": { "post": { "tags": [ "experiments" ], "summary": "Cancel Experiment", "description": "Transition running → cancelled. Traffic returns to normal production\nresolution (the group's environment-activated runtime).", "operationId": "cancel_experiment_v1_experiments__experiment_id__cancel_post", "parameters": [ { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Experiment Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/judges": { "get": { "tags": [ "judges" ], "summary": "List Judges", "description": "List judges for a project, cursor-paginated.\n\nJudges cannot be created here — author a `judges/.yaml` in the\nrecipe repository (schema: `introspection_recipe_check.judge_definition_schema()`)\nand it syncs into this registry when a runtime versions that commit.\nEach runtime group owns its own rows. A row's `id` is the stable `judge_id`\nreferenced by experiments and emitted by runtime judgements. The lineage\nfields describe the last synced source; the exact executed definition hash\nis derived from the selected runtime's pinned recipe and emitted with each\njudgement. The API never serves the YAML itself.", "operationId": "list_judges_v1_judges_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "runtime_group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Judge_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/judges/{judge_id}": { "get": { "tags": [ "judges" ], "summary": "Get Judge", "operationId": "get_judge_v1_judges__judge_id__get", "parameters": [ { "name": "judge_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Judge Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Judge" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "judges" ], "summary": "Update Judge", "description": "Update a judge's OPERATIONAL state (enabled / sample_rate). The definition\nis git-owned and not editable here — this is the runtime off-switch + the\nproduction sampling dial.", "operationId": "update_judge_v1_judges__judge_id__patch", "parameters": [ { "name": "judge_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Judge Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgeOperationalUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Judge" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/endpoints": { "get": { "tags": [ "endpoints" ], "summary": "List Endpoints", "description": "List endpoints for a project, cursor-paginated.\n\nHeader configuration is returned to the authenticated operator with\ncredential references unresolved. Credential secret values are never\nincluded.", "operationId": "list_endpoints_v1_endpoints_get", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/EndpointKind" }, { "type": "null" } ], "description": "Optional filter — 'llm', 'api', or 'mcp'.", "title": "Kind" }, "description": "Optional filter — 'llm', 'api', or 'mcp'." }, { "name": "runtime_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Optional filter — return only endpoints pinned to this runtime.", "title": "Runtime Id" }, "description": "Optional filter — return only endpoints pinned to this runtime." }, { "name": "runtime", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional filter — return only endpoints pinned to this Runtime, by slug or group id.", "title": "Runtime" }, "description": "Optional filter — return only endpoints pinned to this Runtime, by slug or group id." }, { "name": "environment", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ], "description": "Optional filter — return only endpoints pinned to this environment.", "title": "Environment" }, "description": "Optional filter — return only endpoints pinned to this environment." }, { "name": "mcp_server_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Optional filter over metadata.mcp_server_id.", "title": "Mcp Server Id" }, "description": "Optional filter over metadata.mcp_server_id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_EndpointResponse_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "endpoints" ], "summary": "Upsert Endpoint", "description": "Upsert by (org, project, host, runtime scope, environment).\n\nReturns 201 Created on insert, 200 OK on update. When `verify_path`\nis set on the request body, a pre-flight GET to\n`{base_url ?? https://{host}}{verify_path}` must return 2xx or the\nrequest fails with 422 (endpoint_verify_failed).", "operationId": "upsert_endpoint_v1_endpoints_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/endpoints/{endpoint_id}": { "get": { "tags": [ "endpoints" ], "summary": "Get Endpoint", "operationId": "get_endpoint_v1_endpoints__endpoint_id__get", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Endpoint Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "endpoints" ], "summary": "Update Endpoint", "description": "Partial PATCH. Verifies if the merged row has `verify_path`\nset AND any of (headers, host, base_url, verify_path) changed.\nRenames or scope changes alone skip verify.", "operationId": "update_endpoint_v1_endpoints__endpoint_id__patch", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Endpoint Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "endpoints" ], "summary": "Delete Endpoint", "description": "Soft-delete by id. The partial unique index excludes\ndeleted_at IS NOT NULL rows, so a new endpoint at the same\n(project, host, runtime scope, environment) can be created afterwards.", "operationId": "delete_endpoint_v1_endpoints__endpoint_id__delete", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Endpoint Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/channels": { "get": { "tags": [ "channels" ], "summary": "List Channels", "description": "List the channels bound to this project.", "operationId": "list_channels_v1_channels_get", "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by provider slug", "title": "Provider" }, "description": "Filter by provider slug" }, { "name": "integration_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by provider install", "title": "Integration Id" }, "description": "Filter by provider install" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_ChannelResponse_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "channels" ], "summary": "Create Channel", "description": "Bind a channel to this project.\n\nThe named integration must be the caller's own org's — read through the\norg-scoped repository, so a binding can never point at another tenant's\ninstall even though the id is caller-supplied.", "operationId": "create_channel_v1_channels_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/channels/{binding_id}": { "get": { "tags": [ "channels" ], "summary": "Get Channel", "description": "Read one binding.", "operationId": "get_channel_v1_channels__binding_id__get", "parameters": [ { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Binding Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "channels" ], "summary": "Update Channel", "description": "Update a binding.", "operationId": "update_channel_v1_channels__binding_id__patch", "parameters": [ { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Binding Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "channels" ], "summary": "Delete Channel", "description": "Unbind a channel. The bot stays in it and stops answering.", "operationId": "delete_channel_v1_channels__binding_id__delete", "parameters": [ { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Binding Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/connectors/discover-oauth": { "post": { "tags": [ "connectors" ], "summary": "Discover Connector Oauth", "description": "Resolve provider metadata before asking an operator for client credentials.\n\n``issuer`` may be the authorization server or the MCP server it protects.", "operationId": "discover_connector_oauth_v1_connectors_discover_oauth_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorOAuthDiscoveryRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorOAuthDiscoveryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/connectors/{connector_id}/apps": { "get": { "tags": [ "connectors" ], "summary": "List Connector Apps", "description": "Search the provider app catalogue for a connector (currently Pipedream).", "operationId": "list_connector_apps_v1_connectors__connector_id__apps_get", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connector Id" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100, "default": "", "title": "Q" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/connectors": { "get": { "tags": [ "connectors" ], "summary": "List Connectors", "description": "List connectors for the project.", "operationId": "list_connectors_v1_connectors_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_ConnectorResponse_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "connectors" ], "summary": "Create Connector", "description": "Create a connector (owner/member context required).", "operationId": "create_connector_v1_connectors_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/connectors/{connector_id}": { "get": { "tags": [ "connectors" ], "summary": "Get Connector", "description": "Get a connector by id.", "operationId": "get_connector_v1_connectors__connector_id__get", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connector Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "connectors" ], "summary": "Update Connector", "description": "Update a connector (partial).", "operationId": "update_connector_v1_connectors__connector_id__patch", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connector Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "connectors" ], "summary": "Delete Connector Route", "description": "Soft-delete a connector and revoke its connections.", "operationId": "delete_connector_route_v1_connectors__connector_id__delete", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connector Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/connectors/{connector_id}/connections": { "get": { "tags": [ "connectors" ], "summary": "List Connections", "description": "List a connector's connections (no token material).", "operationId": "list_connections_v1_connectors__connector_id__connections_get", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connector Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_ConnectionResponse_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "connectors" ], "summary": "Create Connection", "description": "Registered-mode create: store an already-obtained token.", "operationId": "create_connection_v1_connectors__connector_id__connections_post", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connector Id" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/connectors/{connector_id}/connections/{connection_id}": { "get": { "tags": [ "connectors" ], "summary": "Get Connection", "description": "Get a connection by id (no token material).", "operationId": "get_connection_v1_connectors__connector_id__connections__connection_id__get", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connector Id" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connection Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "connectors" ], "summary": "Revoke Connection", "description": "Revoke a connection and the approvals recorded against it.", "operationId": "revoke_connection_v1_connectors__connector_id__connections__connection_id__delete", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connector Id" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Connection Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/oauth/connections/token": { "post": { "tags": [ "oauth" ], "summary": "Mint Connection Token", "description": "Resolve the subject's connection and return its provider token, or — for\n``person_authorized`` — a pending-authorization response.", "operationId": "mint_connection_token_v1_oauth_connections_token_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerTokenRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerTokenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/oauth/connections/authorize": { "post": { "tags": [ "oauth" ], "summary": "Start Connect", "description": "Connect step 1 — mint the provider consent URL for a connector.\n\nPOST, not GET: this writes a single-use `state` into Redis with a TTL, so\ntwo calls return two different URLs and no response may be cached. It sits\nwith the other minting routes in this family (`/token`, `/exchange`,\n`/refresh`), while the browser-facing `/callback` stays a GET.", "operationId": "start_connect_v1_oauth_connections_authorize_post", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Scope to this project by slug or id. Inferred from API key when omitted.", "title": "Project" }, "description": "Scope to this project by slug or id. Inferred from API key when omitted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectAuthorizeRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectAuthorizeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "APIKey": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Human-readable key name" }, "environment": { "$ref": "#/components/schemas/Environment", "description": "Runtime environment selected by this key.", "default": "production" }, "allow": { "items": { "$ref": "#/components/schemas/ApiKeyCapability" }, "type": "array", "title": "Allow", "description": "Capability bundles granted to this key. Each value expands into one or more concrete scope strings via introspection_common.assemble_api_key_scope." }, "scope": { "type": "string", "title": "Scope", "description": "Assembled permission scope (space-separated) — derived from `allow` at create time. Authoritative for enforcement (JWT claim, has_scope).", "default": "*" }, "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Member Id" }, "key_prefix": { "type": "string", "title": "Key Prefix", "description": "Key prefix (e.g., 'intro_staging_abc12345')" }, "key_suffix": { "type": "string", "title": "Key Suffix", "description": "Last SECRET_SUFFIX_LEN chars for display" }, "redacted_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redacted Key", "description": "Redacted key for display" }, "status": { "$ref": "#/components/schemas/APIKeyStatus", "default": "active" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" }, "acknowledged_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Acknowledged At" }, "key_display": { "type": "string", "title": "Key Display", "description": "Masked display version: uses redacted_key if available, else computes.", "readOnly": true }, "prefix": { "type": "string", "title": "Prefix", "description": "Alias for key_prefix, expected by the frontend.", "readOnly": true } }, "type": "object", "required": [ "org_id", "project_id", "key_prefix", "key_suffix", "key_display", "prefix" ], "title": "APIKey", "description": "Full API key schema with hashed lookup material and optional encrypted stored key." }, "APIKeyResponse": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Human-readable key name" }, "environment": { "$ref": "#/components/schemas/Environment", "description": "Runtime environment selected by this key.", "default": "production" }, "allow": { "items": { "$ref": "#/components/schemas/ApiKeyCapability" }, "type": "array", "title": "Allow", "description": "Capability bundles granted to this key. Each value expands into one or more concrete scope strings via introspection_common.assemble_api_key_scope." }, "scope": { "type": "string", "title": "Scope", "description": "Assembled permission scope (space-separated) — derived from `allow` at create time. Authoritative for enforcement (JWT claim, has_scope).", "default": "*" }, "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Member Id" }, "key_prefix": { "type": "string", "title": "Key Prefix", "description": "Key prefix (e.g., 'intro_staging_abc12345')" }, "key_suffix": { "type": "string", "title": "Key Suffix", "description": "Last SECRET_SUFFIX_LEN chars for display" }, "redacted_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redacted Key", "description": "Redacted key for display" }, "status": { "$ref": "#/components/schemas/APIKeyStatus", "default": "active" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" }, "acknowledged_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Acknowledged At" }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key", "description": "Full API key, returned only by create" }, "key_display": { "type": "string", "title": "Key Display", "description": "Masked display version: uses redacted_key if available, else computes.", "readOnly": true }, "prefix": { "type": "string", "title": "Prefix", "description": "Alias for key_prefix, expected by the frontend.", "readOnly": true } }, "type": "object", "required": [ "org_id", "project_id", "key_prefix", "key_suffix", "key_display", "prefix" ], "title": "APIKeyResponse", "description": "API key response — includes the full key only on creation.\n\nThe full key is shown exactly once, at creation time; it is never stored,\nso there is no way to retrieve it afterwards." }, "APIKeyStatus": { "type": "string", "enum": [ "active", "rotating", "expired", "revoked" ], "title": "APIKeyStatus", "description": "API key status." }, "AddRepositoryRequest": { "properties": { "provider": { "type": "string", "const": "github", "title": "Provider", "default": "github" }, "integration_id": { "type": "string", "format": "uuid", "title": "Integration Id", "description": "GitHub integration to use" }, "url": { "type": "string", "title": "Url", "description": "Repository URL" }, "name": { "type": "string", "title": "Name", "description": "Repository name" } }, "type": "object", "required": [ "integration_id", "url", "name" ], "title": "AddRepositoryRequest", "description": "Request to link a GitHub repository to a project." }, "ApiKeyCapability": { "type": "string", "enum": [ "runtimes", "evals" ], "title": "ApiKeyCapability", "description": "Capability bundle grants on an API key.\n\nMaps 1:1 to the PG enum `api_key_capability`. Each value expands\ninto one or more concrete scope strings via\n``introspection_common.assemble_api_key_scope`` — see\n``API_KEY_CAPABILITY_SCOPES`` in ``introspection_common/scopes.py``.\n\nFuture PRs may add values with a matching migration and scope bundle." }, "ApiKeyCreateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "environment": { "$ref": "#/components/schemas/Environment", "default": "production" }, "allow": { "items": { "$ref": "#/components/schemas/ApiKeyCapability" }, "type": "array", "title": "Allow", "description": "Capability bundles to grant." }, "member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Member Id", "description": "Fixed Agent member this key acts as. Defaults to the organization's Member Agent. The selected member's role determines data visibility." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional key lifetime. When set, the key stops working after this time; when null the key never expires. The UI offers 1h / 1d / 7d or unlimited." } }, "type": "object", "title": "ApiKeyCreateRequest", "description": "Request body for creating an API key.\n\nThe ``allow`` list expands into the persisted ``scope`` string via\n``introspection_common.assemble_api_key_scope``. Every new key\nadditionally carries ``telemetry:write`` from ``API_KEY_BASE_SCOPES``;\neach capability expands its bundle from ``API_KEY_CAPABILITY_SCOPES``.\n\nThe legacy per-capability booleans are gone — UI sends a single\n``allow`` list.\n\nSee apps/controlplane-api/docs/api-key-scopes.md." }, "ApiKeyListResponse": { "properties": { "api_keys": { "items": { "$ref": "#/components/schemas/APIKey" }, "type": "array", "title": "Api Keys" } }, "type": "object", "required": [ "api_keys" ], "title": "ApiKeyListResponse", "description": "List of API keys (without full key values)." }, "ApiKeyUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "allow": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ApiKeyCapability" }, "type": "array" }, { "type": "null" } ], "title": "Allow", "description": "Capability bundles to grant. Omit to leave unchanged." }, "member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Member Id", "description": "Rebind the key to a fixed Agent member. Omit to leave unchanged." } }, "type": "object", "title": "ApiKeyUpdateRequest", "description": "Request body for editing mutable API key metadata.\n\nEnvironment, key material, and lifetime are immutable after creation." }, "BrokerTokenRequest": { "properties": { "connector_id": { "type": "string", "format": "uuid", "title": "Connector Id" }, "connection_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Connection Id", "description": "Exact connection to use. When omitted, the platform resolves the connection from the authenticated subject." }, "subject": { "$ref": "#/components/schemas/ConnectionSubjectType", "default": "app" }, "action": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Action", "description": "The proposed action, e.g. 'booking.reserve' — the mission label shown to the human" }, "requested_permissions": { "$ref": "#/components/schemas/MissionConstraints", "description": "The deterministic envelope the agent proposes (host/resource/limits/window/payload_binding)" } }, "type": "object", "required": [ "connector_id" ], "title": "BrokerTokenRequest", "description": "``getToken`` broker request. The agent names the connector, the subject\n*kind*, and the action it proposes — never the member/person identity, which\nthe platform binds (§7).\n\n``action`` and ``requested_permissions`` are what the agent *asks for*; they\nbecome the mission envelope the human sees and decides on. They can only ever\nnarrow what the org's connector already allows — the agent cannot widen its\nown grant by asking for more, because the Person Server's decision is checked\nagainst this envelope (§3) and the org connector is the ceiling (§19.1)." }, "BrokerTokenResponse": { "properties": { "token": { "type": "string", "title": "Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" } }, "type": "object", "required": [ "token" ], "title": "BrokerTokenResponse", "description": "Broker token handed to the ``connections`` SDK." }, "CallerContext": { "properties": { "ip": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Ip", "description": "Caller IPv4/IPv6 address." }, "user_agent": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "User Agent", "description": "HTTP User-Agent string." }, "locale": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ], "title": "Locale", "description": "BCP-47 locale (e.g. 'en-US')." }, "library": { "anyOf": [ { "$ref": "#/components/schemas/CallerLibrary" }, { "type": "null" } ] }, "page": { "anyOf": [ { "$ref": "#/components/schemas/CallerPage" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "CallerContext", "description": "Caller environment payload — segment.io-style observability data.\n\nCarried alongside `identity` on `RunRequest` and persisted on the\nsession so it survives across all tasks the runner spawns. The Data\nPlane stamps it onto each task as `metadata.caller`, which reaches the\nsandbox in `INTROSPECTION_TASK_METADATA_JSON` along with the rest of\nthe task metadata. Echoed back on `RunnerSpec.runtime_context.caller`\nfor SDK display.\n\nDistinct from `identity` — this payload is **not** consulted by\nrouting. `hash_key_fields` only walks `identity.user_id` /\n`anonymous_id` / `conversation_id`. Mixing routing inputs into the\nobservability payload would be a privacy + stability footgun\n(e.g. routing on IP).\n\nWell-known fields are typed below; any additional fields the caller\npasses (segment.io conventions: `app`, `device`, `os`, `campaign`,\n`network`, `screen`, `timezone`, `traits`, or custom keys) ride\nalong verbatim via `extra=\"allow\"`." }, "CallerLibrary": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "version": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Version" } }, "type": "object", "title": "CallerLibrary", "description": "Caller's instrumentation library — segment.io-canonical `library`." }, "CallerPage": { "properties": { "path": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Path" }, "referrer": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Referrer" }, "search": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Search" }, "title": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Title" }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Url" } }, "type": "object", "title": "CallerPage", "description": "Caller's current page — segment.io-canonical `page` shape." }, "ChannelCreate": { "properties": { "integration_id": { "type": "string", "format": "uuid", "title": "Integration Id", "description": "Org-level provider install serving this channel" }, "provider": { "type": "string", "maxLength": 64, "title": "Provider", "description": "Provider slug, e.g. 'slack'" }, "external_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "External Id", "description": "The provider's own channel key (a Slack channel id), the routing selector" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Display label, e.g. '#ops'. Never a selector" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Runtime group that answers this channel. Omit for the project's Operator, which is the ordinary case for a platform-owned bot." }, "share_conversations": { "type": "boolean", "title": "Share Conversations", "description": "Share conversations from this channel with the whole project. Set it for a channel whose discussion is already open to its audience; it is a policy this binding declares, not one inferred from the provider.", "default": false } }, "type": "object", "required": [ "integration_id", "provider", "external_id" ], "title": "ChannelCreate", "description": "Request body for binding a channel to the caller's project." }, "ChannelResponse": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "integration_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Integration Id" }, "provider": { "type": "string", "maxLength": 64, "title": "Provider", "description": "Provider slug, e.g. 'slack'" }, "external_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "External Id", "description": "The provider's own channel key (a Slack channel id), the routing selector" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Display label, e.g. '#ops'. Never a selector" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Runtime group that answers this channel. Omit for the project's Operator, which is the ordinary case for a platform-owned bot." }, "share_conversations": { "type": "boolean", "title": "Share Conversations", "description": "Share conversations from this channel with the whole project. Set it for a channel whose discussion is already open to its audience; it is a policy this binding declares, not one inferred from the provider.", "default": false }, "created_by_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By Member Id" } }, "type": "object", "required": [ "org_id", "project_id", "provider", "external_id" ], "title": "ChannelResponse", "description": "Public response. Carries no credential — the token lives on the\nintegration and is only ever materialized into an egress session." }, "ChannelUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Set the answering runtime group" }, "clear_runtime_group": { "type": "boolean", "title": "Clear Runtime Group", "description": "Clear the runtime group so the channel falls back to the project's Operator", "default": false }, "share_conversations": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Share Conversations", "description": "Share conversations from this channel with the whole project; omit to leave unchanged" } }, "type": "object", "title": "ChannelUpdate", "description": "Patch body. `external_id`, `provider` and `integration_id` are immutable\n— structurally so, since the row's id is derived from them: changing any of\nthem makes the row a different binding, which is a delete and a create, not\nan edit." }, "ClientRegistrationMethod": { "type": "string", "enum": [ "client_id_metadata_document", "dynamic", "pre_registered" ], "title": "ClientRegistrationMethod", "description": "How the platform identified itself to a custom OAuth provider.\n\nOrdered by preference at discovery: a Client ID Metadata Document needs no\nstate on the provider and is the MCP default, dynamic registration is the\nlegacy path providers keep for older clients, and a pre-registered client\nis what an operator supplies when the provider offers neither." }, "ConnectAuthorizeRequest": { "properties": { "connector_id": { "type": "string", "format": "uuid", "title": "Connector Id" }, "app": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,99}$" }, { "type": "null" } ], "title": "App", "description": "Provider application slug to connect; required for Pipedream Connect links." }, "allow_progressive_scopes": { "type": "boolean", "title": "Allow Progressive Scopes", "description": "Allow the user to grant a supported subset of the application's configured OAuth scopes.", "default": false }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runtime", "description": "Runtime slug or runtime group id whose latest ready version answers this connection's channels. Required for chat connectors; omit for connectors that only store credentials." }, "subject": { "$ref": "#/components/schemas/ConnectionSubjectType", "default": "app" }, "return_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Return Url", "description": "Allowed HTTP(S) URL where the browser returns after consent; defaults to the platform frontend" }, "expires_in": { "type": "integer", "maximum": 86400, "minimum": 60, "title": "Expires In", "description": "Seconds the returned URL stays valid, 60 to 86400 (one day). Raise it when the URL is handed to someone else to open rather than followed immediately.", "default": 600 }, "identity": { "anyOf": [ { "$ref": "#/components/schemas/RunnerIdentity" }, { "type": "null" } ], "description": "The end customer this grant is being made for, asserted by the caller. Its `user_id` resolves a `customer` member (the same `ensure_customer_member` mint an identity-asserted session uses) which is recorded as `created_by_member_id`, so a partner can associate the connection with their own caller instead of the agent member that made the API call. Omit to attribute the grant to the authenticated principal." } }, "type": "object", "required": [ "connector_id" ], "title": "ConnectAuthorizeRequest", "description": "What to mint a provider consent URL for (connect step 1).\n\nA POST because the call is not a read: it writes a single-use `state` into\nRedis with a TTL, so two calls yield two different URLs and neither response\nmay be cached. The OAuth spec's own `/authorize` is a GET, but that endpoint\nredirects a browser — this one returns JSON to a backend caller, which is\nthe same shape as Stripe's account links or Plaid's link tokens, both POSTs." }, "ConnectAuthorizeResponse": { "properties": { "authorize_url": { "type": "string", "title": "Authorize Url" }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Seconds the URL stays valid. It carries a single-use state, so a caller handing it to someone else — an SDK integrator putting it in front of their own user — needs to know it cannot be cached or shared indefinitely." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "Absolute expiry, the same deadline as `expires_in`. Both are returned because they answer different questions: a caller rendering a countdown wants the interval, and one persisting the URL wants a timestamp it can compare against later without having recorded when the response arrived." } }, "type": "object", "required": [ "authorize_url", "expires_in", "expires_at" ], "title": "ConnectAuthorizeResponse", "description": "The provider consent URL the caller opens to grant access (connect step 1)." }, "ConnectionCreate": { "properties": { "subject_type": { "$ref": "#/components/schemas/ConnectionSubjectType", "description": "Whose token this carries", "default": "app" }, "scopes_granted": { "items": { "type": "string" }, "type": "array", "title": "Scopes Granted", "description": "Scopes the provider granted" }, "access_token": { "type": "string", "minLength": 1, "title": "Access Token", "description": "Provider access token (encrypted at rest)" }, "refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refresh Token", "description": "Provider refresh token (encrypted at rest)" }, "token_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Token Expires At", "description": "Access token expiry" } }, "type": "object", "required": [ "access_token" ], "title": "ConnectionCreate", "description": "Registered-mode create: the caller supplies an already-obtained token.\n\n``member_id`` is bound from the verified principal for ``user`` subjects,\nnever from this body." }, "ConnectionResponse": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "subject_type": { "$ref": "#/components/schemas/ConnectionSubjectType", "description": "Whose token this carries", "default": "app" }, "scopes_granted": { "items": { "type": "string" }, "type": "array", "title": "Scopes Granted", "description": "Scopes the provider granted" }, "connector_id": { "type": "string", "format": "uuid", "title": "Connector Id" }, "member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Member Id" }, "created_by_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By Member Id", "description": "The member who performed the grant (never the subject)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Runtime group whose latest ready version answers this connection's channels. None is valid only for connectors that do not deliver conversations." }, "status": { "$ref": "#/components/schemas/ConnectionStatus", "default": "active" }, "token_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Token Expires At" } }, "type": "object", "required": [ "org_id", "connector_id" ], "title": "ConnectionResponse", "description": "Public connection response — never carries token material." }, "ConnectionStatus": { "type": "string", "enum": [ "pending_authorization", "active", "refresh_failed", "revoked" ], "title": "ConnectionStatus", "description": "Connection lifecycle (mirrors ``connection_status``)." }, "ConnectionSubjectType": { "type": "string", "enum": [ "app", "user", "federated", "person", "workspace" ], "title": "ConnectionSubjectType", "description": "Whose token a connection carries (mirrors ``connection_subject_type``)." }, "ConnectorApprovalPolicy": { "type": "string", "enum": [ "human", "judge_advises_human", "judge_auto_within_envelope" ], "title": "ConnectorApprovalPolicy", "description": "How a ``person_authorized`` mission is decided (mirrors ``connector_approval_policy``).\n\nThe judge is an approver rung under a human-granted policy — never the\nsecurity boundary. The deterministic constraints (§14.2) bind the envelope\nregardless of the verdict." }, "ConnectorAuthMode": { "type": "string", "enum": [ "static", "oauth_stored", "client_credentials", "identity_assertion", "federated_exchange", "person_authorized" ], "title": "ConnectorAuthMode", "description": "How a connector's token is sourced (mirrors ``connector_auth_mode``)." }, "ConnectorCreate": { "properties": { "slug": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Slug", "description": "Stable per-org identifier; derived from name when omitted" }, "name": { "type": "string", "maxLength": 255, "title": "Name", "description": "Display label" }, "provider": { "type": "string", "maxLength": 255, "title": "Provider", "description": "Provider slug, e.g. 'gmail'" }, "auth_mode": { "$ref": "#/components/schemas/ConnectorAuthMode", "description": "How the token is sourced" }, "environment": { "$ref": "#/components/schemas/Environment", "description": "Deployment environment this connector targets. A staging and a production provider app are separate apps holding separate credentials, so they are separate connectors; this is what tells them apart and what a minted channel session carries.", "default": "production" }, "agent_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agent Member Id", "description": "The fixed Member Agent this connector acts as — the actor its channel sessions are minted against. Omit on create to use the organization's Member Agent; a supplied id must reference that Member Agent." }, "authorization_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization Endpoint", "description": "OAuth authorize endpoint" }, "token_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Endpoint", "description": "OAuth token endpoint" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes", "description": "Requested scopes" }, "api_hosts": { "items": { "type": "string" }, "type": "array", "title": "Api Hosts", "description": "Resource host(s) the agent calls → egress allowlist" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id", "description": "Customer-owned OAuth client id" }, "person_server_mode": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorPersonServerMode" }, { "type": "null" } ], "description": "Person Server hosting (person_authorized only)" }, "person_server_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Person Server Url", "description": "Person Server base URL" }, "approval_policy": { "$ref": "#/components/schemas/ConnectorApprovalPolicy", "description": "How person_authorized missions are decided (human / judge-advises / judge-auto)", "default": "human" }, "application_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Application Id", "description": "The connector's application. Signs the assertion for identity_assertion; for chat connectors it also supplies the project, environment and agent member that channel sessions resolve through" }, "assertion_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assertion Audience", "description": "Expected `aud` for identity_assertion (falls back to https://{api_hosts[0]})" }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url", "description": "Delivery URL registered with the provider for this app. Stored rather than derived so ingress can move host without re-deriving every registration. Never fetched by the platform" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret", "description": "Plaintext OAuth client secret (encrypted at rest)" }, "signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signing Secret", "description": "Plaintext provider webhook signing secret (encrypted at rest)" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Display metadata" }, "issuer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Issuer", "description": "Provider issuer / service URL for discovery (Vercel-style Custom OAuth). When set and the endpoints are omitted, the CP resolves authorization_endpoint/token_endpoint from the issuer's .well-known metadata at create time. Not persisted as a column." } }, "type": "object", "required": [ "name", "provider", "auth_mode" ], "title": "ConnectorCreate", "description": "Create a connector. ``client_secret`` is sealed before storage." }, "ConnectorOAuthDiscoveryRequest": { "properties": { "issuer": { "type": "string", "minLength": 1, "title": "Issuer", "description": "OAuth authorization-server issuer URL, or the URL of an MCP server / protected resource whose RFC 9728 metadata names its authorization server" } }, "type": "object", "required": [ "issuer" ], "title": "ConnectorOAuthDiscoveryRequest", "description": "URL to resolve before presenting custom OAuth client fields." }, "ConnectorOAuthDiscoveryResponse": { "properties": { "issuer": { "type": "string", "title": "Issuer" }, "authorization_endpoint": { "type": "string", "title": "Authorization Endpoint" }, "token_endpoint": { "type": "string", "title": "Token Endpoint" }, "registration_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registration Endpoint" }, "token_endpoint_auth_methods_supported": { "items": { "type": "string" }, "type": "array", "title": "Token Endpoint Auth Methods Supported" }, "code_challenge_methods_supported": { "items": { "type": "string" }, "type": "array", "title": "Code Challenge Methods Supported" }, "scopes_supported": { "items": { "type": "string" }, "type": "array", "title": "Scopes Supported" }, "client_id_metadata_document_supported": { "type": "boolean", "title": "Client Id Metadata Document Supported", "default": false }, "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource", "description": "RFC 9728 resource identifier of the protected resource discovery started from; sent as the RFC 8707 `resource` parameter so the provider audiences the token to that server" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret" }, "client_registration": { "anyOf": [ { "$ref": "#/components/schemas/ClientRegistrationMethod" }, { "type": "null" } ], "description": "How `client_id` was obtained; unset when the provider offers no automatic registration" } }, "type": "object", "required": [ "issuer", "authorization_endpoint", "token_endpoint" ], "title": "ConnectorOAuthDiscoveryResponse", "description": "OAuth metadata relevant to connector registration and token exchange." }, "ConnectorPersonServerMode": { "type": "string", "enum": [ "managed", "byo", "discovered" ], "title": "ConnectorPersonServerMode", "description": "Who hosts the Person Server for ``person_authorized`` connectors." }, "ConnectorResponse": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "slug": { "type": "string", "maxLength": 255, "title": "Slug", "description": "Stable per-org identifier; create is idempotent on (org_id, slug)" }, "name": { "type": "string", "maxLength": 255, "title": "Name", "description": "Display label" }, "provider": { "type": "string", "maxLength": 255, "title": "Provider", "description": "Provider slug, e.g. 'gmail'" }, "auth_mode": { "$ref": "#/components/schemas/ConnectorAuthMode", "description": "How the token is sourced" }, "environment": { "$ref": "#/components/schemas/Environment", "description": "Deployment environment this connector targets. A staging and a production provider app are separate apps holding separate credentials, so they are separate connectors; this is what tells them apart and what a minted channel session carries.", "default": "production" }, "agent_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agent Member Id", "description": "The fixed Member Agent this connector acts as — the actor its channel sessions are minted against. Omit on create to use the organization's Member Agent; a supplied id must reference that Member Agent." }, "authorization_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization Endpoint", "description": "OAuth authorize endpoint" }, "token_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Endpoint", "description": "OAuth token endpoint" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes", "description": "Requested scopes" }, "api_hosts": { "items": { "type": "string" }, "type": "array", "title": "Api Hosts", "description": "Resource host(s) the agent calls → egress allowlist" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id", "description": "Customer-owned OAuth client id" }, "person_server_mode": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorPersonServerMode" }, { "type": "null" } ], "description": "Person Server hosting (person_authorized only)" }, "person_server_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Person Server Url", "description": "Person Server base URL" }, "approval_policy": { "$ref": "#/components/schemas/ConnectorApprovalPolicy", "description": "How person_authorized missions are decided (human / judge-advises / judge-auto)", "default": "human" }, "application_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Application Id", "description": "The connector's application. Signs the assertion for identity_assertion; for chat connectors it also supplies the project, environment and agent member that channel sessions resolve through" }, "assertion_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assertion Audience", "description": "Expected `aud` for identity_assertion (falls back to https://{api_hosts[0]})" }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url", "description": "Delivery URL registered with the provider for this app. Stored rather than derived so ingress can move host without re-deriving every registration. Never fetched by the platform" }, "status": { "$ref": "#/components/schemas/ConnectorStatus", "default": "pending" }, "created_by_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By Member Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "requires_runtime": { "type": "boolean", "title": "Requires Runtime", "description": "Whether connecting this connector must name a runtime group.\n\nDerived rather than stored: it is a property of the provider, not of the\nrow, so storing it would let the two disagree. Returned so a client —\nour settings UI, or an integrator building their own connect flow —\nknows whether to ask for a runtime without hardcoding a provider list\nthat drifts from `RUNTIME_BOUND_PROVIDERS` the moment a provider is added.", "readOnly": true } }, "type": "object", "required": [ "org_id", "project_id", "slug", "name", "provider", "auth_mode", "requires_runtime" ], "title": "ConnectorResponse", "description": "Public connector response — never carries the client or signing secret.\n\nThis is the response model for create, read, list *and* update, which is what\nmakes the two secrets on `ConnectorUpdate` write-only: they can be sent, and\nthere is no shape that sends them back." }, "ConnectorStatus": { "type": "string", "enum": [ "pending", "active", "error" ], "title": "ConnectorStatus", "description": "Connector lifecycle (mirrors ``connector_status``)." }, "ConnectorUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "agent_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agent Member Id", "description": "Rebind this connector to the fixed Member Agent in its organization." }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scopes" }, "api_hosts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Api Hosts" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/ConnectorStatus" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret", "description": "Write-only: replaces the sealed client secret" }, "signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signing Secret", "description": "Write-only: replaces the sealed signing secret" } }, "type": "object", "title": "ConnectorUpdate", "description": "Partial update — only provided fields change.\n\n``environment`` is deliberately absent: it is a create-time fact. A staging\nand a production provider app are separate apps holding separate\ncredentials, and the provider keeps delivering to one URL — changing it\nwould repoint live connections at the wrong one.\n\n``agent_member_id`` IS settable. It is the actor a channel session carries,\nnot its subject: the turn is minted as the channel member, who owns the\nresulting task and files. Changing the actor redirects future delegation\nand reassigns nothing.\n\nThe two secrets are **write-only**: accepted here, never present on any\nresponse shape. They are settable after create because the registration\norder requires it — a provider app is registered against the delivery URL,\nwhich contains the connector id, so the row exists before the app does and\ntherefore before its credentials do. The create-time upsert deliberately\npreserves sealed columns (its AAD is bound to a freshly-generated id), so\nthis is the only path that can fill them in, and the only path that can\nreplace a leaked one." }, "DisplayIdPrefixes": { "properties": { "issue": { "type": "string", "maxLength": 5, "title": "Issue", "default": "I" }, "report": { "type": "string", "maxLength": 5, "title": "Report", "default": "R" }, "observation": { "type": "string", "maxLength": 5, "title": "Observation", "default": "F" }, "task": { "type": "string", "maxLength": 5, "title": "Task", "default": "T" } }, "type": "object", "title": "DisplayIdPrefixes", "description": "Configurable prefixes for display IDs within a project." }, "EndpointCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Display label (not unique)." }, "host": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Host", "description": "Canonicalised hostname; no scheme, no path, no port." }, "base_url": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Base Url", "description": "Optional full SDK base_url override (https://, netloc must match host)." }, "kind": { "$ref": "#/components/schemas/EndpointKind", "description": "Endpoint role: 'llm' (model provider, counts toward BYOK), 'api' (plain upstream HTTP API; renamed from 'runtime'), or 'mcp' (MCP server). The legacy 'runtime' value is accepted as an alias for 'api'.", "default": "llm" }, "metadata": { "$ref": "#/components/schemas/EndpointMetadata", "description": "Non-secret endpoint metadata. MCP bindings use metadata.mcp_server_id." }, "assertion_claims": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Assertion Claims", "description": "Extra claims merged into identity assertions for this endpoint (e.g. Supabase's PostgREST contract: {\"role\": \"authenticated\"}). Cannot be combined with a stored Authorization header (the assertion occupies it); reserved claims (iss/sub/aud/exp/...) are rejected." }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Optional scope. When set, the endpoint is only available to this Runtime. When NULL, available to all Runtimes in the project." }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Optional runtime group scope. NULL means every runtime group." }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ], "description": "Optional environment scope. NULL means every environment." }, "verify_path": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Verify Path", "description": "Optional path for pre-flight verify (e.g. '/v1/models'). When set, save is blocked until a GET to {base_url ?? https://{host}}{verify_path} returns 2xx. Empty means no verify." }, "headers": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Headers", "description": "Header name → value. Credential references remain unresolved in operator API responses. May be empty for public or allowlist-only endpoints." }, "authorized_application_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Authorized Application Id", "description": "The single application that signs this endpoint's identity assertions (the endpoint's one assertion signer). Optional for every endpoint kind. Linking installs the application's ES256 signing key; the assertion is delivered as the endpoint's Authorization header, so the endpoint must not also set a stored Authorization header (other headers are injected alongside). Owner-only." } }, "type": "object", "required": [ "name", "host", "headers" ], "title": "EndpointCreate", "description": "POST body — upserts by (org, project, host).\n\n`headers` is plaintext on the wire and encrypted at the repository\nlayer before persisting. Empty headers are valid for public or\nallowlist-only endpoints." }, "EndpointKind": { "type": "string", "enum": [ "llm", "api", "mcp" ], "title": "EndpointKind", "description": "Endpoint role discriminator." }, "EndpointMetadata": { "properties": { "mcp_server_id": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$" }, { "type": "null" } ], "title": "Mcp Server Id", "description": "Stable logical MCP server id. Only meaningful for kind='mcp'." }, "connector_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Connector Id", "description": "Connector whose stored connection authenticates this MCP endpoint. Only meaningful for kind='mcp'; the connection is selected per session subject." }, "auth_audience": { "anyOf": [ { "type": "string", "maxLength": 1024, "minLength": 1 }, { "type": "null" } ], "title": "Auth Audience", "description": "Stable application-auth audience for a logical MCP server. Independent from the environment transport URL." } }, "additionalProperties": true, "type": "object", "title": "EndpointMetadata", "description": "Non-secret endpoint metadata carried into session bootstrap." }, "EndpointResponse": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Display label (not unique)." }, "host": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Host", "description": "Canonicalised hostname; no scheme, no path, no port." }, "base_url": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Base Url", "description": "Optional full SDK base_url override (https://, netloc must match host)." }, "kind": { "$ref": "#/components/schemas/EndpointKind", "description": "Endpoint role: 'llm' (model provider, counts toward BYOK), 'api' (plain upstream HTTP API; renamed from 'runtime'), or 'mcp' (MCP server). The legacy 'runtime' value is accepted as an alias for 'api'.", "default": "llm" }, "metadata": { "$ref": "#/components/schemas/EndpointMetadata", "description": "Non-secret endpoint metadata. MCP bindings use metadata.mcp_server_id." }, "assertion_claims": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Assertion Claims", "description": "Extra claims merged into identity assertions for this endpoint (e.g. Supabase's PostgREST contract: {\"role\": \"authenticated\"}). Cannot be combined with a stored Authorization header (the assertion occupies it); reserved claims (iss/sub/aud/exp/...) are rejected." }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Optional scope. When set, the endpoint is only available to this Runtime. When NULL, available to all Runtimes in the project." }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Optional runtime group scope. NULL means every runtime group." }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ], "description": "Optional environment scope. NULL means every environment." }, "verify_path": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Verify Path", "description": "Optional path for pre-flight verify (e.g. '/v1/models'). When set, save is blocked until a GET to {base_url ?? https://{host}}{verify_path} returns 2xx. Empty means no verify." }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "headers": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Headers", "description": "Configured header values with credential references left unresolved." }, "header_names": { "items": { "type": "string" }, "type": "array", "title": "Header Names", "description": "Configured header names." }, "credential_refs": { "items": { "type": "string" }, "type": "array", "title": "Credential Refs", "description": "Credential names referenced from header values via ${NAME} (non-secret)." }, "last_verified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Verified At" }, "authorized_application_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Authorized Application Id", "description": "The single application that signs this endpoint's identity assertions (FK → applications)." }, "created_by_member_id": { "type": "string", "format": "uuid", "title": "Created By Member Id" } }, "type": "object", "required": [ "org_id", "name", "host", "project_id", "created_by_member_id" ], "title": "EndpointResponse", "description": "Operator-facing endpoint response.\n\nHeader values contain configuration and credential references. Credential\nsecrets remain write-only resources and are never expanded into this map." }, "EndpointUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "host": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Host" }, "base_url": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Base Url" }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers" }, "kind": { "anyOf": [ { "$ref": "#/components/schemas/EndpointKind" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/EndpointMetadata" }, { "type": "null" } ] }, "assertion_claims": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Assertion Claims" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id" }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ] }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id" }, "verify_path": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Verify Path" }, "authorized_application_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Authorized Application Id", "description": "The single application that signs this endpoint's identity assertions (the endpoint's one assertion signer). Linking installs the application's ES256 signing key; the assertion is delivered as the endpoint's Authorization header, so the endpoint must not also set a stored Authorization header (other headers are injected alongside). Clearing to null is not supported — omit to leave unchanged." } }, "type": "object", "title": "EndpointUpdate", "description": "PATCH body — all fields optional.\n\nA PATCH that changes `headers`, `host`, `base_url`, or `verify_path`\non a row with a non-null `verify_path` re-runs pre-flight verify and\nblocks the update on success. Renaming (`name`) or rescoping\n(`runtime_id`) skips verify." }, "Environment": { "type": "string", "enum": [ "development", "staging", "production" ], "title": "Environment", "description": "Runtime environment lane." }, "Experiment": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description", "description": "Optional operator notes — the experiment's hypothesis / why it's running." }, "runtime_group_id": { "type": "string", "format": "uuid", "title": "Runtime Group Id", "description": "The Runtime group this experiment is testing. All arms must reference Runtime rows in this group." }, "environment": { "$ref": "#/components/schemas/Environment", "description": "Environment lane this experiment routes inside.", "default": "production" }, "goal_json": { "$ref": "#/components/schemas/ExperimentGoal", "description": "Composite Goal — see docs/design/runtime-platform.md for the shape. Components reference typed telemetry fields or pinned judge definitions. REQUIRED — it is the reward the bandit optimizes; an adaptive scorer with no goal can't learn and stays uniform-random. DB column is JSONB NOT NULL — an empty component list is rejected at create." }, "scoring_interval_seconds": { "type": "integer", "maximum": 86400, "minimum": 10, "title": "Scoring Interval Seconds", "description": "How often the scorer recomputes posteriors + weights.", "default": 300 }, "hash_key_fields": { "items": { "type": "string" }, "type": "array", "title": "Hash Key Fields", "description": "Baggage / header walk order for the consistent-hash subject." }, "sample_rate": { "type": "number", "maximum": 1, "minimum": 0.1, "title": "Sample Rate", "description": "Fraction of the runtime group's traffic served to this experiment — its blast radius. Out-of-sample subjects get the group's normal production runtime (never scored); in-sample subjects are Thompson-sampled across all arms. Operator-selectable on production (10%–100%); always 100% on every other lane. Frozen once the experiment is running.", "default": 1 }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "status": { "$ref": "#/components/schemas/ExperimentStatus", "default": "draft" }, "routing_strategy": { "$ref": "#/components/schemas/ExperimentRoutingStrategy", "default": "beta_sample" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "ended_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Ended At" }, "posterior_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Posterior Json" }, "weights_json": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Weights Json" }, "arms": { "items": { "$ref": "#/components/schemas/ExperimentArm" }, "type": "array", "title": "Arms" }, "created_by_member_id": { "type": "string", "format": "uuid", "title": "Created By Member Id" }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Archived At" }, "halted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Halted At" }, "halted_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Halted Reason" } }, "type": "object", "required": [ "org_id", "name", "runtime_group_id", "project_id", "created_by_member_id" ], "title": "Experiment", "description": "Full Experiment row.\n\nUsed as the API response shape directly — there is no separate\nExperimentResponse wrapper. `deleted_at` is excluded from wire\nserialization by the SoftDeleteMixin so the wire payload only\ncarries fields callers care about. `org_id` is included so\nmulti-tenant clients (e.g. agents-worker tests) can spot mismatches\nwithout a second lookup." }, "ExperimentArm": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "runtime_id": { "type": "string", "format": "uuid", "title": "Runtime Id" }, "arm_label": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Arm Label", "description": "Operator-facing display label for charts (e.g. 'control', 'shorter-prompt')." }, "agent_overrides": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Agent Overrides", "description": "Entry-point agent remap for this arm: {called_agent -> target_agent} (recipe `agents/*.yaml` names). A called entrypoint matching a key runs the target instead — e.g. {'agent-codex': 'agent-codex2'} — so one runtime serves several arms differing only by agent. Applies ONLY to the session entrypoint, never to subagent dispatch. Resolved at routing time and authoritative for in-sample traffic. Null/empty = the runtime's own default agent resolution." }, "initial_weight": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Initial Weight", "description": "System-seeded starting weight (even split across arms). NOT operator-authored — the bandit reallocates from the posterior once scoring begins. Present on reads for observability; absent from the create body.", "default": 0 } }, "type": "object", "required": [ "id", "runtime_id", "arm_label" ], "title": "ExperimentArm", "description": "One arm of an experiment — a synthetic id + a Runtime row + display label.\n\n`id` is the arm's own identity: several arms can share one `runtime_id` and\ndiffer only by `agent_overrides` (e.g. \"main baseline\" vs \"main + overrides\"),\nso scoring, posterior, weights, and judgement telemetry key on `id`, never on\n`runtime_id`." }, "ExperimentArmCreate": { "properties": { "runtime_id": { "type": "string", "format": "uuid", "title": "Runtime Id" }, "arm_label": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Arm Label", "description": "Operator-facing display label for charts (e.g. 'control', 'shorter-prompt')." }, "agent_overrides": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Agent Overrides", "description": "Optional entry-point agent remap for this arm: {called_agent -> target_agent} (recipe `agents/*.yaml` names). Applies only to the session entrypoint, never to subagents. Omit for no remap (the runtime's own default agent resolution)." } }, "type": "object", "required": [ "runtime_id", "arm_label" ], "title": "ExperimentArmCreate", "description": "One arm in the create body — a runtime + display label.\n\nArms are symmetric: there is no operator-selected baseline. The multi-armed\nbandit (`beta_sample`) Thompson-samples across all arms equally and allocates\ntraffic from the posterior, so operators set neither a per-arm weight nor a\ncontrol flag. The incumbent (current production version) is simply whichever\nruntime currently serves production for the group — out-of-sample traffic is\nrouted to it via normal production resolution, independent of the experiment." }, "ExperimentCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description", "description": "Optional operator notes — the experiment's hypothesis / why it's running." }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "title": "Runtime", "description": "Runtime slug or group id this Experiment tests." }, "environment": { "$ref": "#/components/schemas/Environment", "description": "Environment lane this experiment routes inside.", "default": "production" }, "goal_json": { "$ref": "#/components/schemas/ExperimentGoalSpec", "description": "The reward the bandit optimizes. REQUIRED, and must contain at least one positive-weight `source: \"judge\"` component; obtain judge_id values from GET /v1/judges (judges are authored as judges/*.yaml in the recipe repository and synced when a runtime versions that commit — they cannot be created via the API)." }, "scoring_interval_seconds": { "type": "integer", "maximum": 86400, "minimum": 10, "title": "Scoring Interval Seconds", "description": "How often the scorer recomputes posteriors + weights.", "default": 300 }, "hash_key_fields": { "items": { "type": "string" }, "type": "array", "title": "Hash Key Fields", "description": "Baggage / header walk order for the consistent-hash subject." }, "sample_rate": { "type": "number", "maximum": 1, "minimum": 0.1, "title": "Sample Rate", "description": "Fraction of the runtime group's traffic served to this experiment — its blast radius. Out-of-sample subjects get the group's normal production runtime (never scored); in-sample subjects are Thompson-sampled across all arms. Operator-selectable on production (10%–100%); always 100% on every other lane. Frozen once the experiment is running.", "default": 1 }, "project": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "title": "Project", "description": "Project slug or id this Experiment belongs to. Tenant-validated against the caller's org." }, "arms": { "items": { "$ref": "#/components/schemas/ExperimentArmCreate" }, "type": "array", "maxItems": 20, "minItems": 2, "title": "Arms", "description": "2-20 arms; all runtime_ids must share the experiment's runtime_group_id." } }, "additionalProperties": false, "type": "object", "required": [ "name", "runtime", "goal_json", "project", "arms" ], "title": "ExperimentCreate", "description": "POST /v1/experiments body.\n\nPrerequisites (in order): a recipe repository with at least one\n`judges/*.yaml`; a runtime versioned from it (judge sync populates\n`GET /v1/judges`); 2-20 further runtime versions in the same runtime\ngroup to use as arms. Create produces a DRAFT that routes nothing until\n`POST /v1/experiments/{id}/start`.", "examples": [ { "arms": [ { "arm_label": "control", "runtime_id": "0195c0de-0000-7000-8000-00000000000b" }, { "arm_label": "variant", "runtime_id": "0195c0de-0000-7000-8000-00000000000c" } ], "goal_json": { "components": [ { "judge_id": "0195c0de-0000-7000-8000-00000000000d", "source": "judge", "weight": 1 } ], "direction": "maximize", "kind": "composite" }, "name": "helpfulness-prompt-test", "project": "my-project", "runtime_group_id": "0195c0de-0000-7000-8000-00000000000a" } ] }, "ExperimentGoal": { "properties": { "kind": { "type": "string", "const": "composite", "title": "Kind", "default": "composite" }, "direction": { "$ref": "#/components/schemas/ExperimentGoalDirection", "default": "maximize" }, "components": { "items": { "oneOf": [ { "$ref": "#/components/schemas/JudgeGoalComponent" }, { "$ref": "#/components/schemas/TelemetryGoalComponent" } ], "discriminator": { "propertyName": "source", "mapping": { "judge": "#/components/schemas/JudgeGoalComponent", "telemetry": "#/components/schemas/TelemetryGoalComponent" } } }, "type": "array", "title": "Components" } }, "type": "object", "title": "ExperimentGoal", "description": "Composite objective for adaptive experiment scoring." }, "ExperimentGoalDirection": { "type": "string", "enum": [ "maximize", "minimize" ], "title": "ExperimentGoalDirection", "description": "How component scores combine into the optimized reward." }, "ExperimentGoalGuard": { "properties": { "min": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Min" }, "max": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Max" } }, "type": "object", "title": "ExperimentGoalGuard", "description": "Canary bound over one component's rate." }, "ExperimentGoalSpec": { "properties": { "kind": { "type": "string", "const": "composite", "title": "Kind", "default": "composite" }, "direction": { "$ref": "#/components/schemas/ExperimentGoalDirection", "default": "maximize" }, "components": { "items": { "oneOf": [ { "$ref": "#/components/schemas/JudgeGoalComponent" }, { "$ref": "#/components/schemas/TelemetryGoalComponent" } ], "discriminator": { "propertyName": "source", "mapping": { "judge": "#/components/schemas/JudgeGoalComponent", "telemetry": "#/components/schemas/TelemetryGoalComponent" } } }, "type": "array", "minItems": 1, "title": "Components", "description": "Reward components. At least one must be `source: \"judge\"` with weight > 0 — the v1 scorer only implements judge-backed reward, and a goal without one is rejected." } }, "type": "object", "required": [ "components" ], "title": "ExperimentGoalSpec", "description": "The goal as accepted at create/update time.\n\nSame shape as `ExperimentGoal`, but the schema encodes what the bandit\nvalidator enforces instead of hiding it: at least one component is\nrequired, and at least one must be a positive-weight `source: \"judge\"`\ncomponent. Stored/read goals stay `ExperimentGoal` (legacy rows may hold\nempty goals)." }, "ExperimentRoutingStrategy": { "type": "string", "enum": [ "beta_sample" ], "title": "ExperimentRoutingStrategy", "description": "How CP picks an arm per runner request.\n\nBETA_SAMPLE is the only strategy — a multi-armed bandit. It is per-request\nThompson sampling seeded by the identity token (reproducible) on every lane;\narms are symmetric (no special baseline). Production exposure is bounded by\nthe experiment's `sample_rate` (an out-of-sample subject is served the\ngroup's normal production runtime, unattributed), not by a candidate-traffic\ncap. In-sample subjects are pinned to one arm for the experiment's lifetime.\n(Retained as a single-value enum so the row + API response keep a typed\nstrategy; hrw / round_robin were removed.)" }, "ExperimentStatus": { "type": "string", "enum": [ "draft", "running", "ended", "cancelled" ], "title": "ExperimentStatus", "description": "Experiment lifecycle.\n\ndraft → arms can still be edited; routing is not live.\nrunning → routing live; scorer updating posteriors + weights. At most one\n running experiment per (runtime group + environment); starting another\n while one is running is a 409 — end it first.\nended → operator concluded the experiment after reviewing the result\n (terminal; production changes only when the winning PR is merged).\ncancelled → operator aborted before a winner (terminal)." }, "ExperimentUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "goal_json": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentGoal" }, { "type": "null" } ] }, "scoring_interval_seconds": { "anyOf": [ { "type": "integer", "maximum": 86400, "minimum": 10 }, { "type": "null" } ], "title": "Scoring Interval Seconds" }, "hash_key_fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Hash Key Fields" }, "sample_rate": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0.1 }, { "type": "null" } ], "title": "Sample Rate", "description": "Edit the experiment's traffic share (draft only; frozen once running)." } }, "type": "object", "title": "ExperimentUpdate", "description": "PATCH /v1/experiments/{id} — mutable fields.\n\nStatus transitions go through dedicated endpoints (start / end /\ncancel); runtime_group_id and arms are immutable once the experiment is\nrunning so live routing decisions can never become inconsistent. While\nrunning, only description stays editable; goal_json and sample_rate are\nfixed so accumulated evidence keeps a single measured objective and the\nsampled population never shifts mid-experiment." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HostedRepositoryCreate": { "properties": { "provider": { "type": "string", "const": "hosted", "title": "Provider" }, "slug": { "type": "string", "maxLength": 63, "minLength": 1, "title": "Slug" }, "default_branch": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Default Branch", "default": "main" }, "seed_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seed Template", "description": "Name of a template baked into the deployment's worker image, rendered to this slug as the first commit. Omit for the deployment's configured default; explicit null for an empty repository (what the CLI sends when it seeds from a git URL itself)." } }, "type": "object", "required": [ "provider", "slug" ], "title": "HostedRepositoryCreate", "description": "Request to create a repository hosted on the project's data plane.\n\nIdempotent on `slug`: a repeat returns the live row. The row is intent; the\nhosted copy exists once the first push lands (`provisioning_status`)." }, "Judge": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Judge's Recipe-local `name:`." }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Operator off-switch; a disabled judge is not dispatched.", "default": true }, "sample_rate": { "type": "number", "maximum": 1, "minimum": 0, "title": "Sample Rate", "description": "Fraction of PRODUCTION traffic to judge (lower envs judge in full).", "default": 1 }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "runtime_group_id": { "type": "string", "format": "uuid", "title": "Runtime Group Id" }, "source": { "type": "string", "title": "Source", "default": "recipe" }, "repository_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Repository Id" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha" }, "source_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Path" }, "definition_hash": { "type": "string", "title": "Definition Hash" }, "created_by_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By Member Id" } }, "type": "object", "required": [ "org_id", "name", "project_id", "runtime_group_id", "definition_hash" ], "title": "Judge", "description": "Full Judge registry schema with lineage.\n\nRecipe-synced: no audit mixin. The definition + its hash are set by the\nruntime-version sync; only operational state is mutable via the API." }, "JudgeGoalComponent": { "properties": { "source": { "type": "string", "const": "judge", "title": "Source", "default": "judge" }, "judge_id": { "type": "string", "format": "uuid", "title": "Judge Id", "description": "Registry id of a deployed judge in this project — discover via GET /v1/judges. Judges cannot be created through the API: author a judges/*.yaml in the recipe repository; it syncs into the registry when the runtime versions that commit." }, "judge_definition_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Judge Definition Hash", "description": "Definition hash pinned by CP at experiment create/update." }, "weight": { "type": "number", "minimum": 0, "title": "Weight", "description": "Reward weight. The bandit needs at least one judge component with weight > 0.", "default": 1 }, "guard": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentGoalGuard" }, { "type": "null" } ] } }, "type": "object", "required": [ "judge_id" ], "title": "JudgeGoalComponent", "description": "Judge-backed reward or guard component." }, "JudgeOperationalUpdate": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "sample_rate": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Sample Rate" } }, "type": "object", "title": "JudgeOperationalUpdate", "description": "PATCH body — operator updates to a judge's OPERATIONAL state only.\n\nThe definition (on/llm/instructions) is git-owned and never editable\nvia the API; only the platform-owned runtime controls are mutable here. Both\nfields optional so a PATCH sets only what it sends." }, "MissionConstraints": { "properties": { "host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Host", "description": "Resource host lock (request aud)" }, "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource", "description": "Opaque or hashed recipient/resource lock (e.g. a hash of the recipient email, or an account handle). NEVER a raw email/PII — the human-readable value lives in the DP attestation." }, "limits": { "additionalProperties": true, "type": "object", "title": "Limits", "description": "e.g. {amount_max, count}" }, "window_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Window Start", "description": "Grant validity start" }, "window_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Window End", "description": "Grant validity end" }, "payload_binding": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payload Binding", "description": "sha256 of the approved artifact — the 'purpose' as a deterministic hash" } }, "type": "object", "title": "MissionConstraints", "description": "Structured, deterministic constraints on a mission — the enforceable\nenvelope (§14). Stored as plaintext JSONB on the CP and enforced byte/field-\nexact at the **egress boundary in the DP/sandbox**, so the CP never needs the\nraw value. The envelope MUST stay non-PII: any PII-bearing lock (a recipient\nemail, an account) is carried as an opaque or hashed reference here, with the\nhuman-readable value living in the DP attestation (``attestation_refs``),\nnever on the CP. That is why these columns are not encrypted." }, "PaginatedResponse_ChannelResponse_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/ChannelResponse" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[ChannelResponse]" }, "PaginatedResponse_ConnectionResponse_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/ConnectionResponse" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[ConnectionResponse]" }, "PaginatedResponse_ConnectorResponse_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/ConnectorResponse" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[ConnectorResponse]" }, "PaginatedResponse_EndpointResponse_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/EndpointResponse" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[EndpointResponse]" }, "PaginatedResponse_Experiment_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/Experiment" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[Experiment]" }, "PaginatedResponse_Judge_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/Judge" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[Judge]" }, "PaginatedResponse_ProjectResponse_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/ProjectResponse" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[ProjectResponse]" }, "PaginatedResponse_Recipe_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/Recipe" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[Recipe]" }, "PaginatedResponse_Runtime_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/Runtime" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[Runtime]" }, "ProjectCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Project name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description", "description": "Project description" }, "display_id_prefixes": { "$ref": "#/components/schemas/DisplayIdPrefixes", "description": "Custom prefixes for display IDs (I-1, R-1, etc.)" }, "settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Settings", "description": "Project-specific settings" }, "deployment_id": { "type": "string", "format": "uuid", "title": "Deployment Id", "description": "Deployment this project is linked to" }, "slug": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Slug", "description": "Project slug used as a stable identifier" } }, "type": "object", "required": [ "name", "deployment_id" ], "title": "ProjectCreate", "description": "Schema for creating a project." }, "ProjectResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id" }, "deployment_id": { "type": "string", "format": "uuid", "title": "Deployment Id" }, "name": { "type": "string", "title": "Name" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Settings", "description": "Project-specific settings" }, "created_by_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By Member Id" } }, "type": "object", "required": [ "id", "org_id", "deployment_id", "name", "description" ], "title": "ProjectResponse", "description": "Project API response." }, "ProjectUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "display_id_prefixes": { "anyOf": [ { "$ref": "#/components/schemas/DisplayIdPrefixes" }, { "type": "null" } ] }, "settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Settings" } }, "type": "object", "title": "ProjectUpdate", "description": "Schema for updating a project." }, "PullRequestMetadataRequest": { "properties": { "urls": { "items": { "type": "string", "maxLength": 2048 }, "type": "array", "maxItems": 200, "title": "Urls" } }, "type": "object", "required": [ "urls" ], "title": "PullRequestMetadataRequest" }, "Recipe": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Operator label; can be shared across versions." }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "git_ref": { "type": "string", "title": "Git Ref" }, "git_commit_sha": { "type": "string", "title": "Git Commit Sha" }, "git_commit_subject": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Git Commit Subject", "description": "First line of the git commit message for deployment display." }, "sub_path": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Sub Path", "description": "Optional sub-path within the Repository (monorepo support)." }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "repository_id": { "type": "string", "format": "uuid", "title": "Repository Id" }, "slug": { "type": "string", "title": "Slug" }, "created_by_member_id": { "type": "string", "format": "uuid", "title": "Created By Member Id" }, "mcp_servers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RecipeMcpServer" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Servers" }, "validation": { "$ref": "#/components/schemas/RecipeValidation" } }, "type": "object", "required": [ "org_id", "name", "git_ref", "git_commit_sha", "project_id", "repository_id", "slug", "created_by_member_id" ], "title": "Recipe", "description": "Full Recipe schema with audit trail.\n\nThe database stores validation as a typed `validation_status` column\n(guardable by SQL) plus a `validation_metadata` payload; the API keeps\nthe single nested `validation` object, recomposed on read below." }, "RecipeCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Operator label; can be shared across versions." }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "git_ref": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Git Ref", "description": "Branch, tag, or short sha the operator picked." }, "git_commit_sha": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{40}$" }, { "type": "null" } ], "title": "Git Commit Sha", "description": "40-char hex commit sha." }, "git_commit_subject": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Git Commit Subject", "description": "First line of the git commit message for deployment display." }, "sub_path": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Sub Path", "description": "Optional sub-path within the Repository (monorepo support)." }, "project": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "title": "Project", "description": "Project slug or id this Recipe belongs to. Tenant-validated against the caller's org." }, "repository_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Repository Id", "description": "The Repository this Recipe is pinned against." }, "repository": { "anyOf": [ { "$ref": "#/components/schemas/RecipeRepositorySource" }, { "type": "null" } ], "description": "GitHub repository selected for this recipe. The platform links it to the project automatically." }, "slug": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Slug", "description": "Optional stable slug; derived from name + short sha if omitted." } }, "additionalProperties": false, "type": "object", "required": [ "name", "project" ], "title": "RecipeCreate", "description": "Schema for POST /v1/recipes." }, "RecipeMcpServer": { "properties": { "id": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$", "title": "Id" }, "required": { "type": "boolean", "title": "Required", "default": false }, "tools": { "$ref": "#/components/schemas/RecipeMcpTools" } }, "type": "object", "required": [ "id", "tools" ], "title": "RecipeMcpServer", "description": "One normalized logical MCP declaration from package.json." }, "RecipeMcpTools": { "properties": { "include": { "items": { "type": "string" }, "type": "array", "title": "Include" }, "exclude": { "items": { "type": "string" }, "type": "array", "title": "Exclude" } }, "type": "object", "title": "RecipeMcpTools", "description": "Normalized package-level MCP tool ceiling." }, "RecipeRepositorySource": { "properties": { "integration_id": { "type": "string", "format": "uuid", "title": "Integration Id" }, "full_name": { "type": "string", "maxLength": 255, "minLength": 3, "pattern": "^[^/]+/[^/]+$", "title": "Full Name" } }, "type": "object", "required": [ "integration_id", "full_name" ], "title": "RecipeRepositorySource", "description": "GitHub source used to create or reuse a project repository link." }, "RecipeUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "validation": { "anyOf": [ { "$ref": "#/components/schemas/RecipeValidationUpdate" }, { "type": "null" } ] } }, "type": "object", "title": "RecipeUpdate", "description": "Schema for PATCH /v1/recipes/{recipe_id}.\n\nOperator-presentation fields and a validation reset are mutable. The git pin\n(repository_id, git_ref, git_commit_sha, sub_path) is immutable —\npointing at different content means creating a new Recipe row." }, "RecipeValidation": { "properties": { "status": { "$ref": "#/components/schemas/RecipeValidationStatus", "default": "pending" }, "validator_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Validator Name" }, "validator_version": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Validator Version" }, "checked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Checked At" }, "error_message": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ], "title": "Error Message" }, "diagnostics": { "items": { "$ref": "#/components/schemas/RecipeValidationDiagnostic" }, "type": "array", "maxItems": 100, "title": "Diagnostics" } }, "type": "object", "title": "RecipeValidation", "description": "Persisted validation result, separate from derived Recipe projections.\n\n`diagnostics` carry the checker's per-file verdict detail (valid/invalid);\n`error_message` says why a `failed` attempt could not run, mirroring the\nRuntimeImageStatus + image_build_error_message pattern." }, "RecipeValidationDiagnostic": { "properties": { "code": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Code" }, "path": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Path" }, "span": { "anyOf": [ { "$ref": "#/components/schemas/RecipeValidationSpan" }, { "type": "null" } ] }, "message": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Message" }, "help": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ], "title": "Help" } }, "type": "object", "required": [ "code", "path", "message" ], "title": "RecipeValidationDiagnostic", "description": "Structured, user-facing diagnostic for committed Recipe content." }, "RecipeValidationSpan": { "properties": { "line": { "type": "integer", "minimum": 1, "title": "Line" }, "column": { "type": "integer", "minimum": 1, "title": "Column" } }, "type": "object", "required": [ "line", "column" ], "title": "RecipeValidationSpan", "description": "One-based source location for a validation diagnostic." }, "RecipeValidationStatus": { "type": "string", "enum": [ "pending", "valid", "invalid", "failed" ], "title": "RecipeValidationStatus", "description": "Lifecycle state for validation of an immutable Recipe pin." }, "RecipeValidationUpdate": { "properties": { "status": { "type": "string", "const": "pending", "title": "Status" } }, "type": "object", "required": [ "status" ], "title": "RecipeValidationUpdate", "description": "The only client-requestable validation transition.\n\nValidation results remain worker-owned. A client may reset the state to\npending to request a fresh attempt, but it cannot manufacture a terminal\nvalid, invalid, or failed result." }, "RepositoryProvider": { "type": "string", "enum": [ "github", "hosted" ], "title": "RepositoryProvider", "description": "Who serves a repository's Git, which decides how a client reaches it.\n\n`hosted` is served by the project's own data plane, so a runtime clones it\nwith its own session token and needs no third-party credential. `github`\nneeds an installation token from the integration the row names." }, "RepositoryProvisioningStatus": { "type": "string", "enum": [ "pending", "ready", "failed" ], "title": "RepositoryProvisioningStatus", "description": "Whether the hosted copy of a repository exists on its data plane." }, "RepositoryResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "integration_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Integration Id" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" }, "provider": { "$ref": "#/components/schemas/RepositoryProvider", "default": "github" }, "default_branch": { "type": "string", "title": "Default Branch", "default": "main" }, "provisioning_status": { "$ref": "#/components/schemas/RepositoryProvisioningStatus", "default": "pending" }, "seed_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seed Template" }, "clone_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clone Url", "description": "Hosted clone URL; derived from the deployment's Git origin" }, "created_at": { "type": "string", "title": "Created At" }, "is_recipe_source": { "type": "boolean", "title": "Is Recipe Source", "default": false } }, "type": "object", "required": [ "id", "project_id", "integration_id", "url", "name", "created_at" ], "title": "RepositoryResponse", "description": "Repository API response." }, "RepositoryUpdate": { "properties": { "default_branch": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Default Branch" } }, "type": "object", "title": "RepositoryUpdate", "description": "PATCH /v1/repositories/{id}.\n\n`seed_template` is deliberately absent: it records which template the first\ncommit came from, which is a thing that already happened once. Letting a\ncaller rewrite it would let the row describe a first commit that never\nexisted." }, "RunRequest": { "properties": { "identity": { "anyOf": [ { "$ref": "#/components/schemas/RunnerIdentity" }, { "type": "null" } ], "description": "Caller identity. A stable identity makes normal Runtime traffic eligible for experiment sampling and is required when targeting an Experiment directly. Normal Runtime traffic without one falls back to the active environment Runtime." }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ], "description": "Environment whose bindings apply. Human member sessions may override their credential environment; agent credentials remain environment-bound." }, "recipe_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Recipe Id", "description": "Select one Runtime version for initial task creation. The Recipe must belong to the Runtime group identified by the URL Runtime id. This bypasses automatic experiment and active-environment routing when the runner is minted; subsequent task runs retain the group's sticky/latest policy." }, "bindings_required": { "type": "boolean", "title": "Bindings Required", "description": "Require every application binding to materialize. Set false for operator testing where identity-dependent bindings may be reported as unavailable.", "default": true }, "caller": { "anyOf": [ { "$ref": "#/components/schemas/CallerContext" }, { "type": "null" } ], "description": "Optional caller environment payload (segment.io-style) — IP, user_agent, locale, library, page, plus any extra fields. Persisted on the session and stamped onto every task the runner spawns as `metadata.caller`. Not consulted by routing." }, "agent_name": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Agent Name", "description": "Optional entrypoint agent to run. Omit to use the runtime's default agent." }, "ttl_seconds": { "type": "integer", "maximum": 86400, "minimum": 60, "title": "Ttl Seconds", "description": "Runner JWT lifetime, default 1h, max 24h.", "default": 3600 }, "scope": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Scope", "description": "Space-separated scopes to mint onto the runner JWT, capped to the runner-grantable set (tasks/files/shares read+write, conversations:read, events:read, metrics:read, telemetry:write). Omit for the legacy full-access runner. Use a narrow scope when the runner token is handed to a browser." } }, "type": "object", "title": "RunRequest", "description": "Customer-facing body for `POST /v1/runtimes/{id}/run` and\n`POST /v1/experiments/{id}/run`.\n\nScope fields (org_id, project_id, member_id, task_id) come from\nauth and the URL — the customer only supplies their identity, an\noptional caller, and an optional TTL override. The route\nwraps this into a full `RuntimeContext` for the internal service\nlayer." }, "RunnerContextSummary": { "properties": { "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime row." }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Runtime group binding for latest/sticky resolution." }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Set when CP picked the arm via an experiment." }, "recipe_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Recipe Id", "description": "Recipe pin on the resolved runtime." }, "recipe_repository_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Recipe Repository Id", "description": "Repository the recipe lives in." }, "recipe_git_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Ref", "description": "Recipe git ref (e.g. 'main')." }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Pinned recipe commit sha." }, "arm_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arm Label", "description": "Operator-facing arm label, populated when via /experiments/{id}/run." }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name", "description": "Default entrypoint agent selected for this runner session." }, "identity": { "$ref": "#/components/schemas/RunnerIdentity", "description": "Identity the session is bound to (echo of the request input)." }, "caller": { "anyOf": [ { "$ref": "#/components/schemas/CallerContext" }, { "type": "null" } ], "description": "Echo of the caller's caller if one was supplied on the /run request. None when the request didn't include one." } }, "type": "object", "title": "RunnerContextSummary", "description": "Runtime context surfaced on `RunnerSpec.runtime_context`.\n\nMixes server-resolved fields (runtime_id, experiment_id, recipe,\narm_label) with caller-supplied echoes (identity, caller).\nAll runner-context-shaped fields live here so the SDK customer\nreads `runner.runtime_context.*` for everything related to this\nrunner's session.\n\nSnapshots the state at session-create time; not updated on refresh\n(the underlying session's runtime context is immutable once\ncreated)." }, "RunnerDeployment": { "properties": { "endpoint": { "type": "string", "title": "Endpoint", "description": "Public URL of the DP, e.g. `https://api.gcp01.introspection.dev`." }, "slug": { "type": "string", "title": "Slug", "description": "Short deployment identifier, e.g. `gcp01`." }, "region": { "type": "string", "title": "Region", "description": "Cloud region, e.g. `us-east-1`." } }, "type": "object", "required": [ "endpoint", "slug", "region" ], "title": "RunnerDeployment", "description": "Public deployment info surfaced on `RunnerSpec.deployment`.\n\nIdentifies the DP the runner is bound to. The SDK uses `endpoint`\nas the base URL for `runner.tasks.*` / `runner.files.*` calls;\n`slug` + `region` are surfaced for dashboard display and support\ntriage (\"which region did this runner land in?\"). Sensitive\ndeployment fields (config, JWT private key, cloud credentials)\nstay internal." }, "RunnerIdentity": { "properties": { "user_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User Id" }, "anonymous_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Anonymous Id" }, "conversation_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Conversation Id" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Tags to stamp on the `customer` member this identity mints, if it is new (docs/design/shared-tags.md §6). Access-bearing, so it is attenuated to the asserting agent member's own tags and applied on CREATE only — an existing member's tags are never changed here." } }, "type": "object", "title": "RunnerIdentity", "description": "Caller identity captured at session creation time.\n\nDrives consistent-hash routing for experiments and rides on the\nmaterialised access-token claims so DP can stamp it onto\n`task.metadata.identity` and forward as `TASK_USER_ID` /\n`TASK_ANONYMOUS_ID` / `TASK_CONVERSATION_ID` sandbox env. The\nharness picks it up as OTel resource attributes automatically." }, "RunnerSpec": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "UUID7, used as Redis key + AGENT_SESSION_ID" }, "deployment": { "$ref": "#/components/schemas/RunnerDeployment", "description": "DP the session is bound to. The SDK uses `deployment.endpoint` as the base URL for `runner.tasks.*` / `runner.files.*` calls. The customer never types a DP URL themselves — multi-DP routing falls out for free." }, "session_token": { "type": "string", "title": "Session Token", "description": "Signed session_locator JWT — the customer's long-lived credential. SDK sends it as `Authorization: Bearer ` on every `runner.tasks.*` / `runner.files.*` call. DP recognises `type=session_locator`, looks up the session in its Redis cache, and materialises a short-lived access token transparently via the existing session_materializer Restate path." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "Session expiration time" }, "runtime_context": { "$ref": "#/components/schemas/RunnerContextSummary", "description": "Resolved runtime + identity context. Populated by the runner /run routes; left as the default empty summary for gateway/channel session creators that don't carry a runtime context." } }, "type": "object", "required": [ "session_id", "deployment", "session_token", "expires_at" ], "title": "RunnerSpec", "description": "Response from `POST /v1/runtimes/{id}/run` and `/v1/experiments/{id}/run`.\n\nCustomer-facing wire shape. The SDK holds exactly one credential:\n`session_token`. DP transparently materialises the per-request\naccess tokens it needs via the existing session_materializer\nRestate path — the SDK doesn't see or manage them.\n\nSandbox-internal fields (access_token, refresh_token, egress\ncredentials map, sandbox bootstrap, DP-enforced limits, managed LLM\nproxy) live on `InternalRunnerSpec` and are only returned from\n`POST /internal/agent-sessions` on the CP→DP path. Keeping them\noff the customer wire means a leaked `RunnerSpec` JSON can't\nexpose materialised JWTs, upstream API keys, repo installation\nIDs, or LLM-spend authorization." }, "Runtime": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "The runtime group name; shared across versions." }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "kind": { "$ref": "#/components/schemas/RuntimeKind", "default": "byor" }, "llm_mode": { "$ref": "#/components/schemas/RuntimeLlmMode", "default": "managed" }, "config_json": { "additionalProperties": true, "type": "object", "title": "Config Json" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "recipe_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Recipe Id" }, "runtime_group_id": { "type": "string", "format": "uuid", "title": "Runtime Group Id" }, "slug": { "type": "string", "title": "Slug" }, "recipe_kind": { "$ref": "#/components/schemas/RuntimeRecipeKind", "default": "production" }, "recipe_ref": { "type": "string", "title": "Recipe Ref", "default": "main" }, "environments": { "items": { "$ref": "#/components/schemas/Environment" }, "type": "array", "title": "Environments" }, "image_build_status": { "$ref": "#/components/schemas/RuntimeImageStatus", "default": "pending" }, "image_build_error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Build Error Message" }, "image_build_metadata": { "$ref": "#/components/schemas/RuntimeImageBuildMetadata" }, "created_by_member_id": { "type": "string", "format": "uuid", "title": "Created By Member Id" }, "yanked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Yanked At" }, "yanked_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Yanked Reason" }, "environment_ref": { "anyOf": [ { "additionalProperties": { "type": "string" }, "propertyNames": { "$ref": "#/components/schemas/Environment" }, "type": "object" }, { "type": "null" } ], "title": "Environment Ref", "description": "Per-environment git ref each lane tracks ({environment: 'main' | 'pr/N' | }); a tracked lane auto-advances to the newest build from that ref and an absent key means untracked (projected from the runtime group, which is authoritative)." } }, "type": "object", "required": [ "org_id", "name", "project_id", "recipe_id", "runtime_group_id", "slug", "created_by_member_id" ], "title": "Runtime", "description": "Full Runtime schema with audit trail." }, "RuntimeCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "The runtime group name; shared across versions." }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "kind": { "$ref": "#/components/schemas/RuntimeKind", "default": "byor" }, "llm_mode": { "$ref": "#/components/schemas/RuntimeLlmMode", "default": "managed" }, "config_json": { "additionalProperties": true, "type": "object", "title": "Config Json" }, "project": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "uuid" } ], "title": "Project", "description": "Project slug or id this Runtime belongs to. Tenant-validated against the caller's org." }, "recipe_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Recipe Id" }, "slug": { "anyOf": [ { "type": "string", "maxLength": 63, "minLength": 1 }, { "type": "null" } ], "title": "Slug" }, "bootstrap": { "type": "boolean", "title": "Bootstrap", "description": "Create only the first live version of the resolved Runtime group. Used by zero-to-one setup; later Git-driven version creation omits it.", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "name", "project" ], "title": "RuntimeCreate", "description": "Schema for POST /v1/runtimes." }, "RuntimeImageBuildMetadata": { "properties": { "image_tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Tag" }, "built_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Built At" }, "size_bytes": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Size Bytes" }, "external_image_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Image Name" }, "external_artifacts": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "External Artifacts" } }, "type": "object", "title": "RuntimeImageBuildMetadata", "description": "Public details for the Runtime's currently projected image build.\n\nThe stored JSONB also carries an internal ``attempt_id`` ordering cursor.\nBaseSchema ignores that private key when producing the public Runtime\nresponse, while the DP projection request models it explicitly below." }, "RuntimeImageStatus": { "type": "string", "enum": [ "pending", "queued", "building", "ready", "failed" ], "title": "RuntimeImageStatus", "description": "Image build lifecycle, projected from the DP bake pipeline.\n\n``pending`` = no bake recorded yet; ``queued`` = a bake claim is waiting\nfor a bake-pool slot; ``building`` = the bake is executing; ``ready`` /\n``failed`` = terminal build outcomes. A dispatch cancelled before reaching\nthe bake gate projects back to ``pending``; a queued/building claim that\nexpires projects ``failed`` with its timeout reason. In either case the DP\nmay re-claim the content key on the next launch." }, "RuntimeKind": { "type": "string", "enum": [ "byor", "platform" ], "title": "RuntimeKind", "description": "Runtime delivery model." }, "RuntimeLlmMode": { "type": "string", "enum": [ "managed", "byok" ], "title": "RuntimeLlmMode", "description": "How a Runtime acquires LLM provider credentials at session create." }, "RuntimeRecipeKind": { "type": "string", "enum": [ "preview", "production" ], "title": "RuntimeRecipeKind", "description": "Git-backed recipe source for a Runtime deployment row." }, "RuntimeUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description" }, "llm_mode": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeLlmMode" }, { "type": "null" } ] }, "config_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config Json" }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ], "description": "Point an environment at this runtime, moving it off any sibling that currently serves it. Only 'staging' may be set manually; 'production' is managed by main-branch deployments." }, "yanked": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Yanked", "description": "Withdraw (true) or restore (false) this runtime. A yanked runtime is excluded from active-runtime resolution and forces sticky pins off it on their next run; in-flight runs are unaffected. Setting true stamps yanked_at=now(); false clears it." }, "yanked_reason": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Yanked Reason", "description": "Optional operator note recorded when yanking." }, "environment_ref": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "propertyNames": { "$ref": "#/components/schemas/Environment" }, "type": "object" }, { "type": "null" } ], "title": "Environment Ref", "description": "Per-environment git ref each lane tracks ({environment: 'main' | 'pr/N' | }). Merged onto the group's current map: a tracked lane auto-advances to the newest Runtime built from that ref, and a null value untracks that lane (pinning it to its selected version). Applies to the whole group, not a single version." } }, "type": "object", "title": "RuntimeUpdate", "description": "Schema for PATCH /v1/runtimes/{runtime_id}." }, "SlackChannel": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "is_private": { "type": "boolean", "title": "Is Private", "default": false }, "is_member": { "type": "boolean", "title": "Is Member", "default": false } }, "type": "object", "required": [ "id", "name" ], "title": "SlackChannel", "description": "Slack channel available to the connected app." }, "SlackChannelsResponse": { "properties": { "records": { "items": { "$ref": "#/components/schemas/SlackChannel" }, "type": "array", "title": "Records" } }, "type": "object", "required": [ "records" ], "title": "SlackChannelsResponse", "description": "Slack channel list response." }, "TelemetryGoalComponent": { "properties": { "source": { "type": "string", "const": "telemetry", "title": "Source", "default": "telemetry" }, "column": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Column" }, "aggregation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Aggregation" }, "weight": { "type": "number", "minimum": 0, "title": "Weight", "default": 1 }, "guard": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentGoalGuard" }, { "type": "null" } ] } }, "type": "object", "title": "TelemetryGoalComponent", "description": "Reserved typed shape for future telemetry-backed reward components." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } }, "tags": [ { "name": "projects", "description": "Project management", "x-displayName": "Projects" }, { "name": "recipes", "description": "Git-backed agent Recipe registrations (repo + ref pins built into Runtimes)", "x-displayName": "Recipes" }, { "name": "runtimes", "description": "Runtime deployments and runtime groups. Each version serves a set of environment lanes; a runtime group's `environment_ref` map sets the git ref each lane auto-advances from (a yanked runtime is never resolved).", "x-displayName": "Runtimes" }, { "name": "experiments", "description": "A/B bandit experiments across Runtime versions. Created as `draft` (routing not live) and route traffic only after start; require 2-20 arms in one runtime group and a `goal_json` with at least one positive-weight judge component.", "x-displayName": "Experiments" }, { "name": "judges", "description": "LLM-as-judge definitions — read/patch only. Judges are authored in the recipe repo and synced from git via runtime bootstrap; they cannot be created via POST.", "x-displayName": "Judges" }, { "name": "endpoints", "description": "Customer/partner endpoint registrations (LLM, MCP, utility) with header credentials", "x-displayName": "Endpoints" }, { "name": "integrations", "description": "Third-party integrations (GitHub, etc.)", "x-displayName": "Integrations" }, { "name": "api-keys", "description": "API key management for SDK/CLI access", "x-displayName": "API Keys" }, { "name": "repositories", "description": "Project repository linking", "x-displayName": "Repositories" }, { "name": "oauth", "description": "OAuth 2.0 endpoints: token exchange, the device-code flow, and the connector connect/broker surfaces under /v1/oauth/connections", "x-displayName": "Oauth" } ] }