{"openapi":"3.2.0","info":{"title":"Veryfront REST API reference","version":"1.0.0","description":"## Explore the API\n\n| API | Use it to |\n| --- | --- |\n| [Agents API](#tag/agents-api) | Define agents, tasks and workflows, and configure their prompts, skills, tools and resources. |\n| [Execution API](#tag/execution-api) | Start and monitor agent, task, and workflow runs. |\n| [Evaluations API](#tag/evaluations-api) | Define agent evaluations, run them, and inspect results. |\n| [AI Gateway API](#tag/ai-gateway-api) | Generate messages, responses, embeddings, and images. |\n| [Knowledge API](#tag/knowledge-api) | Store document metadata, index file chunks, and search project content. |\n| [Integrations API](#tag/integrations-api) | Connect external accounts, invoke integration tools, and configure messaging channels. |\n| [Projects API](#tag/projects-api) | Create projects and manage source files, branches, and uploads. |\n| [Deployment API](#tag/deployment-api) | Create releases and deploy them to project environments. |\n| [Sandbox API](#tag/sandbox-api) | Create isolated sessions, run commands, and manage files. |\n| [Cache API](#tag/cache-api) | Read and write cached values in project or user scope. |\n| [Observability API](#tag/observability-api) | Query logs, metrics, traces, and alerts to investigate application behavior. |\n| [Identity and Access API](#tag/identity-and-access-api) | Authenticate callers and manage account and project access. |\n| [Billing and Usage API](#tag/billing-and-usage-api) | Manage subscriptions, payments, credits, budgets, and usage. |\n\n[API discovery and metadata](#tag/api-discovery-and-metadata) · [OpenAPI specification (JSON)](/openapi.json)","contact":{"name":"Veryfront API Support","url":"https://veryfront.com/docs","email":"support@veryfront.com"},"x-api-id":"5f1f0b8a-6b0e-4c1a-9b35-0f3a1e6d84c7","x-audience":"external-public"},"components":{"schemas":{"RunStreamEvent":{"type":"object","properties":{"type":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":true},"RunStreamFrame":{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0,"description":"Durable reconnect cursor; null for transient frames."},"event_type":{"type":"string","minLength":1,"description":"Stored event type used for the SSE event name."},"payload":{"$ref":"#/components/schemas/RunStreamEvent"},"is_error":{"type":"boolean","description":"Error classification from the stored row."},"created_at":{"type":["string","null"],"description":"Stored timestamp; null when the frame has no stored timestamp."}},"required":["event_id","event_type","payload","is_error","created_at"],"additionalProperties":false},"ConversationRunStreamFrame":{"allOf":[{"$ref":"#/components/schemas/RunStreamFrame"},{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false}]},"CreateRunHeartbeatRequest":{"type":"object","properties":{"lease_duration_seconds":{"type":"integer","minimum":5,"maximum":300,"default":60}},"additionalProperties":false},"ProjectReference":{"type":"string"},"PaginationCursor":{"type":"string"},"PaginationLimit":{"type":"number","minimum":1,"maximum":100,"default":20},"ProjectConfig":{"type":"object","properties":{"disable_meta_robots":{"type":"boolean","description":"When true, the rendered site asks crawlers not to index it (noindex robots meta tag)."},"provider_id":{"type":["string","null"],"description":"Identifier of the provider backing the project, or null when none is configured. Not necessarily a UUID."},"layout_id":{"type":["string","null"],"description":"Identifier of the layout applied to the project, or null when none is configured."},"is_template":{"type":"boolean","description":"Whether the project is offered in the template gallery."},"coming_soon":{"type":"boolean","description":"Whether the template is listed as coming soon in the gallery."},"category":{"type":["string","null"],"description":"Template gallery category, or null when uncategorised."},"description":{"type":["string","null"],"description":"Template gallery description, or null when none is set."},"disableMetaRobots":{"type":"boolean","description":"Legacy camelCase spelling of `disable_meta_robots`; carries the same value. Prefer `disable_meta_robots`."},"providerId":{"type":["string","null"],"description":"Legacy camelCase spelling of `provider_id`; carries the same value. Prefer `provider_id`."},"layoutId":{"type":["string","null"],"description":"Legacy camelCase spelling of `layout_id`; carries the same value. Prefer `layout_id`."},"isTemplate":{"type":"boolean","description":"Legacy camelCase spelling of `is_template`; carries the same value. Prefer `is_template`."},"comingSoon":{"type":"boolean","description":"Legacy camelCase spelling of `coming_soon`; carries the same value. Prefer `coming_soon`."}},"additionalProperties":false,"description":"Project configuration. Field names use snake_case. Legacy camelCase aliases contain the same values."},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"slug":{"type":"string","example":"my-project"},"name":{"type":"string","example":"My Project"},"description":{"type":"string","example":"A sample project description"},"is_claimed":{"type":"boolean"},"features":{"type":"array","items":{"type":"string"}},"environments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"protected":{"type":"boolean"},"domains":{"type":"array","items":{"type":"string"}},"environment_variables":{"type":"array","items":{}},"active_release_id":{"type":["string","null"],"format":"uuid"},"server_hostname":{"type":["string","null"]}},"required":["id","name"]}},"releases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"export_status":{"type":"string"},"build_status":{"type":"string"},"deploy_status":{"type":"string"}},"required":["id","name"]}},"created_at":{"type":"string","example":"2024-01-15T10:30:00Z"},"updated_at":{"type":"string","example":"2024-01-15T10:30:00Z"},"published_at":{"type":"string"},"prompt_count":{"type":"number"},"config":{"$ref":"#/components/schemas/ProjectConfig"},"provider":{"type":["string","null"]},"layout":{"type":["string","null"]},"type":{"type":"string","enum":["regular","default","template"]},"system_managed":{"type":"boolean"},"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"avatar_src":{"type":"string"}},"required":["id"]}},"capabilities":{"type":"array","items":{"type":"string","enum":["project.read","project.settings.manage","project.delete","project.members.read","project.members.manage","project.invites.read","project.invites.manage","project.files.read","project.files.write","project.realtime.connect","project.realtime.write","project.files.admin","project.uploads.read","project.uploads.write","project.uploads.admin","project.knowledge.read","project.knowledge.write","project.releases.read","project.releases.write","project.deployments.read","project.deployments.write","project.deploy.execute","project.runtime.manage","project.sandboxes.manage","project.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.runs.admin","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","project.conversations.create","project.integrations.read","project.integrations.connect","project.integrations.configure","project.api_keys.read","project.api_keys.manage","project.cache.read","project.cache.write","project.logs.read","project.metrics.read","project.resources.read"]}},"capabilities_version":{"type":"integer"},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":["string","null"]},"color":{"type":["string","null"]}},"required":["id","namespace","key","value"]}}},"required":["id","slug","name"]},"PageInfo":{"type":"object","properties":{"self":{"type":["string","null"],"description":"Cursor pointing to the current page"},"first":{"type":"null","description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":["string","null"],"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":["string","null"],"description":"Cursor for the previous page (null if on first page)"}},"required":["self","first","next","prev"],"description":"Pagination cursor values for traversing the result set."},"Problem":{"type":"object","properties":{"cause":{"type":"string","enum":["schedule_concurrency_forbidden","schedule_fire_in_progress"],"description":"Schedule admission refusal."},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"],"description":"Replay status, retry timing, and recovery lookup."},"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-failed"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Failed"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"code":{"type":"string","description":"Stable machine-readable error code","example":"RUN_INVALID_INPUT"},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence","example":"The 'email' field must be a valid email address"},"instance":{"type":"string","description":"URI reference identifying the specific occurrence","example":"/projects/my-project/members"},"slug":{"type":"string","description":"Stable identifier for the problem type","example":"validation-failed"},"category":{"type":"string","enum":["AUTH","RESOURCE","VALIDATION","DATABASE","SUBSCRIPTION","INTEGRATION","INTERNAL"],"description":"API error category","example":"VALIDATION"},"suggestion":{"type":"string","description":"Suggested action to resolve the problem","example":"Check the request body and query parameters against the API documentation."},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field path that caused the error","example":"email"},"message":{"type":"string","description":"Error message for this field","example":"Invalid email format"},"code":{"type":"string","description":"Error code for this field","example":"INVALID_FORMAT"}},"required":["field","message"]},"description":"Detailed field-level errors for validation failures"}},"required":["type","title","status"]},"Label":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Label UUID."},"resource_kind":{"type":"string","enum":["project","project_agent"],"description":"Resource to which the label is assigned."},"project_id":{"type":"string","format":"uuid","description":"Project UUID containing the labeled resource."},"source_target_kind":{"type":["string","null"]},"source_agent_id":{"type":["string","null"]},"namespace":{"type":"string","description":"Normalized label namespace. API-created labels use user."},"key":{"type":"string","description":"Normalized lowercase label key."},"value":{"type":["string","null"],"description":"Trimmed label value, or null for a key-only label."},"color":{"type":["string","null"],"description":"Trimmed display color, or null when unset."},"created_at":{"type":"string","description":"Creation time as an ISO 8601 timestamp."},"updated_at":{"type":"string","description":"Last update time as an ISO 8601 timestamp."}},"required":["id","resource_kind","project_id","namespace","key","value","created_at","updated_at"]},"SubjectBudget":{"type":["object","null"],"properties":{"monthly_limit_usd":{"type":"number","description":"Monthly AI spend limit for this subject, in USD"},"monthly_limit_credits":{"type":"number","description":"The same limit in credits, the unit spend is counted in"}},"required":["monthly_limit_usd","monthly_limit_credits"],"description":"The subject’s monthly AI budget, or null if no budget is configured. Read-only; use `/budgets` to manage budgets."},"SubjectBudgetStatus":{"type":["object","null"],"properties":{"used":{"type":"number","description":"Credits the subject has spent since the budget month began"},"remaining":{"type":"number","description":"Credits remaining before the budget rejects further requests."},"resets_at":{"type":"string","description":"Budget reset time: midnight UTC on the first day of the next month."}},"required":["used","remaining","resets_at"],"description":"Usage against the budget for the current month, or null if the subject has no budget."},"ProjectDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"slug":{"type":"string","example":"my-project"},"name":{"type":"string","example":"My Project"},"description":{"type":"string","example":"A sample project description"},"is_claimed":{"type":"boolean"},"features":{"type":"array","items":{"type":"string"}},"environments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"protected":{"type":"boolean"},"domains":{"type":"array","items":{"type":"string"}},"environment_variables":{"type":"array","items":{}},"active_release_id":{"type":["string","null"],"format":"uuid"},"server_hostname":{"type":["string","null"]}},"required":["id","name"]}},"releases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"export_status":{"type":"string"},"build_status":{"type":"string"},"deploy_status":{"type":"string"}},"required":["id","name"]}},"created_at":{"type":"string","example":"2024-01-15T10:30:00Z"},"updated_at":{"type":"string","example":"2024-01-15T10:30:00Z"},"published_at":{"type":"string"},"prompt_count":{"type":"number"},"config":{"$ref":"#/components/schemas/ProjectConfig"},"provider":{"type":["string","null"]},"layout":{"type":["string","null"]},"type":{"type":"string","enum":["regular","default","template"]},"system_managed":{"type":"boolean"},"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"avatar_src":{"type":"string"}},"required":["id"]}},"capabilities":{"type":"array","items":{"type":"string","enum":["project.read","project.settings.manage","project.delete","project.members.read","project.members.manage","project.invites.read","project.invites.manage","project.files.read","project.files.write","project.realtime.connect","project.realtime.write","project.files.admin","project.uploads.read","project.uploads.write","project.uploads.admin","project.knowledge.read","project.knowledge.write","project.releases.read","project.releases.write","project.deployments.read","project.deployments.write","project.deploy.execute","project.runtime.manage","project.sandboxes.manage","project.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.runs.admin","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","project.conversations.create","project.integrations.read","project.integrations.connect","project.integrations.configure","project.api_keys.read","project.api_keys.manage","project.cache.read","project.cache.write","project.logs.read","project.metrics.read","project.resources.read"]}},"capabilities_version":{"type":"integer"},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":["string","null"]},"color":{"type":["string","null"]}},"required":["id","namespace","key","value"]}},"budget":{"$ref":"#/components/schemas/SubjectBudget"},"budget_status":{"$ref":"#/components/schemas/SubjectBudgetStatus"}},"required":["id","slug","name","budget","budget_status"]},"ProjectConfigInput":{"type":"object","properties":{"disable_meta_robots":{"type":"boolean","description":"When true, the rendered site asks crawlers not to index it (noindex robots meta tag)."},"provider_id":{"type":"string","description":"Identifier of the provider backing the project. Not necessarily a UUID."},"layout_id":{"type":"string","description":"Identifier of the layout applied to the project."},"is_template":{"type":"boolean","description":"Whether the project is offered in the template gallery."},"coming_soon":{"type":"boolean","description":"Whether the template is listed as coming soon in the gallery."},"category":{"type":"string","description":"Template gallery category."},"description":{"type":"string","description":"Template gallery description."},"disableMetaRobots":{"type":"boolean","description":"Legacy camelCase spelling of `disable_meta_robots`; carries the same value. Prefer `disable_meta_robots`."},"providerId":{"type":"string","description":"Legacy camelCase spelling of `provider_id`; carries the same value. Prefer `provider_id`."},"layoutId":{"type":"string","description":"Legacy camelCase spelling of `layout_id`; carries the same value. Prefer `layout_id`."},"isTemplate":{"type":"boolean","description":"Legacy camelCase spelling of `is_template`; carries the same value. Prefer `is_template`."},"comingSoon":{"type":"boolean","description":"Legacy camelCase spelling of `coming_soon`; carries the same value. Prefer `coming_soon`."}},"additionalProperties":false,"description":"Project configuration to update. Field names use snake_case. If a legacy camelCase alias is also supplied, its value must match the snake_case field. JSON-encoded strings are accepted for compatibility; new clients should send an object."},"ProjectUsage":{"type":"object","properties":{"storage":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"bandwidth":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"api_calls":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"custom_domains":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"code_exports":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"veryfront_badge":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"period_start":{"type":"string","description":"ISO timestamp for the start of the current billing period."},"period_end":{"type":"string","description":"ISO timestamp for the end of the current billing period."},"scope":{"type":"string","enum":["account"],"description":"The scope of the reported usage. Always `\"account\"`: values cover the project owner’s entire account for the current billing period, rather than this project alone."}},"required":["storage","bandwidth","api_calls","custom_domains","code_exports","veryfront_badge","period_start","period_end","scope"]},"UploadFolder":{"type":"object","properties":{"type":{"type":"string","enum":["folder"],"description":"Item type","example":"folder"},"path":{"type":"string","description":"Project-relative storage path, without a leading slash."},"visibility":{"type":"string","enum":["project","public","private"],"description":"Effective access policy for the upload or folder."},"permission":{"type":"string","enum":["read","write","admin"],"description":"The caller’s effective access to this item: read, write, or admin."},"created_at":{"type":"string","description":"Creation timestamp in ISO 8601 format."}},"required":["type","path","visibility","permission","created_at"]},"UploadFile":{"type":"object","properties":{"id":{"type":"string","description":"Upload UUID."},"path":{"type":"string","description":"Project-relative storage path, without a leading slash."},"file_name":{"type":"string","description":"File name from the upload record."},"content_type":{"type":["string","null"],"description":"Stored MIME type, or null when unspecified."},"size":{"type":"number","description":"Declared file size in bytes."},"url":{"type":["string","null"],"description":"API URL for downloading the upload; access depends on its visibility."},"status":{"type":"string","enum":["pending","active","failed"],"description":"Upload lifecycle state: pending until finalized, active when available, or failed."},"visibility":{"type":"string","enum":["project","public","private"],"description":"Effective access policy for the upload or folder."},"created_at":{"type":"string","description":"Creation timestamp in ISO 8601 format."},"updated_at":{"type":"string","description":"Last update timestamp in ISO 8601 format."},"deleted_at":{"type":["string","null"],"description":"Soft deletion timestamp in ISO 8601 format, or null for an undeleted upload."},"type":{"type":"string","enum":["file"],"description":"Item type","example":"file"},"permission":{"type":"string","enum":["read","write","admin"],"description":"The caller’s effective access to this item: read, write, or admin."}},"required":["id","path","file_name","content_type","size","url","status","visibility","created_at","updated_at","deleted_at","type","permission"]},"LegacyCompatibleProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"type":"object","properties":{"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}}}],"description":"Deprecated compatibility error value retained during REST Problem migration"},"message":{"type":"string","description":"Deprecated compatibility alias for detail retained during REST Problem migration"}}}]},"QuotaProblem":{"allOf":[{"$ref":"#/components/schemas/LegacyCompatibleProblem"},{"type":"object","properties":{"used":{"type":"number","description":"Current resource usage in the unit defined by the operation"},"limit":{"type":"number","description":"Configured resource limit in the unit defined by the operation"},"requested":{"type":"number","description":"Additional resource amount requested by the operation"}},"required":["used","limit","requested"]}]},"Release":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"version":{"type":["string","null"],"description":"Semver version, for example \"1.2.3\"."},"project_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"export_status":{"type":["string","null"],"enum":["in_progress","completed","error",null],"description":"Export outcome; null when no export status is recorded."},"build_status":{"type":["string","null"],"enum":["in_progress","completed","error",null],"description":"Build outcome; completion does not imply deployment. Null when no build status is recorded."},"deploy_status":{"type":["string","null"],"enum":["in_progress","completed","error",null],"description":"Recorded deployment outcome, or null when no deployment status is recorded."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"asset_manifest":{"type":["object","null"],"properties":{"state":{"type":"string","enum":["queued","building","partial","ready","failed","superseded"]},"manifest_version":{"type":"integer"}},"required":["state","manifest_version"],"description":"Release asset manifest state and version, or null when no manifest exists."}},"required":["id","name","project_id","export_status","build_status","deploy_status"]},"ReleaseVersionCreator":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"],"description":"Persisted creator, or null when historical attribution is missing."},"ReleaseVersion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"path":{"type":"string"},"entity":{"type":"string","format":"uuid","description":"File ID the version belongs to."},"date":{"type":"string","description":"Legacy alias for `created_at`."},"data":{"type":"string","description":"Legacy JSON-encoded version details. `JSON.parse(data).body` equals `content`."},"user_id":{"type":"string","format":"uuid","description":"Legacy alias for `created_by.id`. Omitted if no creator is recorded."},"content":{"type":"string","description":"File content of this version."},"created_at":{"type":"string","description":"ISO 8601 timestamp the version was created."},"created_by":{"$ref":"#/components/schemas/ReleaseVersionCreator"}},"required":["id","path","date","data","content","created_at","created_by"]},"ProjectMember":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]},"project_role":{"type":"string"},"avatar_src":{"type":["string","null"]},"resolved_capabilities":{"type":"array","items":{"type":"string","enum":["project.read","project.settings.manage","project.delete","project.members.read","project.members.manage","project.invites.read","project.invites.manage","project.files.read","project.files.write","project.realtime.connect","project.realtime.write","project.files.admin","project.uploads.read","project.uploads.write","project.uploads.admin","project.knowledge.read","project.knowledge.write","project.releases.read","project.releases.write","project.deployments.read","project.deployments.write","project.deploy.execute","project.runtime.manage","project.sandboxes.manage","project.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.runs.admin","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","project.conversations.create","project.integrations.read","project.integrations.connect","project.integrations.configure","project.api_keys.read","project.api_keys.manage","project.cache.read","project.cache.write","project.logs.read","project.metrics.read","project.resources.read"]}}},"required":["id","email","project_role","resolved_capabilities"]},"ProjectMemberDetail":{"allOf":[{"$ref":"#/components/schemas/ProjectMember"},{"type":"object","properties":{"budget":{"$ref":"#/components/schemas/SubjectBudget"},"budget_status":{"$ref":"#/components/schemas/SubjectBudgetStatus"}},"required":["budget","budget_status"]}]},"ErrorEnvelope":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}},"ChannelBinding":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"binding_id":{"type":"string","format":"uuid"},"installation_id":{"type":["string","null"],"format":"uuid"},"platform":{"type":"string","enum":["slack"]},"name":{"type":["string","null"]},"assistant_id":{"type":["string","null"],"minLength":1},"enabled":{"type":"boolean"},"platform_team_id":{"type":["string","null"]},"platform_bot_id":{"type":["string","null"]},"workspace_name":{"type":["string","null"]},"respond_to":{"type":"string","enum":["mentions","direct_messages","all"]},"allowed_channels":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["connected","needs_reauth","error"]},"welcome_message":{"type":["string","null"]},"error_message":{"type":["string","null"]},"max_response_tokens":{"type":["integer","null"],"exclusiveMinimum":0},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"},"resolved_target":{"type":"object","properties":{"runtime_target":{"type":"object","properties":{"kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"resolved_environment":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]}},"required":["id","name"]},"resolved_branch":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"resolved_deployment":{"type":["object","null"],"properties":{"id":{"type":"string"},"runtime_version":{"type":["string","null"]},"deployment_revision":{"type":["string","null"]},"last_deployed_at":{"type":["string","null"]}},"required":["id","runtime_version","deployment_revision","last_deployed_at"]},"resolved_managed_domain":{"type":["object","null"],"properties":{"domain":{"type":"string"},"health_url":{"type":["string","null"]}},"required":["domain","health_url"]},"resolved_invoke_mode":{"type":["string","null"],"enum":["dispatch_override","managed_domain",null]},"last_resolution_error":{"type":["object","null"],"properties":{"code":{"type":"string"},"retryable":{"type":"boolean"},"message":{"type":"string"}},"required":["code","retryable","message"]}},"required":["runtime_target","resolved_environment","resolved_branch","resolved_deployment","resolved_managed_domain","resolved_invoke_mode","last_resolution_error"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","platform","enabled","platform_team_id","platform_bot_id","respond_to","allowed_channels","status","runtime_target_kind","resolved_target","created_at","updated_at"]},"WebhookRun":{"type":"object","properties":{"webhook_event_id":{"type":"string","format":"uuid"},"webhook_definition_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"conversation_id":{"type":["string","null"],"format":"uuid"},"message_id":{"type":["string","null"],"format":"uuid"},"run_id":{"type":["string","null"]},"canonical_run_id":{"type":["string","null"],"format":"uuid"},"latest_event_id":{"type":["integer","null"],"minimum":0},"status":{"type":"string","enum":["received","queued","running","completed","failed","cancelled","ignored"],"description":"Webhook run status: received, queued, running, completed, failed, cancelled or ignored. A linked agent run overlays running (also while it waits for a tool), completed, failed or cancelled."},"duplicate":{"type":"boolean"},"payload":{},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"invoked_by":{"type":["string","null"]},"manual_invoked_by_user_id":{"type":["string","null"],"format":"uuid"},"received_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["webhook_event_id","webhook_definition_id","project_id","conversation_id","message_id","run_id","canonical_run_id","latest_event_id","status","duplicate","error_code","error_message","invoked_by","manual_invoked_by_user_id","received_at","completed_at"]},"OkResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]},"WebhookDeliveryEventListResponse":{"type":"object","properties":{"page_info":{"$ref":"#/components/schemas/PageInfo"},"events":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/WebhookRun"},{"type":"object","properties":{"created_at":{"type":"string"}},"required":["created_at"]}]}}},"required":["page_info","events"]},"PublicCatalogCapabilities":{"type":"object","properties":{"webResearch":{"type":"boolean","description":"Whether Studio default chat can enable live web research."},"streaming":{"type":"boolean","description":"Whether streaming responses are supported."},"tools":{"type":"boolean","description":"Whether tool calls are supported."},"vision":{"type":"boolean","description":"Whether image inputs are supported."},"thinking":{"type":"boolean","description":"Whether thinking/reasoning controls are supported."},"supported_parameters":{"type":"array","items":{"type":"string"},"description":"Supported request parameters, using OpenRouter names. Parameters not listed are removed or rejected. Parameters are listed only when support has been verified.","example":["max_tokens","temperature","top_p","tools","tool_choice"]},"reasoning":{"type":"boolean","description":"Whether the model reasons before answering."},"tool_call":{"type":"boolean","description":"Whether the model can call tools."},"temperature":{"type":"boolean","description":"Whether a caller-set temperature reaches the model."},"open_weights":{"type":"boolean","description":"Whether the model weights are publicly released."},"attachment":{"type":"boolean","description":"Whether file input is supported. Omitted if support has not been verified."},"structured_output":{"type":"boolean","description":"Whether schema-constrained output is supported. Omitted if support has not been verified."},"reasoning_mode":{"type":"string","description":"Supported reasoning control. Known values are `budget` and `adaptive`. Omitted if the model does not reason or support has not been verified. Clients must accept unknown values.","example":"budget"},"transport":{"type":"string","description":"OpenAI wire API the client must use. Known values: `chat-completions`, `responses`. Absent when unconstrained. Not a closed enum.","example":"chat-completions"},"reasoning_budget_tokens":{"type":"integer","exclusiveMinimum":0,"description":"Default thinking budget in tokens when the caller does not specify one. Omitted if no default is configured or the model does not accept a budget, including models without reasoning and models with adaptive thinking.","example":2048},"chat_completions_reasoning_with_function_tools":{"type":"boolean","description":"Whether `chat-completions` supports reasoning and function tools in the same request. If false, choose one. Omitted if support has not been verified.","example":false},"chat_completions_consecutive_system_messages":{"type":"boolean","description":"Whether `chat-completions` accepts consecutive system messages. If true, clients can send system instructions separately. Omitted if support has not been verified.","example":true},"modalities":{"type":"object","properties":{"input":{"type":"array","items":{"type":"string"},"description":"Input modalities.","example":["text","image"]}},"required":["input"],"description":"Supported input modalities. Output modalities are omitted because they have not been verified."},"limit":{"type":"object","properties":{"context":{"type":"integer","exclusiveMinimum":0,"description":"Context window in tokens: the provider's documented limit for the deployment Veryfront serves. Input plus requested output must fit within it. Absent while unevidenced.","example":1000000},"output":{"type":"integer","exclusiveMinimum":0,"description":"Maximum output tokens. Absent while unevidenced.","example":128000}},"description":"Known token ceilings. Each is absent while unevidenced; `limit` is absent while neither is known."}},"required":["webResearch","streaming","tools","vision","supported_parameters","reasoning","tool_call","temperature","open_weights","modalities"],"description":"Model capability flags"},"PublicCatalogPricing":{"type":"object","properties":{"inputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Input-token price, USD per 1M tokens. Use `inputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"outputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Output-token price, USD per 1M tokens. Use `outputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreationInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Default-retention cache-write input-token price, USD per 1M tokens. Use `cacheCreationInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreation1hInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. One-hour cache-write input-token price, USD per 1M tokens. Use `cacheCreation1hInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Cache-read input-token price, USD per 1M tokens. Use `cacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio input-token price, USD per 1M tokens. Use `audioInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioOutputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio output-token price, USD per 1M tokens. Use `audioOutputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioCacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio cache-read token price, USD per 1M tokens. Use `audioCacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"inputEurPer1M":{"type":"number","minimum":0,"description":"Input-token price. EUR per 1M tokens; see `fx`."},"outputEurPer1M":{"type":"number","minimum":0,"description":"Output-token price. EUR per 1M tokens; see `fx`."},"cacheCreationInputEurPer1M":{"type":"number","minimum":0,"description":"Default-retention cache-write input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"cacheCreation1hInputEurPer1M":{"type":"number","minimum":0,"description":"One-hour cache-write input-token price, when the provider bills it apart from the default cache write. EUR per 1M tokens; see `fx`."},"cacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioInputEurPer1M":{"type":"number","minimum":0,"description":"Audio input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioOutputEurPer1M":{"type":"number","minimum":0,"description":"Audio output-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioCacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."}},"required":["inputUsdPer1M","outputUsdPer1M","inputEurPer1M","outputEurPer1M"],"description":"Customer price after markup. Excludes provider cost and the markup amount."},"PublicCatalogProviderPricing":{"type":"object","properties":{"inputEurPer1M":{"type":"number","minimum":0,"description":"Input-token price. EUR per 1M tokens; see `fx`."},"outputEurPer1M":{"type":"number","minimum":0,"description":"Output-token price. EUR per 1M tokens; see `fx`."},"cacheCreationInputEurPer1M":{"type":"number","minimum":0,"description":"Default-retention cache-write input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"cacheCreation1hInputEurPer1M":{"type":"number","minimum":0,"description":"One-hour cache-write input-token price, when the provider bills it apart from the default cache write. EUR per 1M tokens; see `fx`."},"cacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioInputEurPer1M":{"type":"number","minimum":0,"description":"Audio input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioOutputEurPer1M":{"type":"number","minimum":0,"description":"Audio output-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioCacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable provider pricing tier identifier","example":"long-context"},"label":{"type":"string","description":"Human-readable pricing tier label","example":"Long context"},"appliesTo":{"type":"string","description":"Condition where this provider pricing tier applies.","example":"Prompts over 200k tokens"},"inputEurPer1M":{"type":"number","minimum":0,"description":"Input-token price. EUR per 1M tokens; see `fx`."},"outputEurPer1M":{"type":"number","minimum":0,"description":"Output-token price. EUR per 1M tokens; see `fx`."},"cacheCreationInputEurPer1M":{"type":"number","minimum":0,"description":"Default-retention cache-write input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"cacheCreation1hInputEurPer1M":{"type":"number","minimum":0,"description":"One-hour cache-write input-token price, when the provider bills it apart from the default cache write. EUR per 1M tokens; see `fx`."},"cacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioInputEurPer1M":{"type":"number","minimum":0,"description":"Audio input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioOutputEurPer1M":{"type":"number","minimum":0,"description":"Audio output-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioCacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."}},"required":["id","label","appliesTo","inputEurPer1M","outputEurPer1M"]},"description":"Provider pricing tiers that apply instead of the base prices under a condition"}},"required":["inputEurPer1M","outputEurPer1M"],"description":"What the provider charges Veryfront (our upstream cost), before markup, in EUR. For a host that invoices in EUR these are that host's published EUR list, unconverted and unrounded."},"PublicCatalogDeployment":{"type":"object","properties":{"tier":{"type":"string","description":"Residency tier of this deployment. Known values: `qualified-sovereign`, `eu-owned`, `eu-resident`, `standard`.","example":"eu-resident"},"jurisdiction":{"type":"string","description":"Legal domicile (ISO 3166-1 alpha-2) of the company operating the inference, or `unknown` where unevidenced. This is the operator's home country, NOT where inference is processed: an EU-resident deployment run by a US company reads `US`. Read `processing` for the location.","example":"US"},"region":{"type":"string","description":"Where inference is PROCESSED — not where the cloud resource was created. `eu` is an EU boundary (the EU Data Zone or an EU multi-region, depending on the host), `europe-west1` / `europe-west4` are single EU member-state regions, `global` means the route is worldwide and no region may be claimed, and `unknown` means unevidenced.","example":"europe-west1"},"processing":{"type":"string","description":"Where inference is processed, normalised from `region` and `tier`. Known values: `eu` (inside a recorded EU boundary), `us` (in the United States), `worldwide` (in any region the operator runs), `unknown` (no processing region is recorded for this route). An open string: tolerate values you have not seen.","example":"eu"},"processing_label":{"type":"string","description":"The processing location in words, for display, e.g. `EU (EEA + Switzerland data zone)`, `EU (europe-west1, Belgium)`, `United States`, `Worldwide (any region)`, `Unknown (processing region not recorded)`. Display text only: branch on `processing`.","example":"EU (europe-west1, Belgium)"},"operator":{"type":"string","description":"Legal entity operating the inference service for this deployment, e.g. `Microsoft Corporation`, `Google LLC`, `OpenAI`, `Scaleway SAS`, or `unknown` where unrecorded.","example":"Google LLC"},"quantization":{"type":"string","description":"Weight precision served. Known values: `bf16`, `fp16`, `fp8`, `fp4`, `nvfp4`, `int4`, `unknown`.","example":"unknown"},"precisionSource":{"type":"string","description":"How `quantization` is evidenced. Known values: `contractual`, `published`, `reported`, `unknown`.","example":"unknown"},"certifications":{"type":"array","items":{"type":"string"},"description":"Certifications evidenced for this deployment. Empty when none is recorded."},"supportedProviderTools":{"type":"array","items":{"type":"string"},"description":"Provider-executed agent tools this deployment supports.","example":["web_search"]},"dataRetention":{"anyOf":[{"type":"string"},{"type":"object","properties":{"days":{"type":"integer","minimum":0}},"required":["days"]}],"description":"Prompt retention on this deployment. Known values: `zero`, `metadata-only`, `unknown`, or `{ \"days\": N }`.","example":"unknown"},"pricing":{"$ref":"#/components/schemas/PublicCatalogPricing"}},"required":["tier","jurisdiction","region","processing","processing_label","operator","quantization","precisionSource","certifications","supportedProviderTools","dataRetention","pricing"],"description":"A model deployment, including its location, terms, and pricing."},"PublicCatalogModel":{"type":"object","properties":{"id":{"type":"string","description":"Model identifier.","example":"claude-sonnet-4-6"},"modelId":{"type":"string","description":"Unified model ID (provider/model).","example":"anthropic/claude-sonnet-4-6"},"provider":{"type":"string","description":"Provider name.","example":"anthropic"},"providerLabel":{"type":"string","description":"Public provider display name.","example":"Anthropic"},"providerLogoKey":{"type":"string","description":"Public provider logo key.","example":"anthropic"},"name":{"type":"string","description":"Display name.","example":"Claude Sonnet"},"description":{"type":"string","description":"Short description.","example":"Most efficient for everyday tasks"},"aliases":{"type":"array","items":{"type":"string"},"description":"Accepted aliases for backward-compatible model selection.","example":["sonnet","anthropic/claude-sonnet-4-6"]},"supportedProviderTools":{"type":"array","items":{"type":"string"},"description":"Provider-executed agent tools supported on the deployment a request for this model is served from.","example":["web_search","web_fetch"]},"temperature":{"type":["object","null"],"properties":{"min":{"type":"number","minimum":0,"description":"Minimum supported temperature."},"max":{"type":"number","minimum":0,"description":"Maximum supported temperature."}},"required":["min","max"],"description":"Per-model temperature limits; null when the runtime fixes or omits temperature."},"capabilities":{"$ref":"#/components/schemas/PublicCatalogCapabilities"},"pricing":{"$ref":"#/components/schemas/PublicCatalogPricing"},"providerPricing":{"$ref":"#/components/schemas/PublicCatalogProviderPricing"},"deployments":{"type":"array","items":{"$ref":"#/components/schemas/PublicCatalogDeployment"},"description":"Available deployments in routing preference order. Without a policy, requests use the first deployment."}},"required":["id","modelId","provider","providerLabel","providerLogoKey","name","aliases","supportedProviderTools","temperature","capabilities","pricing","providerPricing","deployments"],"description":"One publicly listed model"},"PublicModelCatalog":{"type":"object","properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/PublicCatalogModel"},"description":"Publicly listed AI models"},"providers":{"type":"array","items":{"type":"string"},"description":"Provider names represented in the catalog"},"defaultModelId":{"type":"string","description":"Default unified model ID recommended by the API","example":"mistral/mistral-small-2503"},"fx":{"type":"object","properties":{"base":{"type":"string","description":"The currency one unit of which `rate` prices","example":"EUR"},"quote":{"type":"string","description":"The currency `rate` is expressed in","example":"USD"},"rate":{"type":"number","exclusiveMinimum":0,"description":"1 `base` = `rate` `quote`","example":1.1403},"source":{"type":"string","description":"Where the rate is published","example":"ECB euro foreign exchange reference rate"},"date":{"type":"string","description":"The reference date of the rate (YYYY-MM-DD)","example":"2026-09-25"}},"required":["base","quote","rate","source","date"],"description":"1 `base` = `rate` `quote`. EUR prices converted from USD are the USD price divided by `rate`, rounded to 6 decimal places. For a host that invoices in EUR the EUR prices are that host's published EUR list, unconverted and unrounded."}},"required":["models","providers","defaultModelId","fx"],"description":"Public model catalog with customer pricing."},"AgentCardList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"provider":{"type":"object","properties":{"organization":{"type":"string"},"url":{"type":"string"}},"required":["organization","url"]},"version":{"type":"string"},"capabilities":{"type":"object","properties":{"streaming":{"type":"boolean"},"push_notifications":{"type":"boolean"},"extensions":{"type":"array","items":{"type":"string"}}},"required":["streaming","push_notifications","extensions"]},"default_input_modes":{"type":"array","items":{"type":"string"}},"default_output_modes":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["id","name"]}},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1},{"type":"object","properties":{"title":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1}},"required":["title","prompt"],"additionalProperties":false}]}},"kind":{"type":"string","enum":["source_project_agent","installed_project_agent"]},"can_run":{"type":"boolean"},"source_type":{"type":"string","enum":["project","catalog_install"]},"installed_access":{"type":"object","properties":{"grant_id":{"type":"string","format":"uuid"},"relation":{"type":"string","enum":["owner","admin","editor","viewer"]},"service_account_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["grant_id","relation","service_account_id","project_id","status"]},"runtime_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","offline","not_applicable","unknown"]},"reason":{"type":["string","null"]},"runtime_target_kind":{"type":["string","null"],"enum":["registered_push_service","pull_worker",null]},"runtime_service_key":{"type":["string","null"]}},"required":["status","reason","runtime_target_kind","runtime_service_key"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"avatar_url":{"type":["string","null"],"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":["string","null"]},"x-veryfront-url":{"type":"string"}},"required":["id","name","description","provider","version","capabilities","default_input_modes","default_output_modes","tools","skills","kind","can_run","source_type","source_path","edit_mode","x-veryfront-model","x-veryfront-url"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]},"SourcePrimitiveErrorEnvelope":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}},"source_path":{"type":"string"}}},"ProjectAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"model":{"type":["string","null"]},"system_prompt":{"type":["string","null"]},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budget_tokens":{"type":"number","exclusiveMinimum":0}},"required":["enabled"],"additionalProperties":false},"temperature":{"type":["number","null"],"minimum":0,"maximum":2},"max_steps":{"type":["integer","null"],"exclusiveMinimum":0},"allowed_models":{"type":"array","items":{"type":"string"}},"skill_ids":{"type":"array","items":{"type":"string"}},"skill_selection":{"type":"object","properties":{"kind":{"type":"string","enum":["omitted","explicit"]},"skill_ids":{"type":"array","items":{"type":"string"}}},"required":["kind","skill_ids"]},"all_tools_enabled":{"type":"boolean"},"tool_ids":{"type":"array","items":{"type":"string"}},"provider_tool_ids":{"type":"array","items":{"type":"string"}},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1},{"type":"object","properties":{"title":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1}},"required":["title","prompt"],"additionalProperties":false}]}},"avatar":{"type":["object","null"],"properties":{"seed":{"type":"string","minLength":1,"maxLength":128,"description":"The seed associated with this record."},"archetype":{"type":"string","enum":["upright","slumped","alert","profile","leaning","crouched","tall","spread","happy","sad","angry","surprised","sleepy","curious"],"description":"The archetype associated with this record."},"texture":{"type":"string","pattern":"^(?:[0-9]|none)$","description":"The texture associated with this record."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"The color associated with this record."},"shape":{"type":"string","enum":["snircle","circle","square"],"description":"The shape associated with this record."},"matrix":{"type":"string","pattern":"^[012]{16}$","description":"The matrix associated with this record."}},"description":"Structured avatar details associated with this record."},"avatar_url":{"type":["string","null"],"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"security_enabled":{"type":["boolean","null"],"description":"Whether the agent default security guardrails are enabled."},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","model","system_prompt","temperature","max_steps","allowed_models","skill_ids","skill_selection","all_tools_enabled","tool_ids","provider_tool_ids","security_enabled","source_path","source","edit_mode","source_only_reasons"]},"ProjectSkillDocument":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"allowed_tools":{"type":"array","items":{"type":"string"}},"owner_agent_id":{"type":"string"},"short_name":{"type":"string"},"instructions":{"type":"string","description":"The Markdown body of `SKILL.md`, excluding frontmatter."},"sections":{"type":"object","additionalProperties":{"type":"string"},"description":"Read-only sections derived from `## ` headings in the body. Empty if the body cannot be split into sections. Use `instructions` for the complete, authoritative body; this field cannot be updated."},"source":{"type":"string"},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","source_path","edit_mode","instructions","sections","source","source_only_reasons"]},"EvalSourceDocument":{"type":"object","properties":{"kind":{"type":"string","enum":["eval-source-document"]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"targetKind":{"type":"string","enum":["agent"]},"target":{"type":"string"},"source":{"type":"object","properties":{"filePath":{"type":"string"},"exportName":{"type":"string"},"content":{"type":"string"}},"required":["filePath","exportName"]},"dataset":{"type":"object","properties":{"kind":{"type":"string","enum":["inline","json","jsonl","dynamic"]},"path":{"type":"string"},"examples":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"input":{},"reference":{},"metadata":{"type":"object","additionalProperties":{}}},"required":["id"]}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["kind","editable","dynamic"]},"metrics":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"family":{"type":"string","enum":["answer","agent","ops","judge","knowledge","check"]},"severity":{"type":"string","enum":["gate","soft","budget"]},"threshold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"config":{"type":"object","additionalProperties":{}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["name","family","severity","editable","dynamic"]}},"repetitions":{"type":"integer","exclusiveMinimum":0},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{}},"editableFields":{"type":"array","items":{"type":"string","enum":["name","description","target","dataset","repetitions","tags","metadata","metrics","check"]}},"dynamicFields":{"type":"array","items":{"type":"string","enum":["name","description","target","dataset","repetitions","tags","metadata","metrics","check"]}},"capabilities":{"type":"array","items":{"type":"string","enum":["project.evals.read","project.evals.write","project.evals.run"]}}},"required":["kind","id","name","targetKind","target","source","dataset","metrics","repetitions","tags","metadata","editableFields","dynamicFields","capabilities"]},"HistoricalRunTarget":{"type":"object","properties":{"type":{"type":"string","enum":["agent","task","workflow","eval"],"description":"Execution definition type."},"id":{"type":["string","null"],"minLength":1,"maxLength":512,"pattern":"^\\S+$","description":"Definition ID; null when unavailable on a historical run."}},"required":["type","id"],"additionalProperties":false,"description":"Execution definition; its ID may be null only on historical runs.","x-ref-description":"Execution definition; its ID may be null only on historical runs."},"RunFailure":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":128,"description":"Stable failure code."},"message":{"type":"string","minLength":1,"maxLength":4000,"description":"Human-readable failure message."},"details":{"type":"object","additionalProperties":{"description":"Additional structured values supplied to the tool."},"description":"Additional failure details."}},"required":["code","message"],"additionalProperties":false,"description":"Failure details, present only when the run failed.","x-ref-description":"Failure details, present only when the run failed."},"RunLabels":{"type":"object","additionalProperties":{"type":"string","maxLength":256,"description":"Additional structured values supplied to the tool."},"description":"Labels used to organize runs.","maxProperties":50,"propertyNames":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_.-]+$"},"x-ref-description":"Labels used to organize runs."},"RunRuntime":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["main_branch"],"description":"Runtime selection kind."}},"required":["type"],"additionalProperties":false,"description":"Selected main-branch deployment."},{"type":"object","properties":{"type":{"type":"string","enum":["environment"],"description":"Runtime selection kind."},"id":{"type":"string","format":"uuid","description":"Environment UUID."}},"required":["type","id"],"additionalProperties":false,"description":"Selected environment."},{"type":"object","properties":{"type":{"type":"string","enum":["preview_branch"],"description":"Runtime selection kind."},"id":{"type":"string","format":"uuid","description":"Preview branch UUID."}},"required":["type","id"],"additionalProperties":false,"description":"Selected preview branch."},{"type":"object","properties":{"type":{"type":"string","enum":["registered"],"description":"Runtime selection kind."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Registered runtime identifier."}},"required":["type","id"],"additionalProperties":false,"description":"Selected registered runtime."}],"description":"Resolved logical runtime selection; main_branch identifies the selected main-branch deployment, not a worker process.","x-ref-description":"Resolved logical runtime selection; main_branch identifies the selected main-branch deployment, not a worker process."},"RunWait":{"oneOf":[{"type":"object","properties":{"resume_at":{"type":"string","format":"date-time","description":"Scheduled automatic resume time."},"reason":{"type":"string","enum":["manual_pause"],"description":"Condition required to resume the run."}},"required":["reason"],"description":"Waiting for manual resumption."},{"type":"object","properties":{"resume_at":{"type":"string","format":"date-time","description":"Scheduled automatic resume time."},"reason":{"type":"string","enum":["tool_result"],"description":"Condition required to resume the run."},"tool_call_id":{"type":"string","minLength":1,"maxLength":128,"description":"Tool call awaiting a result."}},"required":["reason","tool_call_id"],"description":"Waiting for a tool result."},{"type":"object","properties":{"resume_at":{"type":"string","format":"date-time","description":"Scheduled automatic resume time."},"reason":{"type":"string","enum":["integration_connected"],"description":"Condition required to resume the run."},"integration":{"type":"string","minLength":1,"maxLength":128,"description":"Integration awaiting connection."}},"required":["reason","integration"],"description":"Waiting for an integration connection."},{"type":"object","properties":{"resume_at":{"type":"string","format":"date-time","description":"Scheduled automatic resume time."},"reason":{"type":"string","enum":["approval"],"description":"Condition required to resume the run."},"wait_id":{"type":"string","minLength":1,"maxLength":128,"description":"Durable wait identifier."},"node_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"description":"Workflow nodes awaiting approval."}},"required":["reason","wait_id","node_ids"],"description":"Waiting for workflow approval."},{"type":"object","properties":{"resume_at":{"type":"string","format":"date-time","description":"Scheduled automatic resume time."},"reason":{"type":"string","enum":["event"],"description":"Condition required to resume the run."},"wait_id":{"type":"string","minLength":1,"maxLength":128,"description":"Durable wait identifier."},"name":{"type":"string","minLength":1,"maxLength":128,"description":"Event required to resume."}},"required":["reason","wait_id","name"],"description":"Waiting for a named event."},{"type":"object","properties":{"resume_at":{"type":"string","format":"date-time","description":"Scheduled automatic resume time."},"reason":{"type":"string","enum":["input_request"],"description":"Condition required to resume the run."},"input_request_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"description":"Input requests awaiting responses."}},"required":["reason","input_request_ids"],"description":"Waiting for input responses."},{"type":"object","properties":{"resume_at":{"type":"string","format":"date-time","description":"Scheduled automatic resume time."},"reason":{"type":"string","enum":["child_run"],"description":"Condition required to resume the run."},"dependencies":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid","description":"Canonical UUID of the child run."},"correlation":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["tool_call"],"description":"Child invocation kind."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Tool call identifier."}},"required":["type","id"],"additionalProperties":false,"description":"Child started by a tool call."},{"type":"object","properties":{"type":{"type":"string","enum":["workflow_node"],"description":"Child invocation kind."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Workflow node identifier."}},"required":["type","id"],"additionalProperties":false,"description":"Child started by a workflow node."}]}},"required":["run_id","correlation"],"additionalProperties":false},"minItems":1,"description":"Child runs that must finish."}},"required":["reason","dependencies"],"description":"Waiting for child runs."},{"type":"object","properties":{"resume_at":{"type":"string","format":"date-time","description":"Scheduled automatic resume time."},"reason":{"type":"string","enum":["timer"],"description":"Condition required to resume the run."}},"required":["resume_at","reason"],"description":"Waiting until the scheduled resume time."}],"description":"The current durable wait, with only the fields required to satisfy that wait."},"RunPause":{"type":"object","properties":{"requested_at":{"type":"string","format":"date-time","description":"Time the pause was requested."}},"required":["requested_at"],"additionalProperties":false,"description":"When a pause was requested; control.waiting confirms when execution is paused."},"RunCancellation":{"type":"object","properties":{"requested_at":{"type":"string","format":"date-time","description":"Time cancellation was requested."},"stopped_at":{"type":["string","null"],"format":"date-time","description":"Time the runtime confirmed its stop; null until confirmed."}},"required":["requested_at","stopped_at"]},"RunTrigger":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["api_key"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["service_account"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["system"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["schedule"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["webhook"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["agent"]},"id":{"type":"string","minLength":1,"maxLength":512,"pattern":"^\\S+$"},"tool_call_id":{"type":"string","minLength":1,"maxLength":128}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["task"]},"id":{"type":"string","minLength":1,"maxLength":512,"pattern":"^\\S+$"}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["workflow"]},"id":{"type":"string","minLength":1,"maxLength":512,"pattern":"^\\S+$"},"node_id":{"type":"string","minLength":1,"maxLength":128}},"required":["type","id"],"additionalProperties":false}],"description":"How execution was initiated.","x-ref-description":"How execution was initiated."},"TokenUsage":{"type":"object","properties":{"input":{"type":["integer","null"],"minimum":0,"description":"Input tokens excluding cache reads and writes.","format":"int64"},"output":{"type":["integer","null"],"minimum":0,"description":"Output tokens including reasoning.","format":"int64"},"cache":{"type":"object","properties":{"read":{"type":["integer","null"],"minimum":0,"description":"Tokens read from the provider cache.","format":"int64"},"write":{"type":["integer","null"],"minimum":0,"description":"Tokens written to the provider cache.","format":"int64"}},"required":["read","write"]},"reasoning":{"type":["integer","null"],"minimum":0,"description":"Reasoning tokens included in output.","format":"int64"},"total":{"type":["integer","null"],"minimum":0,"description":"Sum of input, output, cache-read and cache-write tokens.","format":"int64"}},"required":["input","output","cache","total"],"description":"Input excludes cache reads/writes; output includes reasoning. Total is input + output + cache.read + cache.write. Null means unknown, never zero."},"Cost":{"type":"object","properties":{"currency":{"type":"string","enum":["EUR"],"description":"Currency of reference usage value and provider costs."},"status":{"type":"string","enum":["estimated","posted","unavailable"],"description":"Whether charges are estimated, posted or unavailable."},"provider":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d{1,8})?$","description":"Recorded provider USD cost converted to EUR at the catalog reference rate; null when unknown."},"platform":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d{1,8})?$","description":"Reference usage value minus estimated provider cost; null when either amount is unknown."},"total":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d{1,8})?$","description":"Billed credits valued at EUR 0.10 per credit, independent of subscription or purchase discounts."},"credits":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d{1,8})?$","description":"Billed credit units."}},"required":["currency","status","provider","platform","total","credits"],"description":"Estimated EUR usage value before tax: total values billed credits at EUR 0.10 each; provider converts recorded USD cost at the catalog reference rate; platform is total minus provider and can be negative. These amounts are visible to authorized run readers and do not represent invoice charges or actual purchase prices. Descendants sum the same per-run amounts. Credits are exact billed units. Signed decimal strings have at most eight fractional digits. Unknown provider costs leave provider and platform null. Status is independent of token capture; unavailable requires all amounts null. Posted amounts come from the billing ledger and may change through later adjustments.","allOf":[{"if":{"properties":{"status":{"enum":["unavailable"]}},"required":["status"]},"then":{"properties":{"provider":{"type":"null"},"platform":{"type":"null"},"total":{"type":"null"},"credits":{"type":"null"}}},"else":{}}]},"Usage":{"type":"object","properties":{"tokens":{"$ref":"#/components/schemas/TokenUsage"},"cost":{"$ref":"#/components/schemas/Cost"},"model_calls":{"type":["integer","null"],"minimum":0,"description":"Billed provider call count.","format":"int64"},"capture_status":{"type":"string","enum":["complete","partial","missing"],"description":"Token capture coverage."}},"required":["tokens","cost","capture_status"],"description":"Usage when available; unknown measurements are null.","x-ref-description":"Usage when available; unknown measurements are null."},"RunArtifact":{"type":"object","properties":{"artifact_id":{"type":"string","minLength":1,"maxLength":128,"description":"Immutable artifact identifier."},"type":{"type":"string","minLength":1,"description":"Artifact kind."},"media_type":{"type":"string","minLength":1,"description":"File media type."},"size_bytes":{"type":"integer","minimum":0,"description":"File size in bytes."},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 digest of the file."},"href":{"type":"string","format":"uri","description":"Authorized artifact URL."}},"required":["artifact_id","type","media_type","size_bytes","sha256","href"],"description":"An immutable file reference authorized through the run’s project and conversation permissions."},"Run":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique run UUID."},"status":{"type":"string","enum":["pending","running","waiting","completed","failed","cancelled"],"description":"Current execution state."},"project_id":{"type":"string","format":"uuid","description":"Project containing the run."},"target":{"$ref":"#/components/schemas/HistoricalRunTarget"},"input":{"description":"Business input supplied when the run was created."},"output":{"description":"Final business output; null until successful finalization."},"error":{"$ref":"#/components/schemas/RunFailure"},"title":{"type":"string","description":"Display title, omitted when unset."},"labels":{"$ref":"#/components/schemas/RunLabels"},"parent_run_id":{"type":"string","format":"uuid","description":"Immediate parent run ID, present on child runs."},"root_run_id":{"type":"string","format":"uuid","description":"Top-level ancestor run ID, present on child runs."},"created_at":{"type":"string","format":"date-time","description":"When the run was accepted."},"updated_at":{"type":"string","format":"date-time","description":"When the resource last changed, including usage updates."},"started_at":{"type":"string","format":"date-time","description":"When the first execution attempt started, omitted before execution."},"finished_at":{"type":"string","format":"date-time","description":"When the run completed, failed or was cancelled."},"config":{"type":"object","additionalProperties":{"description":"A JSON value."},"description":"Definition-specific execution configuration."},"execution":{"type":"object","properties":{"runtime":{"$ref":"#/components/schemas/RunRuntime"},"timeout_seconds":{"type":"integer","exclusiveMinimum":0,"description":"Deadline for the whole run in seconds, measured from its first start and including retries."},"retry_limit":{"type":"integer","minimum":0,"description":"Maximum retries after the first attempt; only retryable failures are retried."},"attempt":{"type":"integer","minimum":1,"description":"Current or last execution attempt, starting at 1; absent before execution."},"exit_code":{"type":["integer","null"],"description":"Runtime process exit code, or null when no exit code was recorded."},"duration_ms":{"type":["integer","null"],"minimum":0,"description":"Elapsed time from first start to finish, including waits and retries; null when not finished.","format":"int64"},"tool_error_count":{"type":"integer","minimum":0,"description":"Recorded failed tool invocations during this run."},"logs":{"type":"string","description":"Captured runtime text logs, when available."},"start_mode":{"type":"string","description":"Recorded execution start mode, when available."}},"description":"Resolved execution settings and diagnostics."},"control":{"type":"object","properties":{"waiting":{"$ref":"#/components/schemas/RunWait"},"pause":{"$ref":"#/components/schemas/RunPause"},"cancellation":{"$ref":"#/components/schemas/RunCancellation"}},"description":"Pending control requests and the current wait."},"task_id":{"type":"string","minLength":1,"maxLength":200,"description":"Orchestration task ID, distinct from the execution definition."},"conversation_id":{"type":"string","format":"uuid","description":"Conversation containing the run."},"input_message_id":{"type":"string","format":"uuid","description":"Conversation message that supplied the input."},"output_message_id":{"type":"string","format":"uuid","description":"Conversation message containing the result."},"batch_id":{"type":"string","format":"uuid","description":"Batch containing the run."},"trigger":{"$ref":"#/components/schemas/RunTrigger"},"usage":{"$ref":"#/components/schemas/Usage"},"descendants":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total descendants at every depth."},"active":{"type":"integer","minimum":0,"description":"Descendants that are pending, running or waiting."},"has_failures":{"type":"boolean","description":"Whether any descendant has failed."},"usage":{"allOf":[{"$ref":"#/components/schemas/Usage"},{"description":"Aggregate usage of every descendant, excluding this run.","x-ref-description":"Aggregate usage of every descendant, excluding this run."}]}},"required":["total","active","has_failures"],"description":"Counts and usage across all descendant runs, excluding this run."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/RunArtifact"},"description":"Files produced by the run."},"schemas":{"type":"object","properties":{"input":{"type":["object","null"],"properties":{"schema":{"anyOf":[{"type":"boolean"},{"type":"object","additionalProperties":{"description":"A JSON value."}}],"description":"JSON Schema captured for this run; object schemas and boolean schemas are supported."},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 digest of the pinned schema."}},"required":["schema","sha256"]},"output":{"type":["object","null"],"properties":{"schema":{"anyOf":[{"type":"boolean"},{"type":"object","additionalProperties":{"description":"A JSON value."}}],"description":"JSON Schema captured for this run; object schemas and boolean schemas are supported."},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 digest of the pinned schema."}},"required":["schema","sha256"]}},"required":["input","output"],"description":"Pinned schemas for business input and output; null means no declared schema."},"metadata":{"type":"object","additionalProperties":{"description":"A JSON value."},"description":"Additional resource metadata."}},"required":["id","status","project_id","target","input","output","created_at","updated_at"],"description":"One execution resource returned by reads, creation, updates, and lifecycle actions. Omit irrelevant fields and empty groups. Errors appear only on failure; parent/root IDs only on child runs; timestamps appear when reached. Output is null until successful finalization.","allOf":[{"if":{"properties":{"status":{"enum":["failed"]}},"required":["status"]},"then":{"required":["error"]},"else":{"not":{"required":["error"]}}},{"if":{"properties":{"status":{"enum":["completed","failed","cancelled"]}},"required":["status"]},"then":{"required":["finished_at"]},"else":{"not":{"required":["finished_at"]}}},{"if":{"properties":{"status":{"enum":["pending","running","waiting","failed","cancelled"]}},"required":["status"]},"then":{"properties":{"output":{"type":"null"}}},"else":{}},{"if":{"properties":{"status":{"enum":["waiting"]}},"required":["status"]},"then":{"required":["control"],"properties":{"control":{"required":["waiting"]}}},"else":{"properties":{"control":{"not":{"required":["waiting"]}}}}},{"if":{"properties":{"control":{"required":["pause"]}},"required":["control"]},"then":{"properties":{"status":{"enum":["pending","running","waiting"]}}}},{"if":{"required":["trigger"],"properties":{"trigger":{"properties":{"type":{"enum":["agent","task","workflow"]}},"required":["type"]}}},"then":{"required":["parent_run_id","root_run_id"]}},{"if":{"properties":{"status":{"const":"completed"}},"required":["status"]},"then":{"properties":{"descendants":{"properties":{"active":{"const":0}}}}}}],"dependentRequired":{"parent_run_id":["root_run_id"],"root_run_id":["parent_run_id"]}},"RunAnalytics":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_runs":{"type":"number","description":"Total agent runs in the timeframe."},"completed_runs":{"type":"number","description":"Completed runs in the timeframe."},"failed_runs":{"type":"number","description":"Failed runs in the timeframe."},"average_duration_ms":{"type":["number","null"],"description":"Average finished run duration in milliseconds."},"p95_duration_ms":{"type":["number","null"],"description":"95th percentile finished run duration in milliseconds."},"last_run_at":{"type":["string","null"],"description":"Most recent run creation timestamp."}},"required":["total_runs","completed_runs","failed_runs","average_duration_ms","p95_duration_ms","last_run_at"]},"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Analytics aggregation granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of buckets returned."}},"required":["from","to","granularity","timezone","bucket_count"]},"series":{"type":"array","items":{"type":"object","properties":{"bucket_start":{"type":"string","description":"Bucket start timestamp."},"runs":{"type":"number","description":"Runs created in the bucket."},"completed_runs":{"type":"number","description":"Completed runs in the bucket."},"failed_runs":{"type":"number","description":"Failed runs in the bucket."}},"required":["bucket_start","runs","completed_runs","failed_runs"]}},"statuses":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","description":"Status or outcome label."},"count":{"type":"number","description":"Number of matching records."}},"required":["status","count"]}},"models":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","description":"AI provider."},"model":{"type":"string","description":"AI model identifier."},"count":{"type":"number","description":"Number of uses."}},"required":["provider","model","count"]}},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Recorded waiting tool name."},"count":{"type":"number","description":"Runs with this recorded waiting tool."}},"required":["name","count"]}},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"count":{"type":"number","description":"Number of matching records."}},"required":["project_id","project_name","project_slug","count"]}},"recent_runs":{"type":"array","items":{"$ref":"#/components/schemas/Run"}}},"required":["summary","timeframe","series","statuses","models","tools","projects","recent_runs"]},"TargetRunProblem":{"type":"object","properties":{"type":{"type":"string","description":"Problem type URI reference."},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599,"format":"int64"},"code":{"type":"string","minLength":1,"maxLength":128},"cause":{"type":"string","enum":["schedule_concurrency_forbidden","schedule_fire_in_progress"],"description":"Schedule admission refusal."},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}},"required":["field","message"]}}},"required":["type","title","status","code"]},"AccountWithMembership":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["personal","team"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"membership":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin"]},"capabilities":{"type":"array","items":{"type":"string","enum":["account.read","account.settings.manage","account.members.read","account.members.manage","account.invitations.read","account.invitations.manage","account.projects.read","account.projects.create","account.billing.read","account.billing.manage","account.ownership.transfer","account.delete"]}}},"required":["role","capabilities"]}},"required":["id","slug","name","kind","created_at","updated_at","membership"]},"AccountMember":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"email":{"type":"string"},"name":{"type":["string","null"]},"avatar_src":{"type":["string","null"]},"role":{"type":"string","enum":["owner","admin"]},"invited_by_user_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["user_id","email","name","avatar_src","role","invited_by_user_id","created_at","updated_at"]},"AccountInvitation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"account_id":{"type":"string","format":"uuid"},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin"]},"status":{"type":"string","enum":["pending","accepted","revoked","expired"],"description":"Pending invitations are reported as expired after `expires_at`."},"expires_at":{"type":"string"},"invited_by_user_id":{"type":["string","null"],"format":"uuid"},"accepted_by_user_id":{"type":["string","null"],"format":"uuid"},"resolved_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","account_id","email","role","status","expires_at","invited_by_user_id","accepted_by_user_id","resolved_at","created_at"]},"AccountInvitationCreated":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"account_id":{"type":"string","format":"uuid"},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin"]},"status":{"type":"string","enum":["pending","accepted","revoked","expired"],"description":"Pending invitations are reported as expired after `expires_at`."},"expires_at":{"type":"string"},"invited_by_user_id":{"type":["string","null"],"format":"uuid"},"accepted_by_user_id":{"type":["string","null"],"format":"uuid"},"resolved_at":{"type":["string","null"]},"created_at":{"type":"string"},"token":{"type":"string","description":"Raw acceptance token. Returned exactly once; the server stores only its hash."}},"required":["id","account_id","email","role","status","expires_at","invited_by_user_id","accepted_by_user_id","resolved_at","created_at","token"]},"AccountProject":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Project UUID."},"slug":{"type":"string","description":"Project slug."},"name":{"type":"string","description":"Project display name."},"account_id":{"type":"string","format":"uuid","description":"Account UUID to which this project is assigned."},"type":{"type":"string","enum":["regular","default","template"],"description":"Project classification: regular, default, or template."},"is_template":{"type":"boolean","description":"Whether the project is available as a template."},"system_managed":{"type":"boolean","description":"Whether the platform manages this project."},"created_at":{"type":"string","description":"Project creation timestamp in ISO 8601 UTC."},"updated_at":{"type":"string","description":"Project last-update timestamp in ISO 8601 UTC."}},"required":["id","slug","name","account_id","type","is_template","system_managed","created_at","updated_at"]},"ApiKeyInferenceLimitsSummary":{"type":["object","null"],"properties":{"allowed_models":{"type":["array","null"],"items":{"type":"string"}},"requests_per_minute":{"type":["integer","null"]},"updated_at":{"type":"string"}},"required":["allowed_models","requests_per_minute","updated_at"],"description":"The key's inference limits, or null when it carries none. Always null for an account key, and for a key on a project where the caller lacks `project.api_keys.read`. Read-only here; manage them through `/api-keys/{id}/limits`."},"ApiKeyInferenceLimits":{"type":"object","properties":{"api_key_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"configured":{"type":"boolean","description":"Whether the key carries limits. False means every limit below is a default."},"enforced":{"type":"boolean","description":"Whether the gateway enforces the key’s limits. If false, stored limits do not restrict requests."},"allowed_models":{"type":["array","null"],"items":{"type":"string"}},"requests_per_minute":{"type":["integer","null"]},"effective_allowed_models":{"type":["array","null"],"items":{"type":"string"},"description":"The key’s `allowed_models` after applying the project policy’s model restrictions. Other constraints, such as hosts, jurisdictions, and tier, apply to each request. Null if the key has no model list."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"updated_by":{"type":["string","null"],"format":"uuid"}},"required":["api_key_id","project_id","configured","enforced","allowed_models","requests_per_minute","effective_allowed_models","created_at","updated_at","updated_by"]},"ReplaceApiKeyInferenceLimitsRequest":{"type":"object","properties":{"allowed_models":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":200},"minItems":1,"maxItems":100,"description":"Allowed catalog model IDs from `GET /ai/models`. Aliases are normalized to `<vendor>/<model>`, and duplicates are removed. Retired models return `422` with a replacement; unknown models return `400`. Null or omitted means no model restriction. A model excluded by project policy can be stored, but is excluded from `effective_allowed_models` and rejected at request time."},"requests_per_minute":{"type":["integer","null"],"minimum":1,"maximum":10000,"description":"Inference requests this key may make per minute. Null or omitted: no rate limit."}},"additionalProperties":false},"IntegrationConnection":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"connection_generation_id":{"type":"string","format":"uuid"},"integration":{"type":"string"},"display_name":{"type":["string","null"]},"can_disconnect":{"type":"boolean"},"can_reconnect":{"type":"boolean"},"project":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["connected","expired","disconnected"]},"scope":{"type":"string","enum":["user"]},"user_id":{"type":"string","format":"uuid"}},"required":["id","connection_generation_id","integration","display_name","can_disconnect","can_reconnect","project","created_at","updated_at","status","scope","user_id"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"connection_generation_id":{"type":"string","format":"uuid"},"integration":{"type":"string"},"display_name":{"type":["string","null"]},"can_disconnect":{"type":"boolean"},"can_reconnect":{"type":"boolean"},"project":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["connected","expired","disconnected"]},"scope":{"type":"string","enum":["project"]},"user_id":{"type":"null"}},"required":["id","connection_generation_id","integration","display_name","can_disconnect","can_reconnect","project","created_at","updated_at","status","scope","user_id"]}]},"ConnectionList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationConnection"}},"page_info":{"$ref":"#/components/schemas/PageInfo"},"total":{"type":"integer","minimum":0}},"required":["data","page_info","total"]},"Environment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"protected":{"type":"boolean"},"domains":{"type":"array","items":{"type":"string"}},"environment_variables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"value":{"type":"string","enum":["********"]},"has_value":{"type":"boolean"}},"required":["id","key","value","has_value"]}},"deployment":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"release":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"export_status":{"type":["string","null"]},"build_status":{"type":["string","null"]},"deploy_status":{"type":["string","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","name","export_status","build_status","deploy_status","created_at","updated_at"]}},"required":["id","created_at","updated_at","release"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","project_id","domains","environment_variables"]},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"InferencePolicy":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"configured":{"type":"boolean"},"enforced":{"type":"boolean","description":"Whether routing applies every configured constraint. True for every readable policy: each configured constraint, the `eu-resident` minimum tier included, is enforced. False only if a stored tier or precision is unsupported by this API version; in that case, the gateway rejects all requests for the project."},"min_tier":{"type":["string","null"]},"min_quantization":{"type":["string","null"]},"allowed_jurisdictions":{"type":["array","null"],"items":{"type":"string"}},"allowed_host_ids":{"type":["array","null"],"items":{"type":"string"}},"denied_host_ids":{"type":["array","null"],"items":{"type":"string"}},"allowed_models":{"type":["array","null"],"items":{"type":"string"}},"denied_models":{"type":["array","null"],"items":{"type":"string"}},"standard_tier_opt_in_at":{"type":["string","null"]},"standard_tier_opt_in_by":{"type":["string","null"],"format":"uuid"},"standard_tier_opt_in_source":{"type":["string","null"],"description":"How standard-tier consent was recorded. `admin` indicates consent through this API. `grandfather` indicates a migration for projects using inference before the minimum tier was introduced. Null if no consent is recorded or if consent predates this field. Read-only."},"allow_non_eu_hosting":{"type":"boolean","description":"Whether this project has opted in to non-EU hosting: the standard-tier opt-in is recorded (POST /projects/{project_reference}/inference-policy/standard-tier-opt-in) and `min_tier` is `standard`, which drops the default `eu-resident` floor. False by default: a project is EU-only, and a `min_tier` of null is served as `eu-resident`. True does not mean the project is served outside the EU: its other constraints (for example `allowed_jurisdictions` or `allowed_host_ids`) may still restrict serving to the EU. Read-only; derived."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"updated_by":{"type":["string","null"],"format":"uuid"}},"required":["project_id","configured","enforced","min_tier","min_quantization","allowed_jurisdictions","allowed_host_ids","denied_host_ids","allowed_models","denied_models","standard_tier_opt_in_at","standard_tier_opt_in_by","standard_tier_opt_in_source","allow_non_eu_hosting","created_at","updated_at","updated_by"]},"ReplaceInferencePolicyRequest":{"type":"object","properties":{"min_tier":{"type":["string","null"],"enum":["qualified-sovereign","eu-owned","eu-resident","standard",null],"description":"Minimum sovereignty tier. Null is served as `eu-resident`: every project is EU-only by default. `standard` is the lowest tier and admits hosting outside the EU. Before setting `standard`, record consent through `POST /projects/{project_reference}/inference-policy/standard-tier-opt-in`; otherwise, the request returns `400`. After consent is recorded, `standard` can be set here."},"min_quantization":{"type":["string","null"],"enum":["bf16","fp16","fp8","nvfp4","fp4","int4",null]},"allowed_jurisdictions":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Z]{2}$"},"maxItems":500},"allowed_host_ids":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9][a-z0-9._/-]*$"},"maxItems":500},"denied_host_ids":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9][a-z0-9._/-]*$"},"maxItems":500},"allowed_models":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9][a-z0-9._/-]*$"},"maxItems":500},"denied_models":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9][a-z0-9._/-]*$"},"maxItems":500}},"additionalProperties":false},"ContentSearchResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"chunk":{"type":"object","properties":{"id":{"type":"string"},"file_path":{"type":"string"},"file_id":{"type":"string"},"file_version_id":{"type":"string"},"index":{"type":"number"},"content":{"type":"string"},"start_offset":{"type":"number"},"end_offset":{"type":"number"},"token_count":{"type":"number"},"metadata":{"type":"object","additionalProperties":{}}},"required":["id","file_path","file_version_id","index","content","start_offset","end_offset","token_count"]},"score":{"type":"number"},"match_type":{"type":"string","enum":["semantic","keyword","hybrid"]}},"required":["chunk","score","match_type"]},"description":"Vector search matches ordered by relevance."},"page_info":{"$ref":"#/components/schemas/PageInfo"},"search_time_ms":{"type":"number","description":"Server-side search duration in milliseconds."},"total_matches":{"type":"number","description":"Total number of matches reported by the search backend."}},"required":["data","page_info","search_time_ms","total_matches"],"example":{"data":[{"chunk":{"id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","file_path":"src/pages/index.tsx","file_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","file_version_id":"9b2f4c11-3c6a-4b0e-9d1f-2a7f3f6c8e10","index":0,"content":"export default function Home() {\n  return <main>Hello</main>\n}\n","start_offset":0,"end_offset":63,"token_count":18,"metadata":{"language":"tsx"}},"score":0.87,"match_type":"semantic"}],"page_info":{"self":null,"first":null,"next":null,"prev":null},"search_time_ms":42,"total_matches":1}},"ContentSearchBody":{"type":"object","properties":{"vector":{"type":"array","items":{"type":"number"},"minItems":768,"maxItems":4096,"description":"Pre-computed query embedding vector."},"dimension":{"anyOf":[{"type":"number","enum":[768]},{"type":"number","enum":[1024]},{"type":"number","enum":[1536]},{"type":"number","enum":[3072]},{"type":"number","enum":[4096]}],"description":"Embedding vector dimension: 768, 1024, 1536, 3072, or 4096."},"limit":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"Maximum search results to return, from 1 to 100."},"cursor":{"type":"string","description":"Opaque cursor returned from `page_info.next`."},"threshold":{"type":"number","minimum":0,"maximum":1,"default":0.7,"description":"Minimum similarity score for returned semantic matches."}},"required":["vector","dimension"],"example":{"vector":[0,0.4207,0.4546,0.0706,-0.3784,-0.4795,-0.1397,0.3285,0.4947,0.2061,-0.272,-0.5,-0.2683,0.2101,0.4953,0.3251,-0.144,-0.4807,-0.3755,0.0749,0.4565,0.4183,-0.0044,-0.4231,-0.4528,-0.0662,0.3813,0.4782,0.1355,-0.3318,-0.494,-0.202,0.2757,0.5,0.2645,-0.2141,-0.4959,-0.3218,0.1482,0.4819,0.3726,-0.0793,-0.4583,-0.4159,0.0089,0.4255,0.4509,0.0618,-0.3841,-0.4769,-0.1312,0.3351,0.4933,0.198,-0.2794,-0.4999,-0.2608,0.2181,0.4964,0.3184,-0.1524,-0.4831,-0.3696,0.0837,0.46,0.4134,-0.0133,-0.4278,-0.449,-0.0574,0.3869,0.4755,0.1269,-0.3384,-0.4926,-0.1939,0.2831,0.4998,0.257,-0.2221,-0.4969,-0.3149,0.1566,0.4842,0.3666,-0.088,-0.4617,-0.4109,0.0177,0.43,0.447,0.053,-0.3897,-0.4741,-0.1226,0.3416,0.4918,0.1898,-0.2867,-0.4996,-0.2532,0.226,0.4974,0.3115,-0.1608,-0.4853,-0.3636,0.0924,0.4634,0.4084,-0.0221,-0.4323,-0.445,-0.0486,0.3925,0.4727,0.1183,-0.3448,-0.491,-0.1857,0.2903,0.4994,0.2494,-0.23,-0.4978,-0.308,0.165,0.4863,0.3605,-0.0967,-0.4651,-0.4058,0.0265,0.4345,0.443,0.0442,-0.3952,-0.4713,-0.114,0.348,0.4901,0.1816,-0.2939,-0.4992,-0.2455,0.2339,0.4982,0.3045,-0.1692,-0.4873,-0.3574,0.1011,0.4667,0.4032,-0.031,-0.4367,-0.4409,-0.0398,0.3979,0.4698,0.1097,-0.3512,-0.4892,-0.1775,0.2975,0.4989,0.2416,-0.2378,-0.4986,-0.301,0.1733,0.4883,0.3543,-0.1054,-0.4682,-0.4006,0.0354,0.4388,0.4388,0.0354,-0.4006,-0.4682,-0.1054,0.3543,0.4883,0.1733,-0.301,-0.4986,-0.2378,0.2417,0.4989,0.2975,-0.1775,-0.4892,-0.3512,0.1097,0.4698,0.3979,-0.0398,-0.4409,-0.4366,-0.0309,0.4032,0.4667,0.1011,-0.3574,-0.4873,-0.1692,0.3045,0.4982,0.2339,-0.2455,-0.4992,-0.2939,0.1816,0.4901,0.348,-0.114,-0.4713,-0.3952,0.0442,0.443,0.4345,0.0265,-0.4058,-0.465,-0.0967,0.3605,0.4863,0.165,-0.308,-0.4978,-0.2299,0.2494,0.4994,0.2903,-0.1857,-0.491,-0.3448,0.1183,0.4727,0.3925,-0.0486,-0.445,-0.4323,-0.0221,0.4084,0.4634,0.0924,-0.3636,-0.4853,-0.1608,0.3115,0.4974,0.226,-0.2532,-0.4996,-0.2867,0.1898,0.4918,0.3416,-0.1226,-0.4741,-0.3897,0.053,0.447,0.43,0.0177,-0.4109,-0.4617,-0.088,0.3666,0.4842,0.1566,-0.315,-0.4969,-0.222,0.257,0.4998,0.283,-0.1939,-0.4926,-0.3384,0.1269,0.4755,0.3869,-0.0574,-0.449,-0.4278,-0.0133,0.4134,0.46,0.0837,-0.3696,-0.4831,-0.1524,0.3184,0.4964,0.2181,-0.2608,-0.4999,-0.2794,0.198,0.4933,0.3351,-0.1312,-0.4769,-0.3841,0.0618,0.4509,0.4254,0.0088,-0.4159,-0.4583,-0.0793,0.3726,0.4819,0.1482,-0.3218,-0.4959,-0.2141,0.2646,0.5,0.2757,-0.202,-0.494,-0.3318,0.1355,0.4782,0.3813,-0.0662,-0.4528,-0.4231,-0.0044,0.4183,0.4565,0.0749,-0.3755,-0.4807,-0.1439,0.3252,0.4953,0.2101,-0.2683,-0.5,-0.272,0.2061,0.4947,0.3285,-0.1397,-0.4795,-0.3784,0.0706,0.4547,0.4207,0,-0.4207,-0.4546,-0.0705,0.3784,0.4795,0.1397,-0.3285,-0.4947,-0.206,0.272,0.5,0.2683,-0.2101,-0.4953,-0.3251,0.144,0.4807,0.3755,-0.075,-0.4565,-0.4183,0.0044,0.4231,0.4528,0.0662,-0.3813,-0.4782,-0.1354,0.3318,0.494,0.202,-0.2757,-0.5,-0.2645,0.2141,0.4959,0.3218,-0.1482,-0.4819,-0.3725,0.0793,0.4583,0.4159,-0.0089,-0.4255,-0.4509,-0.0618,0.3841,0.4769,0.1312,-0.3351,-0.4933,-0.1979,0.2794,0.4999,0.2608,-0.2181,-0.4964,-0.3184,0.1524,0.4831,0.3696,-0.0837,-0.46,-0.4134,0.0133,0.4278,0.449,0.0574,-0.387,-0.4755,-0.1269,0.3384,0.4926,0.1939,-0.2831,-0.4998,-0.257,0.2221,0.4969,0.3149,-0.1566,-0.4842,-0.3666,0.0881,0.4617,0.4109,-0.0177,-0.43,-0.447,-0.053,0.3897,0.4741,0.1226,-0.3416,-0.4918,-0.1898,0.2867,0.4996,0.2532,-0.226,-0.4974,-0.3115,0.1608,0.4853,0.3636,-0.0924,-0.4634,-0.4084,0.0221,0.4323,0.445,0.0486,-0.3925,-0.4727,-0.1183,0.3449,0.491,0.1857,-0.2903,-0.4994,-0.2493,0.23,0.4978,0.308,-0.165,-0.4863,-0.3605,0.0968,0.4651,0.4058,-0.0266,-0.4345,-0.443,-0.0442,0.3952,0.4713,0.114,-0.3481,-0.4901,-0.1816,0.2939,0.4992,0.2455,-0.2339,-0.4982,-0.3045,0.1692,0.4873,0.3574,-0.1011,-0.4667,-0.4032,0.031,0.4367,0.4409,0.0398,-0.3979,-0.4698,-0.1097,0.3512,0.4892,0.1774,-0.2975,-0.4989,-0.2416,0.2378,0.4986,0.301,-0.1733,-0.4883,-0.3543,0.1054,0.4682,0.4006,-0.0354,-0.4388,-0.4388,-0.0353,0.4006,0.4682,0.1054,-0.3544,-0.4883,-0.1733,0.301,0.4986,0.2377,-0.2417,-0.4989,-0.2974,0.1775,0.4892,0.3512,-0.1097,-0.4698,-0.3979,0.0398,0.4409,0.4366,0.0309,-0.4032,-0.4666,-0.101,0.3575,0.4873,0.1691,-0.3045,-0.4982,-0.2338,0.2455,0.4992,0.2939,-0.1816,-0.4901,-0.348,0.1141,0.4713,0.3952,-0.0442,-0.443,-0.4345,-0.0265,0.4058,0.465,0.0967,-0.3605,-0.4863,-0.165,0.308,0.4978,0.2299,-0.2494,-0.4994,-0.2903,0.1857,0.491,0.3448,-0.1184,-0.4727,-0.3925,0.0486,0.445,0.4323,0.0221,-0.4084,-0.4634,-0.0924,0.3636,0.4853,0.1608,-0.3115,-0.4974,-0.226,0.2532,0.4996,0.2867,-0.1898,-0.4918,-0.3416,0.1227,0.4742,0.3897,-0.053,-0.447,-0.43,-0.0177,0.4109,0.4617,0.088,-0.3666,-0.4842,-0.1566,0.315,0.4969,0.222,-0.257,-0.4998,-0.283,0.1939,0.4926,0.3384,-0.1269,-0.4755,-0.3869,0.0574,0.449,0.4277,0.0132,-0.4134,-0.46,-0.0836,0.3696,0.4831,0.1524,-0.3184,-0.4964,-0.2181,0.2608,0.4999,0.2794,-0.198,-0.4933,-0.3351,0.1312,0.4769,0.3841,-0.0618,-0.4509,-0.4254,-0.0088,0.4159,0.4582,0.0793,-0.3726,-0.4819,-0.1482,0.3218,0.4959,0.2141,-0.2646,-0.5,-0.2757,0.202,0.494,0.3318,-0.1355,-0.4782,-0.3813,0.0662,0.4528,0.4231,0.0044,-0.4183,-0.4565,-0.0749,0.3755,0.4807,0.1439,-0.3252,-0.4953,-0.2101,0.2683,0.5,0.272,-0.2061,-0.4947,-0.3285,0.1397,0.4795,0.3784,-0.0706,-0.4547,-0.4207,0,0.4208,0.4546,0.0705,-0.3784,-0.4795,-0.1397,0.3285,0.4947,0.206,-0.272,-0.5,-0.2683,0.2101,0.4953,0.3251,-0.144,-0.4807,-0.3755,0.075,0.4565,0.4183,-0.0045,-0.4231,-0.4528,-0.0661,0.3813,0.4782,0.1354,-0.3318,-0.494,-0.202,0.2757,0.5,0.2645,-0.2141,-0.4959,-0.3217,0.1482,0.4819,0.3725,-0.0793,-0.4583,-0.4159,0.0089,0.4255,0.4509,0.0618,-0.3841,-0.4769,-0.1312,0.3351,0.4933,0.1979,-0.2794,-0.4999,-0.2607,0.2181],"dimension":768,"limit":10,"threshold":0.7}},"FileChunk":{"type":"object","properties":{"id":{"type":"string"},"file_path":{"type":"string"},"file_id":{"type":"string"},"file_version_id":{"type":"string"},"index":{"type":"number"},"content":{"type":"string"},"start_offset":{"type":"number"},"end_offset":{"type":"number"},"token_count":{"type":"number"},"source_checksum":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"},"embedding":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"string"},"model_provider":{"type":"string"},"dimension":{"type":"integer"},"vector":{"type":"array","items":{"type":"number"}},"created_at":{"type":"string"},"status":{"type":"string","enum":["ready","stale","missing"]}},"required":["id","model","status"]}},"required":["id","file_path","file_version_id","index","content","start_offset","end_offset","token_count","source_checksum","created_at"]},"FileChunkList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FileChunk"},"description":"File chunks in the requested branch, environment, or release context."},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]},"CommitConflictProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"versions":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string","format":"uuid"},"version_id":{"type":"string","format":"uuid"},"path":{"type":"string"}},"required":["version_id","path"]}},"conflicts":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string","format":"uuid"},"path":{"type":"string"},"error":{"type":"string"}},"required":["file_id","path","error"]}}},"required":["success","versions","conflicts"]}]},"Server":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"short_id":{"type":"string"},"user_id":{"type":"string","format":"uuid"},"environment_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"hostname":{"type":"string"},"status":{"type":"string","enum":["pending","provisioning","running","error","deleting"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","short_id","user_id","environment_ids","hostname","status","created_at","updated_at"]},"SandboxSession":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"short_id":{"type":"string"},"endpoint":{"type":"string"},"status":{"type":"string","enum":["pending","provisioning","running","error","deleting"]},"project_id":{"type":["string","null"],"format":"uuid"},"ttl_mode":{"type":"string","enum":["default","duration","always_on"]},"ttl_hours":{"type":["integer","null"],"exclusiveMinimum":0},"expires_at":{"type":["string","null"]},"created_at":{"type":"string"},"last_activity_at":{"type":["string","null"]}},"required":["id","short_id","endpoint","status","project_id","ttl_mode","ttl_hours","expires_at","created_at","last_activity_at"]},"AiGatewayError":{"type":"object","properties":{"error":{"type":"string","description":"Error message."},"code":{"type":"string","description":"Stable machine-readable error code."},"model":{"type":"string","maxLength":256,"description":"Requested model ID, on model-specific refusals."},"successor":{"type":"string","description":"The model that replaces a retired one, on `model_retired` refusals."},"retired_on":{"type":"string","description":"UTC date (YYYY-MM-DD) the model was retired, on `model_retired` refusals."},"allowed_models":{"type":"array","items":{"type":"string"},"description":"The models the calling API key may use, on `key-model-denied` refusals."}},"required":["error"]},"NeutralOpenAiError":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":["string","null"]},"code":{"type":["string","null"]},"veryfront":{"type":"object","additionalProperties":{}}},"required":["message","type","param","code"]}},"required":["error"]},"NeutralAnthropicError":{"type":"object","properties":{"type":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"veryfront":{"type":"object","additionalProperties":{}}},"required":["type","message"]}},"required":["type","error"]},"VeryfrontListedModelProcessing":{"type":"object","properties":{"processing":{"type":"string","description":"Where inference is processed: `eu`, `us`, `worldwide` or `unknown` (not recorded). An open string.","example":"eu"},"processing_label":{"type":"string","description":"The processing location in words, for display, e.g. `EU (EEA + Switzerland data zone)`.","example":"EU (EEA + Switzerland data zone)"}},"required":["processing","processing_label"]},"NeutralOpenAiModelList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["model"]},"created":{"type":"number"},"owned_by":{"type":"string"},"veryfront":{"$ref":"#/components/schemas/VeryfrontListedModelProcessing"}},"required":["id","object","created","owned_by","veryfront"]}}},"required":["object","data"]},"NeutralAnthropicModelList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["model"]},"id":{"type":"string"},"display_name":{"type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"veryfront":{"$ref":"#/components/schemas/VeryfrontListedModelProcessing"}},"required":["type","id","display_name","created_at","veryfront"]}},"has_more":{"type":"boolean"},"first_id":{"type":["string","null"]},"last_id":{"type":["string","null"]}},"required":["data","has_more","first_id","last_id"]},"NeutralGoogleError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"@type":{"type":"string","enum":["type.googleapis.com/google.rpc.ErrorInfo"]},"reason":{"type":"string"},"domain":{"type":"string"}},"required":["@type","reason","domain"]},{"type":"object","properties":{"@type":{"type":"string","enum":["type.googleapis.com/google.rpc.RetryInfo"]},"retryDelay":{"type":"string"}},"required":["@type","retryDelay"]},{"type":"object","properties":{"@type":{"type":"string","enum":["type.googleapis.com/google.rpc.QuotaFailure"]},"violations":{"type":"array","items":{"type":"object","properties":{"quotaId":{"type":"string"}},"required":["quotaId"]}}},"required":["@type","violations"]}]}},"veryfront":{"type":"object","additionalProperties":{}}},"required":["code","message","status"]}},"required":["error"]},"NeutralGoogleModelList":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"veryfront":{"$ref":"#/components/schemas/VeryfrontListedModelProcessing"}},"required":["name","displayName","veryfront"]}},"nextPageToken":{"type":"string"}},"required":["models"]},"GatewayBillingGroupFinalizeResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"billing_group_id":{"type":"string"},"already_finalized":{"type":"boolean"},"request_count":{"type":"integer","minimum":0},"charged_credits":{"type":"number","minimum":0},"target_credits":{"type":"number","minimum":0},"adjustment_credits":{"type":"number","minimum":0},"adjustment":{"type":"string","enum":["none","refund","spend"]},"provider_cost_usd":{"type":"number","minimum":0},"veryfront_charge_usd":{"type":"number","minimum":0},"veryfront_billed_usd":{"type":"number","minimum":0},"usage_capture_status":{"type":"string","enum":["complete"]}},"required":["ok","billing_group_id","already_finalized","request_count","charged_credits","target_credits","adjustment_credits","adjustment","provider_cost_usd","veryfront_charge_usd","veryfront_billed_usd","usage_capture_status"]},"GatewayBillingGroupFinalizeRequest":{"type":"object","properties":{"billing_group_id":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9._:-]+$"}},"required":["billing_group_id"]},"AgentPushRuntimeServiceResponse":{"type":"object","properties":{"service":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"service_name":{"type":"string","minLength":1,"maxLength":128},"service_key":{"type":"string","minLength":1,"maxLength":128},"scope_kind":{"type":"string","enum":["global","project"]},"scope_key":{"type":"string","minLength":1},"project_id":{"type":["string","null"],"format":"uuid"},"agent_id":{"type":["string","null"]},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{},"metadata":{},"managed_source":{"type":["object","null"],"properties":{"project_id":{"type":"string","format":"uuid"},"environment_id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"}},"required":["project_id","environment_id","release_id"],"additionalProperties":false},"version":{"type":["string","null"]},"runtime":{"type":["string","null"]},"region":{"type":["string","null"]},"last_heartbeat_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","service_name","service_key","scope_kind","scope_key","project_id","agent_id","base_url","invoke_url","status","managed_source","version","runtime","region","last_heartbeat_at","created_at","updated_at"]}},"required":["service"]},"ListRunEventTypesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"group":{"type":["string","null"],"minLength":1},"scope":{"type":"string","enum":["ag-ui","control-plane","extension"]},"event_class":{"type":"string","enum":["fact","delta"]},"status":{"type":"string","enum":["active","live_only","reserved","deprecated"]},"viewer_visibility":{"type":"string","enum":["full","sanitised","type_only"]},"description":{"type":"string","minLength":1},"fields":{"type":"array","items":{"type":"string","minLength":1}},"legacy_types":{"type":"array","items":{"type":"string","minLength":1}},"custom_names":{"type":"array","items":{"type":"string","minLength":1}}},"required":["type","name","group","scope","event_class","status","viewer_visibility","description","fields"],"additionalProperties":false}}},"required":["data"]},"RunEvent":{"oneOf":[{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["RUN_STARTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunStartedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_STARTED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["RUN_FINISHED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunFinishedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_FINISHED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["RUN_ERROR"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunErrorPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_ERROR"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TEXT_MESSAGE_START"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/TextMessageStartPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_START"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/TextMessageContentPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TEXT_MESSAGE_END"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/TextMessageEndPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_END"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_START"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallStartPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_START"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_ARGS"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallArgsPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_ARGS"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_CHUNK"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallChunkPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_CHUNK"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_END"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallEndPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_END"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_RESULT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallResultPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_RESULT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["STATE_SNAPSHOT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StateSnapshotPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_SNAPSHOT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["STATE_DELTA"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StateDeltaPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_DELTA"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["MESSAGES_SNAPSHOT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/MessagesSnapshotPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["MESSAGES_SNAPSHOT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["STEP_STARTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StepStartedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STEP_STARTED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["STEP_FINISHED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StepFinishedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STEP_FINISHED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["REASONING_START"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningStartPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_START"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["REASONING_MESSAGE_START"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningMessageStartPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_START"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["REASONING_MESSAGE_CONTENT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningMessageContentPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_CONTENT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["REASONING_MESSAGE_END"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningMessageEndPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_END"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["REASONING_CONTENT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningContentPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_CONTENT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["REASONING_END"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningEndPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_END"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["ACTIVITY_SNAPSHOT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ActivitySnapshotPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["ACTIVITY_SNAPSHOT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["ACTIVITY_DELTA"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ActivityDeltaPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["ACTIVITY_DELTA"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_AUTHORIZATION_SEALED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunAuthorizationSealedPayload"},{"$ref":"#/components/schemas/AgentRunAuthorizationSealedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_REQUEST_ENQUEUED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunRequestEnqueuedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_REQUEST_ENQUEUED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_DEFAULT_CHAT_START_ENQUEUED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunDefaultChatStartEnqueuedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_DEFAULT_CHAT_START_ENQUEUED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_SUBMITTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunToolResultSubmittedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_SUBMITTED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_DELIVERY_FAILED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunToolResultDeliveryFailedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_DELIVERY_FAILED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_INTEGRATION_CONNECTION_REFUSED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunIntegrationConnectionRefusedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_INTEGRATION_CONNECTION_REFUSED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_RUNTIME_OWNER_BOUND"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunRuntimeOwnerBoundPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_RUNTIME_OWNER_BOUND"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_RUNTIME_INVOKE_RETRIED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunRuntimeInvokeRetriedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_RUNTIME_INVOKE_RETRIED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_CONTEXT_COMPACTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunContextCompactedPayload"},{"$ref":"#/components/schemas/AgentRunContextCompactedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointedPayload"},{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointedPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_TURN_STARTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunProviderReplayTurnStartedPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayTurnStartedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_TURN_FINISHED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunProviderReplayTurnFinishedPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayTurnFinishedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunModelCallContextRecordedPayload"},{"$ref":"#/components/schemas/AgentRunModelCallContextRecordedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchAcceptedPayloadRead"},{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchAcceptedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_DETACHED_ACCEPTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunDetachedAcceptedPayload"},{"$ref":"#/components/schemas/AgentRunDetachedAcceptedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_INVOKE_AGENT_BILLING_MODE_RETAINED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunInvokeAgentBillingModeRetainedPayload"},{"$ref":"#/components/schemas/AgentRunInvokeAgentBillingModeRetainedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_BILLING_USAGE_RETAINED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunBillingUsageRetainedPayload"},{"$ref":"#/components/schemas/AgentRunBillingUsageRetainedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_REPLAYED_UPLOADS_SEALED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunReplayedUploadsSealedPayload"},{"$ref":"#/components/schemas/AgentRunReplayedUploadsSealedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallStatusChangedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["INPUT_REQUEST_CREATED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/InputRequestCreatedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_CREATED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/InputRequestUpdatedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ChildRunStatusChangedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["MODEL_CALL_COMPLETED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ModelCallCompletedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["MODEL_CALL_COMPLETED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["RUN_PARKED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunParkedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_PARKED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["RUN_LOG_CAPTURED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunLogCapturedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_LOG_CAPTURED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StreamHeartbeatEmittedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["URL_CITED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/UrlCitedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["URL_CITED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["DOCUMENT_CITED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/DocumentCitedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["DOCUMENT_CITED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["FILE_ATTACHED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/FileAttachedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["FILE_ATTACHED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["FILES_CHANGED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/FilesChangedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["FILES_CHANGED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RuntimeEventRecordedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchReceiptPayload"},{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchReceiptPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointPayload"},{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunModelCallContextPayload"},{"$ref":"#/components/schemas/AgentRunModelCallContextPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","not":{"enum":["RUN_STARTED","RUN_FINISHED","RUN_ERROR","TEXT_MESSAGE_START","TEXT_MESSAGE_CONTENT","TEXT_MESSAGE_END","TOOL_CALL_START","TOOL_CALL_ARGS","TOOL_CALL_CHUNK","TOOL_CALL_END","TOOL_CALL_RESULT","STATE_SNAPSHOT","STATE_DELTA","MESSAGES_SNAPSHOT","STEP_STARTED","STEP_FINISHED","REASONING_START","REASONING_MESSAGE_START","REASONING_MESSAGE_CONTENT","REASONING_MESSAGE_END","REASONING_CONTENT","REASONING_END","ACTIVITY_SNAPSHOT","ACTIVITY_DELTA","AGENT_RUN_AUTHORIZATION_SEALED","AGENT_RUN_REQUEST_ENQUEUED","AGENT_RUN_DEFAULT_CHAT_START_ENQUEUED","AGENT_RUN_TOOL_RESULT_SUBMITTED","AGENT_RUN_TOOL_RESULT_DELIVERY_FAILED","AGENT_RUN_INTEGRATION_CONNECTION_REFUSED","AGENT_RUN_RUNTIME_OWNER_BOUND","AGENT_RUN_RUNTIME_INVOKE_RETRIED","AGENT_RUN_CONTEXT_COMPACTED","AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED","AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED","AGENT_RUN_PROVIDER_REPLAY_TURN_STARTED","AGENT_RUN_PROVIDER_REPLAY_TURN_FINISHED","AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED","AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED","AGENT_RUN_DETACHED_ACCEPTED","AGENT_RUN_INVOKE_AGENT_BILLING_MODE_RETAINED","AGENT_RUN_BILLING_USAGE_RETAINED","AGENT_RUN_REPLAYED_UPLOADS_SEALED","TOOL_CALL_STATUS_CHANGED","INPUT_REQUEST_CREATED","INPUT_REQUEST_UPDATED","CHILD_RUN_STATUS_CHANGED","MODEL_CALL_COMPLETED","RUN_PARKED","RUN_LOG_CAPTURED","STREAM_HEARTBEAT_EMITTED","URL_CITED","DOCUMENT_CITED","FILE_ATTACHED","FILES_CHANGED","RUNTIME_EVENT_RECORDED","AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT","AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT","AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT","AGENT_RUN_MODEL_CALL_CONTEXT"]}},"payload":{"description":"Payload of an unrecognized historical or future event."},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false}]},"RunsPageInfo":{"type":"object","properties":{"next":{"type":["string","null"]}},"required":["next"],"description":"Opaque cursor for the next page; null means there are no more results."},"ListRunEventsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunEvent"}},"page_info":{"$ref":"#/components/schemas/RunsPageInfo"}},"required":["data","page_info"]},"AppendRunEventsResponse":{"type":"object","properties":{"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"appended_count":{"type":"integer","minimum":0},"run_id":{"type":"string","format":"uuid"}},"required":["latest_event_id","appended_count","run_id"]},"AppendRunEventsRequest":{"type":"object","properties":{"expected_previous_event_id":{"type":["integer","null"],"minimum":0},"expected_previous_external_event_sequence":{"type":["integer","null"],"minimum":0},"external_sequence_scope":{"type":"string","enum":["agent","publish_only"]},"events":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TextMessageStartPayload"},{"$ref":"#/components/schemas/TextMessageContentPayload"},{"$ref":"#/components/schemas/TextMessageEndPayload"},{"$ref":"#/components/schemas/ToolCallStartPayload"},{"$ref":"#/components/schemas/ToolCallArgsPayload"},{"$ref":"#/components/schemas/ToolCallChunkPayload"},{"$ref":"#/components/schemas/ToolCallEndPayload"},{"$ref":"#/components/schemas/ToolCallResultPayload"},{"$ref":"#/components/schemas/MessagesSnapshotPayload"},{"$ref":"#/components/schemas/StateSnapshotPayload"},{"$ref":"#/components/schemas/StateDeltaPayload"},{"$ref":"#/components/schemas/RunStartedPayload"},{"$ref":"#/components/schemas/RunFinishedPayload"},{"$ref":"#/components/schemas/RunErrorPayload"},{"$ref":"#/components/schemas/StepStartedPayload"},{"$ref":"#/components/schemas/StepFinishedPayload"},{"$ref":"#/components/schemas/ReasoningStartPayload"},{"$ref":"#/components/schemas/ReasoningMessageStartPayload"},{"$ref":"#/components/schemas/ReasoningMessageContentPayload"},{"$ref":"#/components/schemas/ReasoningMessageEndPayload"},{"$ref":"#/components/schemas/ReasoningContentPayload"},{"$ref":"#/components/schemas/ReasoningEndPayload"},{"$ref":"#/components/schemas/ActivitySnapshotPayload"},{"$ref":"#/components/schemas/ActivityDeltaPayload"},{"$ref":"#/components/schemas/ToolCallStatusChangedPayload"},{"$ref":"#/components/schemas/InputRequestCreatedPayload"},{"$ref":"#/components/schemas/InputRequestUpdatedPayload"},{"$ref":"#/components/schemas/ChildRunStatusChangedPayload"},{"$ref":"#/components/schemas/ModelCallCompletedPayload"},{"$ref":"#/components/schemas/RunParkedPayload"},{"$ref":"#/components/schemas/RunLogCapturedPayload"},{"$ref":"#/components/schemas/StreamHeartbeatEmittedPayload"},{"$ref":"#/components/schemas/UrlCitedPayload"},{"$ref":"#/components/schemas/DocumentCitedPayload"},{"$ref":"#/components/schemas/FileAttachedPayload"},{"$ref":"#/components/schemas/FilesChangedPayload"},{"$ref":"#/components/schemas/RuntimeEventRecordedPayload"},{"$ref":"#/components/schemas/AgentRunContextCompactedPayload"},{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchAcceptedPayload"},{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchReceiptPayload"},{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointedPayload"},{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointedPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointPayload"},{"$ref":"#/components/schemas/AgentRunModelCallContextRecordedPayload"},{"$ref":"#/components/schemas/AgentRunModelCallContextPayload"}]},"minItems":1,"maxItems":100}},"required":["events"]},"RunEventSummary":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid"},"total":{"type":"integer","minimum":0},"error_count":{"type":"integer","minimum":0},"first_event_id":{"type":["integer","null"],"minimum":0},"last_event_id":{"type":["integer","null"],"minimum":0},"first_event_at":{"type":["string","null"],"format":"date-time"},"last_event_at":{"type":["string","null"],"format":"date-time"},"by_event_class":{"type":"object","properties":{"fact":{"type":"integer","minimum":0},"delta":{"type":"integer","minimum":0}},"required":["fact","delta"],"additionalProperties":false},"by_event_type":{"type":"array","items":{"type":"object","properties":{"event_type":{"type":"string","minLength":1},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"count":{"type":"integer","minimum":0},"error_count":{"type":"integer","minimum":0}},"required":["event_type","event_class","count","error_count"],"additionalProperties":false}},"buckets":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"count":{"type":"integer","minimum":0},"error_count":{"type":"integer","minimum":0}},"required":["start","end","count","error_count"],"additionalProperties":false},"description":"Half-open time buckets `[start, end)` covering `first_event_at` through `last_event_at + 1 ms`. Boundaries use whole milliseconds; widths differ by at most 1 ms. Boundaries can be passed directly as the event-list `start` and `end` filters. The bucket count cannot exceed the span in milliseconds. Empty if no events match."}},"required":["run_id","total","error_count","first_event_id","last_event_id","first_event_at","last_event_at","by_event_class","by_event_type","buckets"],"additionalProperties":false},"RunSnapshotEvent":{"oneOf":[{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["RUN_STARTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunStartedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_STARTED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["RUN_FINISHED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunFinishedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_FINISHED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["RUN_ERROR"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunErrorPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_ERROR"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TEXT_MESSAGE_START"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/TextMessageStartPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_START"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/TextMessageContentPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TEXT_MESSAGE_END"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/TextMessageEndPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_END"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_START"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallStartPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_START"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_ARGS"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallArgsPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_ARGS"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_CHUNK"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallChunkPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_CHUNK"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_END"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallEndPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_END"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_RESULT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallResultPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_RESULT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["STATE_SNAPSHOT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StateSnapshotPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_SNAPSHOT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["STATE_DELTA"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StateDeltaPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_DELTA"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["MESSAGES_SNAPSHOT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/MessagesSnapshotPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["MESSAGES_SNAPSHOT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["STEP_STARTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StepStartedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STEP_STARTED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["STEP_FINISHED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StepFinishedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STEP_FINISHED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["REASONING_START"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningStartPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_START"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["REASONING_MESSAGE_START"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningMessageStartPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_START"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["REASONING_MESSAGE_CONTENT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningMessageContentPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_CONTENT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["REASONING_MESSAGE_END"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningMessageEndPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_END"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["REASONING_CONTENT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningContentPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_CONTENT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["REASONING_END"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ReasoningEndPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_END"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["ACTIVITY_SNAPSHOT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ActivitySnapshotPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["ACTIVITY_SNAPSHOT"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["ACTIVITY_DELTA"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ActivityDeltaPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["ACTIVITY_DELTA"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_AUTHORIZATION_SEALED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunAuthorizationSealedPayload"},{"$ref":"#/components/schemas/AgentRunAuthorizationSealedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_REQUEST_ENQUEUED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunRequestEnqueuedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_REQUEST_ENQUEUED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_DEFAULT_CHAT_START_ENQUEUED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunDefaultChatStartEnqueuedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_DEFAULT_CHAT_START_ENQUEUED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_SUBMITTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunToolResultSubmittedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_SUBMITTED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_DELIVERY_FAILED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunToolResultDeliveryFailedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_DELIVERY_FAILED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_INTEGRATION_CONNECTION_REFUSED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunIntegrationConnectionRefusedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_INTEGRATION_CONNECTION_REFUSED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_RUNTIME_OWNER_BOUND"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunRuntimeOwnerBoundPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_RUNTIME_OWNER_BOUND"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_RUNTIME_INVOKE_RETRIED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunRuntimeInvokeRetriedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_RUNTIME_INVOKE_RETRIED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_CONTEXT_COMPACTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunContextCompactedPayload"},{"$ref":"#/components/schemas/AgentRunContextCompactedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointedPayload"},{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointedPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_TURN_STARTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunProviderReplayTurnStartedPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayTurnStartedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_TURN_FINISHED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunProviderReplayTurnFinishedPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayTurnFinishedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunModelCallContextRecordedPayload"},{"$ref":"#/components/schemas/AgentRunModelCallContextRecordedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchAcceptedPayloadRead"},{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchAcceptedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_DETACHED_ACCEPTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunDetachedAcceptedPayload"},{"$ref":"#/components/schemas/AgentRunDetachedAcceptedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_INVOKE_AGENT_BILLING_MODE_RETAINED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunInvokeAgentBillingModeRetainedPayload"},{"$ref":"#/components/schemas/AgentRunInvokeAgentBillingModeRetainedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_BILLING_USAGE_RETAINED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunBillingUsageRetainedPayload"},{"$ref":"#/components/schemas/AgentRunBillingUsageRetainedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_REPLAYED_UPLOADS_SEALED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunReplayedUploadsSealedPayload"},{"$ref":"#/components/schemas/AgentRunReplayedUploadsSealedPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ToolCallStatusChangedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["INPUT_REQUEST_CREATED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/InputRequestCreatedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_CREATED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/InputRequestUpdatedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ChildRunStatusChangedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["MODEL_CALL_COMPLETED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ModelCallCompletedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["MODEL_CALL_COMPLETED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["RUN_PARKED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunParkedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_PARKED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["RUN_LOG_CAPTURED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RunLogCapturedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_LOG_CAPTURED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/StreamHeartbeatEmittedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["URL_CITED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/UrlCitedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["URL_CITED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["DOCUMENT_CITED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/DocumentCitedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["DOCUMENT_CITED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["FILE_ATTACHED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/FileAttachedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["FILE_ATTACHED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["FILES_CHANGED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/FilesChangedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["FILES_CHANGED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/RuntimeEventRecordedPayload"},{"type":"object","properties":{"type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"]}},"required":["type"],"additionalProperties":false}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchReceiptPayload"},{"$ref":"#/components/schemas/AgentRunControlPlaneDispatchReceiptPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointPayload"},{"$ref":"#/components/schemas/AgentRunToolExposureCheckpointPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointPayload"},{"$ref":"#/components/schemas/AgentRunProviderReplayCheckpointPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT"]},"payload":{"anyOf":[{"$ref":"#/components/schemas/AgentRunModelCallContextPayload"},{"$ref":"#/components/schemas/AgentRunModelCallContextPayloadRedacted"}]},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false},{"type":"object","properties":{"event_id":{"type":["integer","null"],"minimum":0},"event_type":{"type":"string","not":{"enum":["RUN_STARTED","RUN_FINISHED","RUN_ERROR","TEXT_MESSAGE_START","TEXT_MESSAGE_CONTENT","TEXT_MESSAGE_END","TOOL_CALL_START","TOOL_CALL_ARGS","TOOL_CALL_CHUNK","TOOL_CALL_END","TOOL_CALL_RESULT","STATE_SNAPSHOT","STATE_DELTA","MESSAGES_SNAPSHOT","STEP_STARTED","STEP_FINISHED","REASONING_START","REASONING_MESSAGE_START","REASONING_MESSAGE_CONTENT","REASONING_MESSAGE_END","REASONING_CONTENT","REASONING_END","ACTIVITY_SNAPSHOT","ACTIVITY_DELTA","AGENT_RUN_AUTHORIZATION_SEALED","AGENT_RUN_REQUEST_ENQUEUED","AGENT_RUN_DEFAULT_CHAT_START_ENQUEUED","AGENT_RUN_TOOL_RESULT_SUBMITTED","AGENT_RUN_TOOL_RESULT_DELIVERY_FAILED","AGENT_RUN_INTEGRATION_CONNECTION_REFUSED","AGENT_RUN_RUNTIME_OWNER_BOUND","AGENT_RUN_RUNTIME_INVOKE_RETRIED","AGENT_RUN_CONTEXT_COMPACTED","AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED","AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED","AGENT_RUN_PROVIDER_REPLAY_TURN_STARTED","AGENT_RUN_PROVIDER_REPLAY_TURN_FINISHED","AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED","AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED","AGENT_RUN_DETACHED_ACCEPTED","AGENT_RUN_INVOKE_AGENT_BILLING_MODE_RETAINED","AGENT_RUN_BILLING_USAGE_RETAINED","AGENT_RUN_REPLAYED_UPLOADS_SEALED","TOOL_CALL_STATUS_CHANGED","INPUT_REQUEST_CREATED","INPUT_REQUEST_UPDATED","CHILD_RUN_STATUS_CHANGED","MODEL_CALL_COMPLETED","RUN_PARKED","RUN_LOG_CAPTURED","STREAM_HEARTBEAT_EMITTED","URL_CITED","DOCUMENT_CITED","FILE_ATTACHED","FILES_CHANGED","RUNTIME_EVENT_RECORDED","AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT","AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT","AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT","AGENT_RUN_MODEL_CALL_CONTEXT"]}},"payload":{"description":"Payload of an unrecognized historical or future event."},"is_error":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"run_id":{"type":"string","format":"uuid","description":"Run identifier associated with the record."},"event_class":{"type":"string","enum":["fact","delta"],"description":"The event class associated with this record."},"span_id":{"type":"string","minLength":1,"description":"The span id associated with this record."},"parent_span_id":{"type":["string","null"],"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":["string","null"],"minLength":1,"description":"The turn id associated with this record."},"origin_event_type":{"type":"string","minLength":1,"description":"The origin event type associated with this record."},"origin_custom_name":{"type":["string","null"],"minLength":1,"description":"The origin custom name associated with this record."},"unrecoverable_fields":{"type":"array","items":{"type":"string","minLength":1,"description":"One unrecoverable field item associated with this record."},"description":"List of unrecoverable fields associated with this record."}},"required":["event_id","event_type","payload","is_error","created_at","run_id","event_class","span_id","parent_span_id","turn_id","origin_event_type","origin_custom_name","unrecoverable_fields"],"additionalProperties":false}]},"RunEventSnapshot":{"type":"object","properties":{"after_event_id":{"type":"integer","minimum":0,"description":"Cursor for continuing event reads after this snapshot."},"events":{"type":"array","items":{"$ref":"#/components/schemas/RunSnapshotEvent"}}},"required":["after_event_id","events"],"description":"Replay events with a continuation cursor. For task and workflow histories over 5000 events or 10 MiB, use paginated event reads."},"RunTarget":{"type":"object","properties":{"type":{"type":"string","enum":["agent","task","workflow"],"description":"Kind of execution definition."},"id":{"type":"string","minLength":1,"maxLength":512,"pattern":"^\\S+$","description":"Definition ID without a kind prefix, such as health-check rather than task:health-check."}},"required":["type","id"],"additionalProperties":false,"description":"Resolved execution definition.","x-ref-description":"Resolved execution definition."},"CreatedRun":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique run UUID."},"status":{"type":"string","enum":["pending","running","waiting","completed","failed","cancelled"],"description":"Current execution state."},"project_id":{"type":"string","format":"uuid","description":"Project containing the run."},"target":{"$ref":"#/components/schemas/RunTarget"},"input":{"description":"Business input supplied when the run was created."},"output":{"description":"Final business output; null until successful finalization."},"error":{"$ref":"#/components/schemas/RunFailure"},"title":{"type":"string","description":"Display title, omitted when unset."},"labels":{"$ref":"#/components/schemas/RunLabels"},"parent_run_id":{"type":"string","format":"uuid","description":"Immediate parent run ID, present on child runs."},"root_run_id":{"type":"string","format":"uuid","description":"Top-level ancestor run ID, present on child runs."},"created_at":{"type":"string","format":"date-time","description":"When the run was accepted."},"updated_at":{"type":"string","format":"date-time","description":"When the resource last changed, including usage updates."},"started_at":{"type":"string","format":"date-time","description":"When the first execution attempt started, omitted before execution."},"finished_at":{"type":"string","format":"date-time","description":"When the run completed, failed or was cancelled."},"config":{"type":"object","additionalProperties":{"description":"A JSON value."},"description":"Definition-specific execution configuration."},"execution":{"type":"object","properties":{"runtime":{"$ref":"#/components/schemas/RunRuntime"},"timeout_seconds":{"type":"integer","exclusiveMinimum":0,"description":"Deadline for the whole run in seconds, measured from its first start and including retries."},"retry_limit":{"type":"integer","minimum":0,"description":"Maximum retries after the first attempt; only retryable failures are retried."},"attempt":{"type":"integer","minimum":1,"description":"Current or last execution attempt, starting at 1; absent before execution."},"exit_code":{"type":["integer","null"],"description":"Runtime process exit code, or null when no exit code was recorded."},"duration_ms":{"type":["integer","null"],"minimum":0,"description":"Elapsed time from first start to finish, including waits and retries; null when not finished.","format":"int64"},"tool_error_count":{"type":"integer","minimum":0,"description":"Recorded failed tool invocations during this run."},"logs":{"type":"string","description":"Captured runtime text logs, when available."},"start_mode":{"type":"string","description":"Recorded execution start mode, when available."}},"description":"Resolved execution settings and diagnostics."},"control":{"type":"object","properties":{"waiting":{"$ref":"#/components/schemas/RunWait"},"pause":{"$ref":"#/components/schemas/RunPause"},"cancellation":{"$ref":"#/components/schemas/RunCancellation"}},"description":"Pending control requests and the current wait."},"task_id":{"type":"string","minLength":1,"maxLength":200,"description":"Orchestration task ID, distinct from the execution definition."},"conversation_id":{"type":"string","format":"uuid","description":"Conversation containing the run."},"input_message_id":{"type":"string","format":"uuid","description":"Conversation message that supplied the input."},"output_message_id":{"type":"string","format":"uuid","description":"Conversation message containing the result."},"batch_id":{"type":"string","format":"uuid","description":"Batch containing the run."},"trigger":{"$ref":"#/components/schemas/RunTrigger"},"usage":{"$ref":"#/components/schemas/Usage"},"descendants":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total descendants at every depth."},"active":{"type":"integer","minimum":0,"description":"Descendants that are pending, running or waiting."},"has_failures":{"type":"boolean","description":"Whether any descendant has failed."},"usage":{"allOf":[{"$ref":"#/components/schemas/Usage"},{"description":"Aggregate usage of every descendant, excluding this run.","x-ref-description":"Aggregate usage of every descendant, excluding this run."}]}},"required":["total","active","has_failures"],"description":"Counts and usage across all descendant runs, excluding this run."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/RunArtifact"},"description":"Files produced by the run."},"schemas":{"type":"object","properties":{"input":{"type":["object","null"],"properties":{"schema":{"anyOf":[{"type":"boolean"},{"type":"object","additionalProperties":{"description":"A JSON value."}}],"description":"JSON Schema captured for this run; object schemas and boolean schemas are supported."},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 digest of the pinned schema."}},"required":["schema","sha256"]},"output":{"type":["object","null"],"properties":{"schema":{"anyOf":[{"type":"boolean"},{"type":"object","additionalProperties":{"description":"A JSON value."}}],"description":"JSON Schema captured for this run; object schemas and boolean schemas are supported."},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 digest of the pinned schema."}},"required":["schema","sha256"]}},"required":["input","output"],"description":"Pinned schemas for business input and output; null means no declared schema."},"metadata":{"type":"object","additionalProperties":{"description":"A JSON value."},"description":"Additional resource metadata."}},"required":["id","status","project_id","target","input","output","created_at","updated_at","trigger"],"description":"A newly created run with resolved target and recorded trigger.","allOf":[{"if":{"properties":{"status":{"enum":["failed"]}},"required":["status"]},"then":{"required":["error"]},"else":{"not":{"required":["error"]}}},{"if":{"properties":{"status":{"enum":["completed","failed","cancelled"]}},"required":["status"]},"then":{"required":["finished_at"]},"else":{"not":{"required":["finished_at"]}}},{"if":{"properties":{"status":{"enum":["pending","running","waiting","failed","cancelled"]}},"required":["status"]},"then":{"properties":{"output":{"type":"null"}}},"else":{}},{"if":{"properties":{"status":{"enum":["waiting"]}},"required":["status"]},"then":{"required":["control"],"properties":{"control":{"required":["waiting"]}}},"else":{"properties":{"control":{"not":{"required":["waiting"]}}}}},{"if":{"properties":{"control":{"required":["pause"]}},"required":["control"]},"then":{"properties":{"status":{"enum":["pending","running","waiting"]}}}},{"if":{"required":["trigger"],"properties":{"trigger":{"properties":{"type":{"enum":["agent","task","workflow"]}},"required":["type"]}}},"then":{"required":["parent_run_id","root_run_id"]}},{"if":{"properties":{"status":{"const":"completed"}},"required":["status"]},"then":{"properties":{"descendants":{"properties":{"active":{"const":0}}}}}}],"dependentRequired":{"parent_run_id":["root_run_id"],"root_run_id":["parent_run_id"]}},"RunCreationReceipt":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","running","waiting","completed","failed","cancelled"],"description":"Current execution state."}},"required":["run_id","status"],"additionalProperties":false,"description":"Minimal admission receipt for a caller who cannot read the created run. No private fields are disclosed."},"CreateRunResult":{"anyOf":[{"$ref":"#/components/schemas/CreatedRun"},{"$ref":"#/components/schemas/RunCreationReceipt"}],"description":"The full created run when readable by the caller; otherwise only its admission receipt. Replay uses the same caller visibility."},"RunExecutionOptions":{"type":"object","properties":{"runtime":{"allOf":[{"$ref":"#/components/schemas/RunRuntime"},{"description":"Deployment or registered runtime override; omit to use the definition default.","x-ref-description":"Deployment or registered runtime override; omit to use the definition default."}]},"timeout_seconds":{"type":"integer","exclusiveMinimum":0,"description":"Whole-run deadline in seconds, including retries; unsupported target overrides are refused."},"retry_limit":{"type":"integer","minimum":0,"description":"Maximum retries after the first attempt, restricted to retryable failures."}},"additionalProperties":false,"description":"Execution overrides, separate from business input and configuration.","x-ref-description":"Execution overrides, separate from business input and configuration."},"DirectRunRequest":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid","description":"UUID of the project containing the execution definition or saved source."},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Optional display title for the accepted run."},"labels":{"$ref":"#/components/schemas/RunLabels"},"target":{"allOf":[{"$ref":"#/components/schemas/RunTarget"},{"description":"Definition executed by this run."}]},"input":{"description":"Business input passed to the definition unchanged; omitted input resolves to null."},"config":{"type":"object","additionalProperties":{"description":"A JSON value."},"description":"Definition-specific configuration; business keys retain their spelling on every transport."},"execution":{"$ref":"#/components/schemas/RunExecutionOptions"},"parent_run_id":{"type":"string","format":"uuid","description":"Canonical UUID of the authenticated runtime parent; ordinary users cannot assert parent authority."},"tool_call_id":{"type":"string","minLength":1,"maxLength":128,"description":"Durable tool invocation on an agent parent; requires parent_run_id and excludes node_id."},"node_id":{"type":"string","minLength":1,"maxLength":128,"description":"Started workflow node on the parent; requires parent_run_id and excludes tool_call_id."},"conversation_id":{"type":"string","format":"uuid","description":"Conversation associated with an agent admission, when applicable."},"batch_id":{"type":"string","format":"uuid","description":"Batch UUID associated with the accepted run."}},"required":["project_id","target"],"additionalProperties":false,"description":"Provide the option 1.","dependentRequired":{"tool_call_id":["parent_run_id"],"node_id":["parent_run_id"]},"allOf":[{"not":{"required":["tool_call_id","node_id"]}}]},"ScheduleRunRequest":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid","description":"UUID of the project containing the execution definition or saved source."},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Optional display title for the accepted run."},"labels":{"$ref":"#/components/schemas/RunLabels"},"source":{"type":"object","properties":{"type":{"type":"string","enum":["schedule"],"description":"Execute a saved schedule."},"id":{"type":"string","format":"uuid","description":"UUID of the saved schedule in this project."}},"required":["type","id"],"additionalProperties":false,"description":"Saved schedule supplying the target and execution configuration."}},"required":["project_id","source"],"additionalProperties":false,"description":"Structured option 2 details used by the tool."},"WebhookRunRequest":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid","description":"Project identifier for the target project."},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Short human-readable title for the record."},"labels":{"$ref":"#/components/schemas/RunLabels"},"source":{"type":"object","properties":{"type":{"type":"string","enum":["webhook"],"description":"Saved source kind."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Saved webhook identifier."}},"required":["type","id"],"additionalProperties":false,"description":"Saved webhook to execute."},"input":{"description":"A JSON value."}},"required":["project_id","source","input"],"additionalProperties":false,"description":"Structured option 3 details used by the tool."},"CreateRunRequest":{"anyOf":[{"$ref":"#/components/schemas/DirectRunRequest"},{"$ref":"#/components/schemas/ScheduleRunRequest"},{"$ref":"#/components/schemas/WebhookRunRequest"}],"description":"Create a direct run with project_id, target:{type,id}, and optional input, or execute a saved schedule or webhook. Input is business data; configuration and execution settings are separate."},"FinalizeRunRequest":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["completed"]},"output":{"description":"Any JSON value. The HTTP boundary rejects non-JSON values."}},"required":["status","output"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"error":{"allOf":[{"$ref":"#/components/schemas/RunFailure"},{"description":"Error details supplied to the tool."}]}},"required":["status","error"],"additionalProperties":false}],"description":"Finalizes a run with output or an error."},"SucceedRunRequest":{"type":"object","properties":{"output":{"description":"Final JSON output. Use explicit null when there is no value."}},"required":["output"],"additionalProperties":false,"description":"Final output for a successful run."},"FailRunRequest":{"type":"object","properties":{"error":{"allOf":[{"$ref":"#/components/schemas/RunFailure"},{"description":"Error details supplied to the tool."}]}},"required":["error"],"additionalProperties":false,"description":"Error for a failed run."},"ResumeRunRequest":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["manual"],"description":"Provide the type."}},"required":["type"],"additionalProperties":false,"description":"Structured option 1 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"],"description":"Provide the type."},"tool_call_id":{"type":"string","minLength":1,"maxLength":128,"description":"Tool call identifier that links this request to a prior tool invocation."},"result":{"description":"A JSON value."},"is_error":{"type":"boolean","description":"Provide the is error."}},"required":["type","tool_call_id","result"],"additionalProperties":false,"description":"Structured option 2 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["integration_connected"],"description":"Provide the type."},"integration":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the integration."}},"required":["type","integration"],"additionalProperties":false,"description":"Structured option 3 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["approval"],"description":"Provide the type."},"wait_id":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the wait id."},"node_id":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the node id."},"approved":{"type":"boolean","description":"Provide the approved."},"comment":{"type":"string","maxLength":4000,"description":"Provide the comment."}},"required":["type","wait_id","node_id","approved"],"additionalProperties":false,"description":"Structured option 4 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Provide the type."},"wait_id":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the wait id."},"name":{"type":"string","minLength":1,"maxLength":128,"description":"Human-readable name for the target record."},"payload":{"description":"A JSON value."}},"required":["type","wait_id","name"],"additionalProperties":false,"description":"Structured option 5 details used by the tool."}],"description":"Provide the input."},"RunsPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Run"}},"page_info":{"$ref":"#/components/schemas/RunsPageInfo"}},"required":["data","page_info"]},"UpdateRunRequest":{"type":"object","properties":{"title":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Replace the display title; null clears it."},"labels":{"allOf":[{"$ref":"#/components/schemas/RunLabels"},{"description":"Replace the complete label map; an empty object clears it."}]}},"additionalProperties":false,"description":"Update the run title or labels.","minProperties":1},"RunHeartbeat":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid"},"expires_at":{"type":"string","format":"date-time"}},"required":["run_id","expires_at"]},"RunEventToken":{"type":"object","properties":{"token":{"type":"string","minLength":1},"token_type":{"type":"string","enum":["Bearer"]},"expires_at":{"type":"string","format":"date-time"},"run_id":{"type":"string","format":"uuid"},"permissions":{"type":"array","items":{"type":"string","enum":["run.events.append"]},"minItems":1,"maxItems":1}},"required":["token","token_type","expires_at","run_id","permissions"],"description":"A short-lived event-append credential for the target child run; never grants finalization, heartbeat, or child creation."},"InputRequestField":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"label":{"type":"string","maxLength":1000},"description":{"type":"string","maxLength":4000},"required":{"type":"boolean","default":false},"type":{"type":"string","enum":["password"]}},"required":["name","type"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"label":{"type":"string","maxLength":1000},"description":{"type":"string","maxLength":4000},"required":{"type":"boolean","default":false},"type":{"type":"string","enum":["text","textarea","email","url"]},"default":{"type":"string"}},"required":["name","type"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"label":{"type":"string","maxLength":1000},"description":{"type":"string","maxLength":4000},"required":{"type":"boolean","default":false},"type":{"type":"string","enum":["number"]},"default":{"type":"number"}},"required":["name","type"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"label":{"type":"string","maxLength":1000},"description":{"type":"string","maxLength":4000},"required":{"type":"boolean","default":false},"type":{"type":"string","enum":["checkbox","confirm"]},"default":{"type":"boolean"}},"required":["name","type"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"label":{"type":"string","maxLength":1000},"description":{"type":"string","maxLength":4000},"required":{"type":"boolean","default":false},"type":{"type":"string","enum":["select","radio"]},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"description":{"type":"string"},"recommended":{"type":"boolean"}},"required":["value","label"],"additionalProperties":false},"minItems":1,"maxItems":100},"default":{"type":"string"}},"required":["name","type","options"],"additionalProperties":false}]},"InputValues":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"number","description":"Provide the option 2."},{"type":"boolean","description":"Provide the option 3."},{"type":"null","description":"Provide the option 4."},{"type":"null"}],"description":"Additional structured values supplied to the tool."},"description":"Submitted values keyed by field name; password values are omitted from reads.","x-ref-description":"Submitted values keyed by field name; password values are omitted from reads."},"Actor":{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key","service_account","system"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["type","id"],"description":"Immediate authenticated initiator, recorded by the server; execution credentials identify their issuing service account, not the original caller."},"UnavailableActor":{"type":"object","properties":{"type":{"type":"string","enum":["unavailable"]},"reason":{"type":"string","enum":["not_recorded","identity_removed"],"description":"`not_recorded`: the server never stored the submitting credential. `identity_removed`: the recorded identity was later revoked or deleted."},"legacy_role":{"type":"string","enum":["human","agent","integration","system","user","api_key","service_account"],"description":"Role tag stored with the response. It is not an authenticated actor type."},"legacy_id":{"type":"string","minLength":1,"maxLength":255,"description":"Actor ID stored with the response. It is not promoted to an authenticated actor."}},"required":["type","reason"],"additionalProperties":false,"description":"A historical response without authoritative submitting-credential provenance. The server never infers or looks up a replacement actor."},"InputResponse":{"type":"object","properties":{"response_id":{"type":"string","format":"uuid","description":"Unique response ID."},"values":{"$ref":"#/components/schemas/InputValues"},"actor":{"anyOf":[{"$ref":"#/components/schemas/Actor"},{"$ref":"#/components/schemas/UnavailableActor"}],"description":"Authenticated principal that submitted the response, or `unavailable` for a historical response without authoritative provenance."},"redacted_fields":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Names of submitted secret fields omitted from values."},"created_at":{"type":"string","format":"date-time","description":"When the response was submitted."}},"required":["response_id","values","actor","created_at"]},"InputRequest":{"type":"object","properties":{"input_request_id":{"type":"string","format":"uuid","description":"Unique input request ID."},"project_id":{"type":"string","format":"uuid","description":"Project inherited from the run."},"run_id":{"type":"string","format":"uuid","description":"Run waiting for this input."},"title":{"type":"string","minLength":1,"maxLength":1000,"description":"Question or decision shown to the responder."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/InputRequestField"},"description":"Fields the responder can fill in."},"status":{"type":"string","enum":["open","submitted","cancelled","expired"],"description":"Current resolution state."},"requested_responder_type":{"type":"string","enum":["human","agent","system"],"description":"Required responder role; the authenticated actor identifies who actually responded."},"response":{"anyOf":[{"$ref":"#/components/schemas/InputResponse"},{"type":"null"},{"type":"null"}],"description":"Submitted response, or null before submission or after cancellation or expiry."},"created_at":{"type":"string","format":"date-time","description":"When the request was created."},"expires_at":{"type":"string","format":"date-time","description":"When the request expires."},"resolved_at":{"type":"string","format":"date-time","description":"When the request was submitted, cancelled or expired."},"tool_call_id":{"type":"string","minLength":1,"maxLength":128,"description":"Tool invocation waiting for the response."},"conversation_id":{"type":"string","format":"uuid","description":"Conversation inherited from the run."},"description":{"type":"string","description":"Additional instructions for the responder."},"metadata":{"type":"object","additionalProperties":{"description":"A JSON value."},"description":"Additional resource metadata."}},"required":["input_request_id","project_id","run_id","title","fields","status","requested_responder_type","response","created_at"],"allOf":[{"if":{"properties":{"status":{"enum":["submitted"]}},"required":["status"]},"then":{"properties":{"response":{"type":"object"}}},"else":{"properties":{"response":{"type":"null"}}}},{"if":{"properties":{"status":{"enum":["open"]}},"required":["status"]},"then":{"not":{"required":["resolved_at"]}},"else":{"required":["resolved_at"]}}]},"ListInputRequestsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InputRequest"}},"page_info":{"$ref":"#/components/schemas/RunsPageInfo"}},"required":["data","page_info"]},"CreateInputRequestRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":1000},"fields":{"type":"array","items":{"$ref":"#/components/schemas/InputRequestField"},"minItems":1,"maxItems":100},"tool_call_id":{"type":"string","minLength":1,"maxLength":128},"requested_responder_type":{"type":"string","enum":["human","agent","system"],"default":"human"},"description":{"type":"string","maxLength":20000},"expires_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":{"description":"A JSON value."}}},"required":["title","fields"],"additionalProperties":false},"RespondToInputRequestRequest":{"type":"object","properties":{"values":{"allOf":[{"$ref":"#/components/schemas/InputValues"},{"description":"Structured values submitted to the tool."}]}},"required":["values"],"additionalProperties":false},"Uuid":{"type":"string","format":"uuid"},"ConversationMessage":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"parent_id":{"type":["string","null"]},"seq":{"type":"number"},"role":{"type":"string","enum":["user","assistant","tool"]},"created_by":{"type":["string","null"]},"sender_type":{"type":"string","enum":["user","webhook","service_account","integration","agent","system"],"default":"user"},"sender_id":{"type":["string","null"]},"sender_display_name":{"type":["string","null"]},"parts":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."}},"required":["type","text"],"description":"Structured option 1 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"url":{"type":"string","description":"Provide the url."}},"required":["type","upload_id","media_type"],"description":"Structured option 2 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["file"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"filename":{"type":"string","description":"Provide the filename."},"url":{"type":"string","description":"Provide the url."}},"required":["type","media_type"],"description":"Structured option 3 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_call"],"description":"Provide the type."},"id":{"type":"string","description":"Unique identifier for the target record."},"name":{"type":"string","description":"Human-readable name for the target record."},"input":{"type":"object","additionalProperties":{"description":"Additional structured values supplied to the tool."},"description":"Structured input details used by the tool."},"state":{"type":"string","enum":["streaming","pending","completed","error"],"description":"Provide the state."}},"required":["type","id","name","input","state"],"description":"Structured option 4 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"],"description":"Provide the type."},"tool_call_id":{"type":"string","description":"Tool call identifier that links this request to a prior tool invocation."},"output":{"description":"Provide the output."},"is_error":{"type":"boolean","description":"Provide the is error."}},"required":["type","tool_call_id"],"description":"Structured option 5 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["reasoning"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."},"signature":{"type":"string","description":"Provide the signature."}},"required":["type","text"],"description":"Structured option 6 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["citation"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"url":{"type":"string","description":"Provide the url."},"title":{"type":"string","description":"Short human-readable title for the record."},"quote":{"type":"string","description":"Provide the quote."}},"required":["type","source_id"],"description":"Structured option 7 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["source_document"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"media_type":{"type":"string","description":"Provide the media type."},"title":{"type":"string","description":"Short human-readable title for the record."},"filename":{"type":"string","description":"Provide the filename."}},"required":["type","source_id","media_type","title"],"description":"Structured option 8 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["step_start"],"description":"Provide the type."}},"required":["type"],"description":"Structured option 9 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["error"],"description":"Provide the type."},"code":{"type":"string","description":"Provide the code."},"message":{"type":"string","description":"Provide the message."}},"required":["type","code","message"],"description":"Structured option 10 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["data"],"description":"Provide the type."},"name":{"type":"string","description":"Human-readable name for the target record."},"value":{"description":"Provide the value."}},"required":["type","name"],"description":"Structured option 11 details used by the tool."}],"description":"One part item supplied to the tool."}},"model":{"type":["string","null"]},"run_usage":{"type":["object","null"],"properties":{"scope":{"type":"string","enum":["run"],"description":"The scope associated with this record."},"model":{"type":["string","null"],"description":"AI model id or alias. Call list_models for the ids this deployment serves; never invent a version suffix."},"input_tokens":{"type":"integer","minimum":0,"description":"The input tokens associated with this record."},"output_tokens":{"type":"integer","minimum":0,"description":"The output tokens associated with this record."},"cache_creation_input_tokens":{"type":"integer","minimum":0,"description":"The cache creation input tokens associated with this record."},"cache_read_input_tokens":{"type":"integer","minimum":0,"description":"The cache read input tokens associated with this record."},"reasoning_tokens":{"type":"integer","minimum":0,"description":"The reasoning tokens associated with this record."},"total_tokens":{"type":"integer","minimum":0,"description":"The total tokens associated with this record."},"model_calls":{"type":"integer","minimum":0,"description":"The model calls associated with this record."},"cost_credits":{"type":["string","null"],"description":"The cost credits associated with this record."}},"required":["scope","model","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","reasoning_tokens","total_tokens","model_calls","cost_credits"],"description":"Structured run usage details associated with this record."},"token_usage":{"type":["object","null"],"properties":{"input":{"type":"number"},"output":{"type":"number"},"reasoning_tokens":{"type":"integer","minimum":0}}},"finish_reason":{"type":["string","null"]},"cost_credits":{"type":["string","null"]},"status":{"type":"string","enum":["pending","streaming","completed","failed","cancelled"]},"edited_at":{"type":["string","null"]},"idempotency_key":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":["string","null"]}},"required":["id","conversation_id","seq","role","parts","status","created_at"]},"BudgetScope":{"type":"object","properties":{"kind":{"type":"string","enum":["api_key","member","project"],"description":"Budget scope name. API key takes precedence, followed by project member, then project. Matches `scope` in a `402` `ai-budget-exceeded` response."},"project_id":{"type":["string","null"],"format":"uuid"},"user_id":{"type":["string","null"],"format":"uuid"},"api_key_id":{"type":["string","null"],"format":"uuid"}},"required":["kind","project_id","user_id","api_key_id"]},"Budget":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"scope":{"$ref":"#/components/schemas/BudgetScope"},"monthly_limit_usd":{"type":"number","description":"The monthly AI spend limit, in USD"},"monthly_limit_credits":{"type":"number","description":"The same limit in credits, the unit spend is counted in"},"status":{"allOf":[{"$ref":"#/components/schemas/SubjectBudgetStatus"},{"type":"object"}]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","scope","monthly_limit_usd","monthly_limit_credits","status","created_at","updated_at"]},"BudgetScopeInput":{"type":"object","properties":{"project_reference":{"type":"string","minLength":1,"description":"The project whose spend this budget caps. Required whenever `user_id` is set."},"user_id":{"type":"string","format":"uuid","description":"The person whose spend on that project this budget caps."},"api_key_id":{"type":"string","format":"uuid","description":"The API key whose spend this budget caps, wherever the key is used."}}},"CreateBudgetInput":{"type":"object","properties":{"scope":{"$ref":"#/components/schemas/BudgetScopeInput"},"monthly_limit_credits":{"type":"number","minimum":0,"maximum":8589934591.999999,"description":"Monthly AI spending limit in credits, the unit spend is counted in. At most 8589934591.999999 credits, with at most six decimal places. A value of 0 blocks all spending within the scope. Provide exactly one of monthly_limit_credits or monthly_limit_usd.","example":500},"monthly_limit_usd":{"type":"number","minimum":0,"maximum":858993459.1999999,"description":"Deprecated. Use `monthly_limit_credits`. Monthly AI spending limit in USD, converted to credits at the published credit price. At most 858993459.1999999 USD, the most that converts within the credit maximum. A value of 0 blocks all spending within the scope. Provide exactly one of monthly_limit_credits or monthly_limit_usd.","example":50,"deprecated":true,"x-deprecation":{"register_id":"CR-budget-monthly-limit-usd-input","deprecated_at":"2026-09-29","replacement":"monthly_limit_credits on REST request bodies or monthlyLimitCredits on GraphQL inputs, stored exactly as written.","rollout_state":"announced","old_semantics":"A monthly limit in USD, converted to credits at the published credit price and stored as credits. It is accepted in place of monthly_limit_credits, never together with it, and keeps that meaning while this entry is open. The monthly_limit_usd member of budget responses is not covered by this entry.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}}},"required":["scope"]},"UpdateBudgetInput":{"type":"object","properties":{"monthly_limit_credits":{"type":"number","minimum":0,"maximum":8589934591.999999,"description":"New monthly AI spending limit in credits. At most 8589934591.999999 credits, with at most six decimal places. Usage already recorded this month is retained. Provide exactly one of monthly_limit_credits or monthly_limit_usd.","example":500},"monthly_limit_usd":{"type":"number","minimum":0,"maximum":858993459.1999999,"description":"Deprecated. Use `monthly_limit_credits`. New monthly AI spending limit in USD, converted to credits at the published credit price. At most 858993459.1999999 USD, the most that converts within the credit maximum. Usage already recorded this month is retained. Provide exactly one of monthly_limit_credits or monthly_limit_usd.","example":50,"deprecated":true,"x-deprecation":{"register_id":"CR-budget-monthly-limit-usd-input","deprecated_at":"2026-09-29","replacement":"monthly_limit_credits on REST request bodies or monthlyLimitCredits on GraphQL inputs, stored exactly as written.","rollout_state":"announced","old_semantics":"A monthly limit in USD, converted to credits at the published credit price and stored as credits. It is accepted in place of monthly_limit_credits, never together with it, and keeps that meaning while this entry is open. The monthly_limit_usd member of budget responses is not covered by this entry.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}}}},"CreditsError":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]},"OAuthConnectionProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"type":"object","properties":{"connect_url":{"type":"string","format":"uri","description":"URL for starting OAuth consent for a missing or unusable connection. Present only if the project and OAuth integration exist. The URL is a hint, not authorization to redirect.","example":"https://api.veryfront.com/oauth/connect/github?project_reference=my-project&scope=project"},"connectUrl":{"type":"string","format":"uri","description":"Retained legacy alias for connect_url; present exactly when connect_url is, with the same value."}}}]},"ProviderFile":{"type":"object","properties":{"id":{"type":"string","description":"Provider-specific file or folder ID."},"name":{"type":"string","description":"File or folder name."},"path":{"type":"string","description":"Provider path for the file or folder. For a folder returned by list-files, pass this value unchanged as `path` to list its contents (a drive-relative path for OneDrive, an `sp-site:` path for SharePoint, the folder ID for Google Drive). Google Drive files keep their name. Search results may not carry a navigable path."},"mime_type":{"type":"string","description":"MIME type, or the legacy `folder` sentinel for folders."},"size":{"type":"number","description":"File size in bytes. Folders may report 0."},"size_bytes":{"type":"number","description":"File size in bytes; equal to `size`. Folders may report 0."},"is_folder":{"type":"boolean","description":"Whether this item is a folder. Equivalent to `kind === \"folder\"`."},"kind":{"type":"string","enum":["file","folder"],"description":"Whether this item is a file or a folder."},"modified_at":{"type":["string","null"],"format":"date-time","description":"Provider last-modified timestamp in ISO 8601, or null when the provider does not report a valid one.","example":"2026-03-02T09:15:27.000Z"},"thumbnail":{"type":"string","description":"Optional provider thumbnail URL."}},"required":["id","name","path","mime_type","size","size_bytes","is_folder","kind","modified_at"]},"ProviderConnectionProblem":{"allOf":[{"$ref":"#/components/schemas/LegacyCompatibleProblem"},{"type":"object","properties":{"provider":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"Provider whose connection is missing. Present on `provider-not-connected`."},"connect_url":{"type":"string","format":"uri","description":"URL for starting OAuth consent for a missing or unusable provider connection. Present for `provider-not-connected` errors. The URL is a hint, not authorization to redirect.","example":"https://api.veryfront.com/oauth/connect/onedrive?project_reference=my-project&scope=user"},"connectUrl":{"type":"string","format":"uri","description":"Retained legacy alias for connect_url; present exactly when connect_url is, with the same value."}}}]},"ProviderProblem":{"allOf":[{"$ref":"#/components/schemas/LegacyCompatibleProblem"},{"type":"object","properties":{"retry_after_seconds":{"type":"integer","minimum":0,"description":"Seconds to wait before retrying, if supplied by the provider’s rate-limit response."}}}]},"ProviderError":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message."},"connectUrl":{"type":"string","description":"OAuth connection URL when provider authorization is required."}},"required":["error"]},"Jwk":{"type":"object","properties":{"kty":{"type":"string","enum":["RSA"],"description":"Key type"},"use":{"type":"string","enum":["sig"],"description":"Public key use"},"alg":{"type":"string","enum":["RS256"],"description":"Signing algorithm"},"kid":{"type":"string","description":"Key identifier"},"n":{"type":"string","description":"RSA modulus, base64url encoded"},"e":{"type":"string","description":"RSA public exponent, base64url encoded"}},"required":["kty","use","alg","kid","n","e"]},"JwksResponse":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/Jwk"},"description":"JSON Web Key Set"}},"required":["keys"]},"OAuthTokenResponse":{"type":"object","properties":{"access_token":{"type":"string","description":"JWT access token"},"token_type":{"type":"string","enum":["Bearer"],"description":"Token type"},"user":{"type":"object","additionalProperties":{},"description":"User information (empty object for client_credentials)"}},"required":["access_token","token_type","user"]},"OAuthErrorResponse":{"type":"object","properties":{"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}}}],"description":"Error message or object"}},"required":["error"]},"OAuthTokenOptions":{"type":"object","properties":{"shared_user_id":{"type":"string","description":"Scoped user ID for limited access tokens"},"expire":{"type":"number","description":"Token expiration in seconds"},"scopes":{"type":"array","items":{"type":"string"},"description":"Requested scopes for the token (must be subset of allowed scopes for the client)"}}},"OAuthTokenRequest":{"type":"object","properties":{"grant_type":{"type":"string","enum":["client_credentials"],"description":"OAuth grant type","example":"client_credentials"},"client_id":{"type":"string","description":"Client ID for client_credentials token exchange"},"client_secret":{"type":"string","description":"Client secret for client_credentials token exchange"},"project_reference":{"type":"string","description":"Project UUID or slug for scoped tokens"},"project_id":{"type":"string","description":"Deprecated project ID selector; a slug is not resolved here. Use project_reference."},"project_slug":{"type":"string","description":"Deprecated project slug selector; a UUID is not accepted here. Use project_reference."},"custom_domain":{"type":"string","description":"Custom domain to resolve project (alternative to project_id/project_slug)"},"options":{"$ref":"#/components/schemas/OAuthTokenOptions"}},"required":["grant_type","client_id","client_secret"]},"EnvironmentAccessTokenResponse":{"type":"object","properties":{"access_token":{"type":"string","description":"Short-lived environment access token for protected environment requests"},"token_type":{"type":"string","enum":["Bearer"],"description":"Token type"},"expires_in":{"type":"integer","exclusiveMinimum":0,"description":"Seconds until the token expires"}},"required":["access_token","token_type","expires_in"]},"AuthErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"}},"required":["error"]},"EnvironmentAccessTokenRequest":{"type":"object","properties":{"project_reference":{"type":"string","minLength":1,"maxLength":200,"description":"Project UUID or slug that owns the environment"},"environment_name":{"type":"string","minLength":1,"maxLength":200,"description":"Environment the token opens"}},"required":["project_reference","environment_name"]},"OAuthLogoutResponse":{"type":"object","properties":{"logout":{"type":"boolean","description":"Logout success status"}},"required":["logout"]},"MagicLinkCreateResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status"},"message":{"type":"string","description":"Status message"}},"required":["success","message"]},"MagicLinkCreateRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"User email address","example":"user@example.com"},"redirectUrl":{"type":"string","maxLength":4096,"format":"uri","description":"URL to redirect after verification"},"redirect_url":{"type":"string","maxLength":4096,"format":"uri","description":"URL to redirect after verification"}},"required":["email"]},"ErrorSummary":{"type":"object","properties":{"slug":{"type":"string","example":"resource-not-found"},"title":{"type":"string","example":"Resource Not Found"},"status":{"type":"number","example":404},"category":{"type":"string","example":"RESOURCE"}},"required":["slug","title","status","category"]},"ListErrorsResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorSummary"}}},"required":["errors"]},"ErrorSolution":{"type":"object","properties":{"message":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"example":{"type":"string"},"tips":{"type":"array","items":{"type":"string"}},"relatedErrors":{"type":"array","items":{"type":"string"}}},"required":["message"]},"ErrorDetail":{"type":"object","properties":{"slug":{"type":"string","example":"resource-not-found"},"title":{"type":"string","example":"Resource Not Found"},"status":{"type":"number","example":404},"category":{"type":"string","example":"RESOURCE"},"suggestion":{"type":"string"},"solution":{"$ref":"#/components/schemas/ErrorSolution"},"docs":{"type":"string","example":"https://veryfront.com/docs/api/errors/resource-not-found"}},"required":["slug","title","status","category"]},"AgentRunControlPlaneDispatchAcceptedPayloadRead":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED"]},"requestHash":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["type","requestHash"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED"]},"version":{"type":"number","enum":[2]},"state":{"type":"string","enum":["intent_recorded"]},"runId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"projectId":{"type":"string","format":"uuid"},"leaseOwner":{"type":"string","pattern":"^agent-run-detached:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"dispatchAttemptId":{"type":"string","format":"uuid"},"transportRecoveryAttempt":{"type":"integer","minimum":0},"resumesDispatchAttemptId":{"type":"string","format":"uuid"},"requestHash":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"leaseExpiresAt":{"type":"string","format":"date-time"}},"required":["type","version","state","runId","projectId","leaseOwner","dispatchAttemptId","transportRecoveryAttempt","requestHash","leaseExpiresAt"],"additionalProperties":false}]},"AgentRunAuthorizationSealedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_AUTHORIZATION_SEALED"]}},"required":["type"],"additionalProperties":false},"AgentRunContextCompactedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTEXT_COMPACTED"]}},"required":["type"],"additionalProperties":false},"AgentRunToolExposureCheckpointedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED"]}},"required":["type"],"additionalProperties":false},"AgentRunProviderReplayCheckpointedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED"]}},"required":["type"],"additionalProperties":false},"AgentRunProviderReplayTurnStartedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_TURN_STARTED"]}},"required":["type"],"additionalProperties":false},"AgentRunProviderReplayTurnFinishedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_TURN_FINISHED"]}},"required":["type"],"additionalProperties":false},"AgentRunModelCallContextRecordedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED"]}},"required":["type"],"additionalProperties":false},"AgentRunControlPlaneDispatchAcceptedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED"]}},"required":["type"],"additionalProperties":false},"AgentRunDetachedAcceptedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_DETACHED_ACCEPTED"]}},"required":["type"],"additionalProperties":false},"AgentRunInvokeAgentBillingModeRetainedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_INVOKE_AGENT_BILLING_MODE_RETAINED"]}},"required":["type"],"additionalProperties":false},"AgentRunBillingUsageRetainedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_BILLING_USAGE_RETAINED"]}},"required":["type"],"additionalProperties":false},"AgentRunReplayedUploadsSealedPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_REPLAYED_UPLOADS_SEALED"]}},"required":["type"],"additionalProperties":false},"AgentRunControlPlaneDispatchReceiptPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT"]}},"required":["type"],"additionalProperties":false},"AgentRunToolExposureCheckpointPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT"]}},"required":["type"],"additionalProperties":false},"AgentRunProviderReplayCheckpointPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT"]}},"required":["type"],"additionalProperties":false},"AgentRunModelCallContextPayloadRedacted":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT"]}},"required":["type"],"additionalProperties":false},"RunStartedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["RUN_STARTED"]},"runId":{"type":"string","minLength":1}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["RUN_STARTED"]}},"required":["type"]}]},"RunFinishedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["RUN_FINISHED"]},"runId":{"type":"string","minLength":1},"metadata":{"type":"object","additionalProperties":{}}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["RUN_FINISHED"]}},"required":["type"]}]},"RunErrorPayload":{"type":"object","properties":{"type":{"type":"string","enum":["RUN_ERROR"]},"runId":{"type":"string","minLength":1},"code":{"type":"string","minLength":1},"message":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["RUN_ERROR"]}},"required":["type"]}]},"TextMessageStartPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_START"]},"messageId":{"type":"string","minLength":1},"contentId":{"type":"string","minLength":1},"role":{"type":"string"}},"required":["type","messageId","contentId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_START"]},"messageId":{"type":"string","minLength":1},"contentId":{"type":"string","minLength":1},"role":{"type":"string"}},"required":["type","messageId","contentId"]}]},"TextMessageContentPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"]},"messageId":{"type":"string","minLength":1},"contentId":{"type":"string","minLength":1},"delta":{"type":"string"}},"required":["type","messageId","delta"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"]},"messageId":{"type":"string","minLength":1},"contentId":{"type":"string","minLength":1},"delta":{"type":"string"}},"required":["type","messageId","contentId","delta"]}]},"TextMessageEndPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_END"]},"messageId":{"type":"string","minLength":1},"contentId":{"type":"string","minLength":1}},"required":["type","messageId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_END"]},"messageId":{"type":"string","minLength":1},"contentId":{"type":"string","minLength":1}},"required":["type","messageId","contentId"]}]},"ToolCallStartPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_START"]},"toolCallId":{"type":"string","minLength":1},"toolCallName":{"type":"string","minLength":1},"parentMessageId":{"type":"string","minLength":1}},"required":["type","toolCallId","toolCallName"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_START"]},"toolCallId":{"type":"string","minLength":1},"toolCallName":{"type":"string","minLength":1}},"required":["type","toolCallId","toolCallName"]}]},"ToolCallArgsPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_ARGS"]},"toolCallId":{"type":"string","minLength":1},"delta":{"type":"string"}},"required":["type","toolCallId","delta"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_ARGS"]},"toolCallId":{"type":"string","minLength":1},"delta":{"type":"string"}},"required":["type","toolCallId","delta"]}]},"ToolCallChunkPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_CHUNK"]},"toolCallId":{"type":"string","minLength":1},"delta":{"type":"string"}},"required":["type","toolCallId","delta"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_CHUNK"]},"toolCallId":{"type":"string","minLength":1},"delta":{"type":"string"}},"required":["type","toolCallId","delta"]}]},"ToolCallEndPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_END"]},"toolCallId":{"type":"string","minLength":1}},"required":["type","toolCallId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_END"]},"toolCallId":{"type":"string","minLength":1}},"required":["type","toolCallId"]}]},"ToolCallResultPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_RESULT"]},"toolCallId":{"type":"string","minLength":1},"messageId":{"type":"string","minLength":1},"parentMessageId":{"type":"string","minLength":1},"content":{},"isError":{"type":["boolean","null"]},"role":{"type":"string","enum":["tool"]}},"required":["type","toolCallId","isError"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_RESULT"]},"messageId":{"type":"string","minLength":1},"parentMessageId":{"type":"string","minLength":1},"toolCallId":{"type":"string","minLength":1},"input":{},"content":{},"result":{},"role":{"type":"string","enum":["tool"]},"isError":{"type":["boolean","null"]}},"required":["type","toolCallId"]}]},"StateSnapshotPayload":{"type":"object","properties":{"type":{"type":"string","enum":["STATE_SNAPSHOT"]},"snapshot":{"type":"object","additionalProperties":{}}},"required":["type","snapshot"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["STATE_SNAPSHOT"]},"snapshot":{"type":"object","additionalProperties":{}}},"required":["type","snapshot"]}]},"StateDeltaPayload":{"type":"object","properties":{"type":{"type":"string","enum":["STATE_DELTA"]},"delta":{}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["STATE_DELTA"]},"delta":{"anyOf":[{"type":"object","additionalProperties":{}},{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace","move","copy","test"]},"path":{"type":"string","minLength":1},"from":{"type":"string","minLength":1},"value":{}},"required":["op","path"]}}]}},"required":["type","delta"]}]},"MessagesSnapshotPayload":{"type":"object","properties":{"type":{"type":"string","enum":["MESSAGES_SNAPSHOT"]},"messages":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["type","messages"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["MESSAGES_SNAPSHOT"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"role":{"type":"string","minLength":1},"parts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1}},"required":["type"]}},"content":{}}}}},"required":["type","messages"]}]},"StepStartedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["STEP_STARTED"]},"stepId":{"type":"string","minLength":1},"stepName":{"type":"string","minLength":1},"runtime":{"type":"string","minLength":1}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["STEP_STARTED"]}},"required":["type"]}]},"StepFinishedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["STEP_FINISHED"]},"stepId":{"type":"string","minLength":1},"stepName":{"type":"string","minLength":1},"runtime":{"type":"string","minLength":1},"status":{"type":"string","minLength":1}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["STEP_FINISHED"]}},"required":["type"]}]},"ReasoningStartPayload":{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_START"]},"messageId":{"type":"string","minLength":1}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_START"]}},"required":["type"]}]},"ReasoningMessageStartPayload":{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_START"]},"messageId":{"type":"string","minLength":1}},"required":["type","messageId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_START"]}},"required":["type"]}]},"ReasoningMessageContentPayload":{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_CONTENT"]},"messageId":{"type":"string","minLength":1},"delta":{"type":"string"}},"required":["type","messageId","delta"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_CONTENT"]}},"required":["type"]}]},"ReasoningMessageEndPayload":{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_END"]},"messageId":{"type":"string","minLength":1}},"required":["type","messageId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_MESSAGE_END"]}},"required":["type"]}]},"ReasoningContentPayload":{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_CONTENT"]},"messageId":{"type":"string","minLength":1},"delta":{"type":"string"}},"required":["type","delta"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_CONTENT"]}},"required":["type"]}]},"ReasoningEndPayload":{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_END"]},"messageId":{"type":"string","minLength":1}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["REASONING_END"]}},"required":["type"]}]},"ActivitySnapshotPayload":{"type":"object","properties":{"type":{"type":"string","enum":["ACTIVITY_SNAPSHOT"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["ACTIVITY_SNAPSHOT"]}},"required":["type"]}]},"ActivityDeltaPayload":{"type":"object","properties":{"type":{"type":"string","enum":["ACTIVITY_DELTA"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["ACTIVITY_DELTA"]}},"required":["type"]}]},"AgentRunAuthorizationSealedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_AUTHORIZATION_SEALED"]}},"required":["type"]},"AgentRunRequestEnqueuedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_REQUEST_ENQUEUED"]}},"required":["type"]},"AgentRunDefaultChatStartEnqueuedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_DEFAULT_CHAT_START_ENQUEUED"]}},"required":["type"]},"AgentRunToolResultSubmittedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_SUBMITTED"]}},"required":["type"]},"AgentRunToolResultDeliveryFailedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_RESULT_DELIVERY_FAILED"]}},"required":["type"]},"AgentRunIntegrationConnectionRefusedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_INTEGRATION_CONNECTION_REFUSED"]},"integration":{"type":"string","minLength":1},"toolName":{"type":"string","minLength":1},"message":{"type":"string","minLength":1}},"required":["type","integration","toolName","message"]},"AgentRunRuntimeOwnerBoundPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_RUNTIME_OWNER_BOUND"]}},"required":["type"]},"AgentRunRuntimeInvokeRetriedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_RUNTIME_INVOKE_RETRIED"]}},"required":["type"]},"AgentRunContextCompactedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTEXT_COMPACTED"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTEXT_COMPACTED"]},"summary":{"type":"object","properties":{"text":{"type":"string","minLength":1}},"required":["text"]},"firstKeptEntryId":{"type":"string","minLength":1},"tokensBefore":{"type":"integer","minimum":0},"tokensAfter":{"type":"integer","minimum":0},"tokenBudget":{"type":"integer","exclusiveMinimum":0},"reserveTokens":{"type":"integer","minimum":0},"reason":{"type":"string","enum":["context_window","transport_body"]},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","summary","firstKeptEntryId","tokensBefore","tokensAfter","tokenBudget","reserveTokens","reason"],"additionalProperties":false}]},"AgentRunToolExposureCheckpointedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED"]},"version":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"authorizedCatalogFingerprint":{"type":"string","minLength":1,"maxLength":256},"loadedToolNames":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z][a-zA-Z0-9._:-]*$"}},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","version","loadedToolNames"],"additionalProperties":false}]},"AgentRunProviderReplayCheckpointedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED"]},"version":{"type":"number","enum":[1]},"messageId":{"type":"string","minLength":1,"maxLength":256},"provider":{"type":"string","enum":["anthropic","openai-responses"]},"providerBlocks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["provider-block"]},"provider":{"type":"string","enum":["anthropic","openai-responses"]},"block":{"type":"object","additionalProperties":{}}},"required":["type","provider","block"],"additionalProperties":false},"minItems":1,"maxItems":100},"providerBlockPositions":{"type":"array","items":{"type":"integer","minimum":0,"maximum":10000},"minItems":1,"maxItems":100},"providerMessageBlockCounts":{"type":"array","items":{"type":"integer","minimum":1,"maximum":100},"minItems":1,"maxItems":100},"totalPartCount":{"type":"integer","minimum":1,"maximum":10000},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","version","messageId","provider","providerBlocks","providerBlockPositions","totalPartCount"],"additionalProperties":false}]},"AgentRunProviderReplayTurnStartedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_TURN_STARTED"]}},"required":["type"]},"AgentRunProviderReplayTurnFinishedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_TURN_FINISHED"]}},"required":["type"]},"AgentRunModelCallContextRecordedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED"]},"model":{"type":"object","properties":{"id":{"type":"string","minLength":1},"modelProvider":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false},"request":{"type":"object","properties":{"maxOutputTokens":{"type":"number","minimum":0},"temperature":{"type":"number"},"topP":{"type":"number"},"topK":{"type":"number"},"stopSequences":{"type":"array","items":{"type":"string"}},"seed":{"type":"number"},"presencePenalty":{"type":"number"},"frequencyPenalty":{"type":"number"},"reasoning":{"type":"object","properties":{"enabled":{"type":"boolean"},"effort":{"type":"string","enum":["low","medium","high","max"]},"budgetTokens":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false},"messages":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"role":{"type":"string","enum":["system"]},"content":{"type":"string"},"providerOptions":{"type":"object","additionalProperties":{"type":"object","properties":{"cacheControl":{"type":"object","properties":{"type":{"type":"string","enum":["ephemeral"]},"ttl":{"type":"string","enum":["5m","1h"]}},"required":["type"],"additionalProperties":false}},"required":["cacheControl"],"additionalProperties":false}}},"required":["role","content"],"additionalProperties":false},{"type":"object","properties":{"role":{"type":"string","enum":["user"]},"content":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["image","file"]},"mediaType":{"type":"string"},"url":{"type":"string"},"filename":{"type":"string"}},"required":["type","mediaType","url"],"additionalProperties":false}]}}},"required":["role","content"],"additionalProperties":false},{"type":"object","properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["tool-call"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"input":{},"providerExecuted":{"type":"boolean"}},"required":["type","toolCallId","toolName","input"],"additionalProperties":false}]}}},"required":["role","content"],"additionalProperties":false},{"type":"object","properties":{"role":{"type":"string","enum":["tool"]},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["tool-result"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"output":{"type":"object","properties":{"type":{"type":"string","enum":["json"]},"value":{}},"required":["type","value"],"additionalProperties":false}},"required":["type","toolCallId","toolName","output"],"additionalProperties":false}}},"required":["role","content"],"additionalProperties":false}]}},"tools":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["function"]},"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{}},"required":["type","name","inputSchema"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["provider"]},"name":{"type":"string"},"id":{"type":"string"},"args":{"type":"object","additionalProperties":{}}},"required":["type","name","id","args"],"additionalProperties":false}]}},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","messages"],"additionalProperties":false}]},"AgentRunControlPlaneDispatchAcceptedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED"]},"requestHash":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["type","requestHash"],"additionalProperties":false}]},"AgentRunDetachedAcceptedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_DETACHED_ACCEPTED"]},"leaseOwner":{"type":"string","minLength":1},"dispatchAttemptId":{"type":"string","format":"uuid"}},"required":["type","leaseOwner","dispatchAttemptId"]},"AgentRunInvokeAgentBillingModeRetainedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_INVOKE_AGENT_BILLING_MODE_RETAINED"]}},"required":["type"]},"AgentRunBillingUsageRetainedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_BILLING_USAGE_RETAINED"]}},"required":["type"]},"AgentRunReplayedUploadsSealedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_REPLAYED_UPLOADS_SEALED"]}},"required":["type"]},"ToolCallStatusChangedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"]},"toolCallId":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"toolCallName":{"type":["string","null"],"minLength":1}},"required":["type","toolCallId","status","toolCallName"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"]},"toolCallId":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"toolCallName":{"type":["string","null"],"minLength":1}},"required":["type","toolCallId","status","toolCallName"]}]},"InputRequestCreatedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_CREATED"]},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"]}},"required":["type","inputRequest"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_CREATED"]},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"]}},"required":["type","inputRequest"]}]},"InputRequestUpdatedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"]},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"]}},"required":["type","inputRequest"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"]},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"]}},"required":["type","inputRequest"]}]},"ChildRunStatusChangedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"]},"toolCallId":{"type":"string","minLength":1},"childRunId":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"childConversationId":{"type":["string","null"],"minLength":1},"childMessageId":{"type":["string","null"],"minLength":1},"childAgentId":{"type":["string","null"],"minLength":1},"description":{"type":"string","minLength":1}},"required":["type","toolCallId","childRunId","status"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"]},"toolCallId":{"type":"string","minLength":1},"childRunId":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"childConversationId":{"type":["string","null"],"minLength":1},"childMessageId":{"type":["string","null"],"minLength":1},"childAgentId":{"type":["string","null"],"minLength":1},"description":{"type":"string","minLength":1}},"required":["type","toolCallId","childRunId","status"]}]},"ModelCallCompletedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["MODEL_CALL_COMPLETED"]},"provider":{"type":"string","minLength":1},"model":{"type":"string","minLength":1},"inputTokens":{"type":"integer","minimum":0},"outputTokens":{"type":"integer","minimum":0},"cacheCreationTokens":{"type":"integer","minimum":0},"cacheReadTokens":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0},"costCredits":{"type":"string","minLength":1},"latencyMs":{"type":["integer","null"],"minimum":0},"usageCaptureStatus":{"type":"string","enum":["complete","partial","missing"]},"providerRequestId":{"type":["string","null"],"minLength":1},"modelCallContextEventId":{"type":["integer","null"],"exclusiveMinimum":0}},"required":["type","provider","model","inputTokens","outputTokens","cacheCreationTokens","cacheReadTokens","totalTokens","costCredits","latencyMs","usageCaptureStatus","providerRequestId","modelCallContextEventId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["MODEL_CALL_COMPLETED"]},"provider":{"type":"string","minLength":1},"model":{"type":"string","minLength":1},"inputTokens":{"type":"integer","minimum":0},"outputTokens":{"type":"integer","minimum":0},"cacheCreationTokens":{"type":"integer","minimum":0},"cacheReadTokens":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0},"costCredits":{"type":"string","minLength":1},"latencyMs":{"type":["integer","null"],"minimum":0},"usageCaptureStatus":{"type":"string","enum":["complete","partial","missing"]},"providerRequestId":{"type":["string","null"],"minLength":1},"modelCallContextEventId":{"type":["integer","null"],"exclusiveMinimum":0}},"required":["type","provider","model","inputTokens","outputTokens","cacheCreationTokens","cacheReadTokens","totalTokens","costCredits","latencyMs","usageCaptureStatus","providerRequestId","modelCallContextEventId"]}]},"RunParkedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["RUN_PARKED"]},"runId":{"type":"string","minLength":1},"reason":{"type":"string","minLength":1},"lastEventId":{"type":"integer","minimum":0}},"required":["type","runId","reason","lastEventId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["RUN_PARKED"]},"runId":{"type":"string","minLength":1},"reason":{"type":"string","minLength":1},"lastEventId":{"type":"integer","minimum":0}},"required":["type","runId","reason","lastEventId"]}]},"RunLogCapturedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["RUN_LOG_CAPTURED"]},"logs":{"type":"string"}},"required":["type","logs"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["RUN_LOG_CAPTURED"]},"logs":{"type":"string"}},"required":["type","logs"]}]},"StreamHeartbeatEmittedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"]},"runId":{"type":"string","minLength":1},"lastEventId":{"type":"integer","minimum":0}},"required":["type","runId","lastEventId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"]},"runId":{"type":"string","minLength":1},"lastEventId":{"type":"integer","minimum":0}},"required":["type","runId","lastEventId"]}]},"UrlCitedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["URL_CITED"]},"url":{"type":"string","minLength":1},"sourceId":{"type":"string","minLength":1},"title":{"type":"string","minLength":1}},"required":["type","url","sourceId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["URL_CITED"]},"url":{"type":"string","minLength":1},"sourceId":{"type":"string","minLength":1},"title":{"type":"string","minLength":1}},"required":["type","url","sourceId"]}]},"DocumentCitedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["DOCUMENT_CITED"]},"mediaType":{"type":"string","minLength":1},"sourceId":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"filename":{"type":"string","minLength":1}},"required":["type","mediaType","sourceId"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["DOCUMENT_CITED"]},"mediaType":{"type":"string","minLength":1},"sourceId":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"filename":{"type":"string","minLength":1}},"required":["type","mediaType","sourceId"]}]},"FileAttachedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["FILE_ATTACHED"]},"mediaType":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"filename":{"type":"string","minLength":1}},"required":["type","mediaType"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["FILE_ATTACHED"]},"mediaType":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"filename":{"type":"string","minLength":1}},"required":["type","mediaType"]}]},"FilesChangedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["FILES_CHANGED"]},"id":{"type":["string","null"],"minLength":1},"status":{"type":["string","null"],"minLength":1},"changes":{}},"required":["type","id","status","changes"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["FILES_CHANGED"]},"id":{"type":["string","null"],"minLength":1},"status":{"type":["string","null"],"minLength":1},"changes":{}},"required":["type","id","status","changes"]}]},"RuntimeEventRecordedPayload":{"type":"object","properties":{"type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"]},"runtime":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"value":{}},"required":["type","runtime","kind","value"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"]},"runtime":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"value":{}},"required":["type","runtime","kind","value"]}]},"AgentRunControlPlaneDispatchReceiptPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT"]},"requestHash":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["type","requestHash"],"additionalProperties":false}]},"AgentRunToolExposureCheckpointPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT"]},"version":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"authorizedCatalogFingerprint":{"type":"string","minLength":1,"maxLength":256},"loadedToolNames":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z][a-zA-Z0-9._:-]*$"}},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","version","loadedToolNames"],"additionalProperties":false}]},"AgentRunProviderReplayCheckpointPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT"]},"version":{"type":"number","enum":[1]},"messageId":{"type":"string","minLength":1,"maxLength":256},"provider":{"type":"string","enum":["anthropic","openai-responses"]},"providerBlocks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["provider-block"]},"provider":{"type":"string","enum":["anthropic","openai-responses"]},"block":{"type":"object","additionalProperties":{}}},"required":["type","provider","block"],"additionalProperties":false},"minItems":1,"maxItems":100},"providerBlockPositions":{"type":"array","items":{"type":"integer","minimum":0,"maximum":10000},"minItems":1,"maxItems":100},"providerMessageBlockCounts":{"type":"array","items":{"type":"integer","minimum":1,"maximum":100},"minItems":1,"maxItems":100},"totalPartCount":{"type":"integer","minimum":1,"maximum":10000},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","version","messageId","provider","providerBlocks","providerBlockPositions","totalPartCount"],"additionalProperties":false}]},"AgentRunModelCallContextPayload":{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT"]}},"required":["type"],"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT"]},"model":{"type":"object","properties":{"id":{"type":"string","minLength":1},"modelProvider":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false},"request":{"type":"object","properties":{"maxOutputTokens":{"type":"number","minimum":0},"temperature":{"type":"number"},"topP":{"type":"number"},"topK":{"type":"number"},"stopSequences":{"type":"array","items":{"type":"string"}},"seed":{"type":"number"},"presencePenalty":{"type":"number"},"frequencyPenalty":{"type":"number"},"reasoning":{"type":"object","properties":{"enabled":{"type":"boolean"},"effort":{"type":"string","enum":["low","medium","high","max"]},"budgetTokens":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false},"messages":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"role":{"type":"string","enum":["system"]},"content":{"type":"string"},"providerOptions":{"type":"object","additionalProperties":{"type":"object","properties":{"cacheControl":{"type":"object","properties":{"type":{"type":"string","enum":["ephemeral"]},"ttl":{"type":"string","enum":["5m","1h"]}},"required":["type"],"additionalProperties":false}},"required":["cacheControl"],"additionalProperties":false}}},"required":["role","content"],"additionalProperties":false},{"type":"object","properties":{"role":{"type":"string","enum":["user"]},"content":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["image","file"]},"mediaType":{"type":"string"},"url":{"type":"string"},"filename":{"type":"string"}},"required":["type","mediaType","url"],"additionalProperties":false}]}}},"required":["role","content"],"additionalProperties":false},{"type":"object","properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["tool-call"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"input":{},"providerExecuted":{"type":"boolean"}},"required":["type","toolCallId","toolName","input"],"additionalProperties":false}]}}},"required":["role","content"],"additionalProperties":false},{"type":"object","properties":{"role":{"type":"string","enum":["tool"]},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["tool-result"]},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"output":{"type":"object","properties":{"type":{"type":"string","enum":["json"]},"value":{}},"required":["type","value"],"additionalProperties":false}},"required":["type","toolCallId","toolName","output"],"additionalProperties":false}}},"required":["role","content"],"additionalProperties":false}]}},"tools":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["function"]},"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{}},"required":["type","name","inputSchema"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["provider"]},"name":{"type":"string"},"id":{"type":"string"},"args":{"type":"object","additionalProperties":{}}},"required":["type","name","id","args"],"additionalProperties":false}]}},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","messages"],"additionalProperties":false}]}},"parameters":{"ProjectReference":{"schema":{"$ref":"#/components/schemas/ProjectReference"},"required":true,"description":"Project slug, UUID, or domain that identifies the project.","name":"project_reference","in":"path"},"PaginationCursor":{"schema":{"$ref":"#/components/schemas/PaginationCursor"},"required":false,"description":"Opaque cursor pointing at the next page. Omit it to read the first page.","name":"cursor","in":"query"},"PaginationLimit":{"schema":{"$ref":"#/components/schemas/PaginationLimit"},"required":false,"description":"Maximum number of entries to return. Defaults to 20 and is capped at 100.","name":"limit","in":"query"}},"securitySchemes":{"hostBasicAuth":{"type":"http","scheme":"basic","description":"Internal host credentials; public user and API-key credentials are insufficient."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT or API Key","description":"Use a JWT bearer token or a Veryfront API key in the `Authorization` header."},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative API key header for `vf_<prefix>_<secret>` tokens."},"runEventWriterAuth":{"type":"http","scheme":"bearer","bearerFormat":"Run Event Writer JWT","description":"A run-bound Veryfront runtime event-writer token in the `Authorization` header."},"runExecutionAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Server-issued credential bound to project, run, registered runtime, execution generation, audience, expiry, and explicitly allowed operations; user/API-key editor access is insufficient."},"projectRunStopAuth":{"type":"http","scheme":"bearer","bearerFormat":"Project Run Stop JWT","description":"A project-run stop capability bound to one run, project, and executor attempt."}}},"paths":{"/agents":{"get":{"operationId":"listAccessibleAgents","tags":["Accessible agents"],"summary":"List agents","description":"List agents visible across projects that you can access, including agents with `can_run: false`.\n\nFollow non-null `page_info.next` even when `data` is empty. A response budget can leave project scan work for the next request; the cursor does not guarantee more matching agents. Use the agent template catalog to find public templates.","parameters":[{"schema":{"type":"string","description":"Opaque cursor returned from `page_info.next` or `page_info.prev`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of agents to return, from 1 to 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Case-insensitive search across agent names, agent IDs, and project names. Requires `sort=+project_name` and `access=all`, with no `kind` or `runtime_status` filter. Any cursor must come from a page with compatible search options. Other combinations return `400`."},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Optional project slug or ID to narrow the account-wide collection."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","enum":["all","project","shared"],"default":"all","description":"Access source filter. `shared` is reserved for direct shared-agent grants and currently returns an empty set."},"required":false,"name":"access","in":"query"},{"schema":{"type":"string","enum":["source_project_agent","installed_project_agent"],"description":"Filter by project-agent kind."},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","enum":["ready","offline","not_applicable","unknown"],"description":"Filter by runtime readiness status."},"required":false,"name":"runtime_status","in":"query"},{"schema":{"type":"string","enum":["+name","-name","+project_name","-project_name","+updated_at","-updated_at"],"default":"+project_name","description":"Sort order. Supported values: +name, -name, +project_name, -project_name, +updated_at, -updated_at."},"required":false,"name":"sort","in":"query"}],"responses":{"200":{"description":"Paginated account-wide accessible agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque stable account-wide agent row ID."},"agent_id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"avatar_url":{"type":["string","null"],"format":"uri"},"kind":{"type":"string","enum":["source_project_agent","installed_project_agent"]},"source_type":{"type":"string","enum":["project","catalog_install"]},"can_run":{"type":"boolean","description":"Whether a run can start on this agent. False when the project has no billing owner; starting a run there fails with 422 project-billing-owner-missing."},"provider":{"type":"object","properties":{"organization":{"type":"string"},"url":{"type":"string"}},"required":["organization","url"]},"version":{"type":"string"},"capabilities":{"type":"object","properties":{"streaming":{"type":"boolean"},"push_notifications":{"type":"boolean"},"extensions":{"type":"array","items":{"type":"string"}}},"required":["streaming","push_notifications","extensions"]},"default_input_modes":{"type":"array","items":{"type":"string"}},"default_output_modes":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["id","name"]}},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1},{"type":"object","properties":{"title":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1}},"required":["title","prompt"],"additionalProperties":false}]}},"project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"name":{"type":"string"}},"required":["id","reference","name"]},"access":{"type":"object","properties":{"type":{"type":"string","enum":["project","project_install","shared"]},"relation":{"type":"string","enum":["owner","admin","editor","viewer"]}},"required":["type","relation"]},"runtime_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","offline","not_applicable","unknown"]},"reason":{"type":["string","null"]},"runtime_target_kind":{"type":["string","null"],"enum":["registered_push_service","pull_worker",null]},"runtime_service_key":{"type":["string","null"]}},"required":["status","reason","runtime_target_kind","runtime_service_key"]},"model":{"type":["string","null"]},"url":{"type":"string"},"updated_at":{"type":["string","null"]}},"required":["id","agent_id","name","description","kind","source_type","can_run","provider","version","capabilities","default_input_modes","default_output_modes","tools","skills","project","access","runtime_readiness","model","url","updated_at"]}},"page_info":{"allOf":[{"$ref":"#/components/schemas/PageInfo"},{"type":"object","properties":{"next":{"type":["string","null"],"description":"Opaque cursor to continue matching rows or remaining scan work. Follow it even when this page has no agents; null means no continuation remains."}}}],"description":"Pagination cursor values for traversing the result set."}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/agent-templates":{"get":{"operationId":"browseAgentTemplates","tags":["Agent templates"],"summary":"Browse agent templates","description":"Returns the unified agent template catalog assembled from configured template projects and approved installable registry entries. Template agents expose the fork action. Installable agents expose the install action and their runtime service key, but never expose internal invoke URLs.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Page size (1-200, default 100)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Zero-based offset into the flat catalog."},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Filter to a single category ID."},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Case-insensitive substring search across agent name, description, `agent_id`, and `category_label`. Uses the catalog cache; template edits appear within approximately 60 seconds.","example":"support"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["name","agent_id","category_label"],"description":"Sort field. Defaults to \"name\".","example":"name"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort order. Defaults to \"asc\".","example":"asc"},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated agent template catalog","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"agent_id":{"type":"string"},"kind":{"type":"string","enum":["template_agent","installable_agent"],"description":"Catalog identity kind. Template agents are fork-only; installable agents are installed into a project before they can run."},"name":{"type":"string"},"description":{"type":["string","null"]},"avatar_url":{"type":["string","null"],"format":"uri"},"category_id":{"type":"string"},"category_label":{"type":"string"},"provider_name":{"type":"string"},"provider_url":{"type":["string","null"],"format":"uri"},"model":{"type":["string","null"]},"version":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"string","minLength":1}},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1},{"type":"object","properties":{"title":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1}},"required":["title","prompt"],"additionalProperties":false}]}},"actions":{"type":"array","items":{"type":"string","enum":["fork","install"]},"description":"Allowed catalog actions for the caller. Clients should use this instead of inferring behavior from provenance."},"template_project":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the template project used as the forked project name."},"project_reference":{"type":"string","description":"Template project reference used by the fork flow."},"source_path":{"type":["string","null"],"description":"Source path of the agent inside the template project."}},"required":["name","project_reference","source_path"],"description":"Present for template_agent items; omitted for installable_agent items."},"installability":{"type":"object","properties":{"status":{"type":"string","enum":["installable","already_installed","unavailable"]},"reason":{"type":["string","null"]}},"required":["status","reason"],"description":"Project-install state for installable_agent items."},"origin":{"type":"string","enum":["veryfront","user"]},"runtime_mode":{"type":"string","enum":["push_service","pull_worker","none"]},"runtime_service_key":{"type":["string","null"],"description":"Runtime registry key when the entry is backed by a registered service. Internal invoke URLs are intentionally not exposed."},"environment_scope":{"type":"string","enum":["development","staging","production","all"]},"card":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"provider":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}},"required":["name","url"]},"version":{"type":["string","null"]},"runtime_mode":{"type":"string","enum":["push_service","pull_worker","none"]},"runtime_service_key":{"type":["string","null"]},"default_input_modes":{"type":"array","items":{"type":"string"}},"default_output_modes":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["id","name"]}},"tools":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","provider","version","runtime_mode","runtime_service_key","default_input_modes","default_output_modes","skills","tools"]}},"required":["id","agent_id","kind","name","description","category_id","category_label","provider_name","provider_url","version","actions"]}},"total":{"type":"integer"},"has_more":{"type":"boolean"},"next_offset":{"type":["integer","null"]}},"required":["items","total","has_more","next_offset"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/projects/{project_reference}/agents":{"get":{"operationId":"listAgents","tags":["Project agents"],"summary":"List project agents","description":"List agents from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCardList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"post":{"operationId":"createAgent","tags":["Project agents"],"summary":"Create agent","description":"Create an agent document.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Unique identifier for the record."},"name":{"type":"string","minLength":1,"description":"Human-readable name for the record."},"description":{"type":["string","null"],"description":"Human-readable description for the record."},"model":{"type":["string","null"],"description":"AI model id or alias. Call list_models for the ids this deployment serves; never invent a version suffix."},"system_prompt":{"type":"string","minLength":1},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean","description":"The enabled associated with this record."},"budget_tokens":{"type":"number","exclusiveMinimum":0,"description":"The budget tokens associated with this record."}},"required":["enabled"],"additionalProperties":false,"description":"The thinking associated with this record."},"temperature":{"type":["number","null"],"minimum":0,"maximum":2,"description":"The temperature associated with this record."},"max_steps":{"type":["integer","null"],"exclusiveMinimum":0,"description":"The max steps associated with this record."},"allowed_models":{"type":"array","items":{"type":"string","minLength":1,"description":"One allowed model item associated with this record."},"description":"AI model ids or aliases the agent may switch between. Call list_models for the accepted ids."},"skill_ids":{"type":"array","items":{"type":"string","minLength":1,"description":"One skill id item associated with this record."},"description":"The skill ids associated with this record."},"skill_selection":{"type":"object","properties":{"kind":{"type":"string","enum":["omitted","explicit"],"description":"The kind associated with this record."},"skill_ids":{"type":"array","items":{"type":"string","minLength":1,"description":"One skill id item associated with this record."},"default":[],"description":"The skill ids associated with this record."}},"required":["kind"],"description":"The skill selection associated with this record."},"all_tools_enabled":{"type":"boolean","description":"The all tools enabled associated with this record."},"tool_ids":{"type":"array","items":{"type":"string","minLength":1,"description":"One tool id item associated with this record."},"description":"Tool IDs attached to the record, including project-local, built-in, and integration catalog tools."},"provider_tool_ids":{"type":"array","items":{"type":"string","minLength":1,"description":"One provider tool id item associated with this record."},"description":"Provider-native model tool IDs attached to the record."},"suggestions":{"type":["array","null"],"items":{"anyOf":[{"type":"string","minLength":1,"description":"The option 1 associated with this record."},{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Short human-readable title for the record."},"prompt":{"type":"string","minLength":1,"description":"The prompt associated with this record."}},"required":["title","prompt"],"additionalProperties":false,"description":"Structured option 2 details associated with this record."}],"description":"One suggestion item associated with this record."},"description":"The suggestions associated with this record."},"avatar":{"type":["object","null"],"properties":{"seed":{"type":"string","minLength":1,"maxLength":128,"description":"The seed associated with this record."},"archetype":{"type":"string","enum":["upright","slumped","alert","profile","leaning","crouched","tall","spread","happy","sad","angry","surprised","sleepy","curious"],"description":"The archetype associated with this record."},"texture":{"type":"string","pattern":"^(?:[0-9]|none)$","description":"The texture associated with this record."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"The color associated with this record."},"shape":{"type":"string","enum":["snircle","circle","square"],"description":"The shape associated with this record."},"matrix":{"type":"string","pattern":"^[012]{16}$","description":"The matrix associated with this record."}},"description":"The avatar associated with this record."},"avatar_url":{"type":["string","null"],"format":"uri","description":"The avatar url associated with this record."},"security_enabled":{"type":"boolean","description":"Whether the agent default security guardrails are enabled."}},"required":["id","name","system_prompt"]}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectAgent"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/agents/{agent_id}":{"get":{"operationId":"getAgent","tags":["Project agents"],"summary":"Get agent","description":"Return an agent document.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Agent identifier"},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Agent document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectAgent"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"put":{"operationId":"updateAgent","tags":["Project agents"],"summary":"Update agent","description":"Update an agent document.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Agent identifier"},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Human-readable name for the record."},"description":{"type":["string","null"],"description":"Human-readable description for the record."},"model":{"type":["string","null"],"description":"AI model id or alias. Call list_models for the ids this deployment serves; never invent a version suffix."},"system_prompt":{"type":"string","minLength":1},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean","description":"The enabled associated with this record."},"budget_tokens":{"type":"number","exclusiveMinimum":0,"description":"The budget tokens associated with this record."}},"required":["enabled"],"additionalProperties":false,"description":"Structured thinking details associated with this record."},"temperature":{"type":["number","null"],"minimum":0,"maximum":2,"description":"The temperature associated with this record."},"max_steps":{"type":["integer","null"],"exclusiveMinimum":0,"description":"The max steps associated with this record."},"allowed_models":{"type":"array","items":{"type":"string","minLength":1,"description":"One allowed model item associated with this record."},"description":"AI model ids or aliases the agent may switch between. Call list_models for the accepted ids."},"skill_ids":{"type":"array","items":{"type":"string","minLength":1,"description":"One skill id item associated with this record."},"description":"List of skill ids associated with this record."},"skill_selection":{"type":"object","properties":{"kind":{"type":"string","enum":["omitted","explicit"],"description":"The kind associated with this record."},"skill_ids":{"type":"array","items":{"type":"string","minLength":1,"description":"One skill id item associated with this record."},"default":[],"description":"The skill ids associated with this record."}},"required":["kind"],"description":"Structured skill selection details associated with this record."},"all_tools_enabled":{"type":"boolean","description":"The all tools enabled associated with this record."},"tool_ids":{"type":"array","items":{"type":"string","minLength":1,"description":"One tool id item associated with this record."},"description":"Tool IDs attached to the record, including project-local, built-in, and integration catalog tools."},"provider_tool_ids":{"type":"array","items":{"type":"string","minLength":1,"description":"One provider tool id item associated with this record."},"description":"Provider-native model tool IDs attached to the record."},"suggestions":{"type":["array","null"],"items":{"anyOf":[{"type":"string","minLength":1,"description":"The option 1 associated with this record."},{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Short human-readable title for the record."},"prompt":{"type":"string","minLength":1,"description":"The prompt associated with this record."}},"required":["title","prompt"],"additionalProperties":false,"description":"Structured option 2 details associated with this record."}],"description":"One suggestion item associated with this record."},"description":"List of suggestions associated with this record."},"avatar":{"type":["object","null"],"properties":{"seed":{"type":"string","minLength":1,"maxLength":128,"description":"The seed associated with this record."},"archetype":{"type":"string","enum":["upright","slumped","alert","profile","leaning","crouched","tall","spread","happy","sad","angry","surprised","sleepy","curious"],"description":"The archetype associated with this record."},"texture":{"type":"string","pattern":"^(?:[0-9]|none)$","description":"The texture associated with this record."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"The color associated with this record."},"shape":{"type":"string","enum":["snircle","circle","square"],"description":"The shape associated with this record."},"matrix":{"type":"string","pattern":"^[012]{16}$","description":"The matrix associated with this record."}},"description":"Structured avatar details associated with this record."},"avatar_url":{"type":["string","null"],"format":"uri","description":"The avatar url associated with this record."},"security_enabled":{"type":"boolean","description":"Whether the agent default security guardrails are enabled."},"id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Unique identifier for the record."}}}}}},"responses":{"200":{"description":"Agent updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectAgent"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"delete":{"operationId":"deleteAgent","tags":["Project agents"],"summary":"Delete agent","description":"Delete an agent document.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Agent identifier"},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"204":{"description":"Agent deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/agents/{agent_id}/rename":{"post":{"operationId":"renameAgent","tags":["Project agents"],"summary":"Rename agent","description":"Renames an agent and moves its labels to the new identifier.\n\nThe request is rejected if the new identifier is in use, if files such as `agents/{agent_id}/SKILL.md` would remain under the old identifier, or if schedules or channel bindings still reference the agent.\n\nGenerated avatars are copied to the new identifier. The original upload remains available to preview branches and releases that still reference it. The platform removes it asynchronously after those references are gone.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Current agent identifier"},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_agent_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"New agent identifier. Must not be occupied by another agent."}},"required":["new_agent_id"]}}}},"responses":{"200":{"description":"Agent renamed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectAgent"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/capabilities":{"get":{"operationId":"getProjectCapabilities","tags":["Agent Capabilities"],"summary":"Get project capabilities","description":"Return project capabilities for the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Resolved project capabilities","content":{"application/json":{"schema":{"type":"object","properties":{"resolved_capabilities":{"type":"object","properties":{"source_target":{"type":"object","properties":{"kind":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"skills":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["project"]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"allowed_tools":{"type":"array","items":{"type":"string"}}},"required":["type","id","name","description","source_path","edit_mode"],"title":"ProjectSkill"},{"type":"object","properties":{"type":{"type":"string","enum":["agent"]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["type","id","name"],"title":"AgentSkill"}]}},"tools":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["control_plane"]},"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","additionalProperties":{}}},"required":["type","name"],"title":"ControlPlaneTool"},{"type":"object","properties":{"type":{"type":"string","enum":["integration"]},"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","additionalProperties":{}}},"required":["type","name","description","input_schema"],"title":"IntegrationTool"},{"type":"object","properties":{"type":{"type":"string","enum":["project"]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":["object","null"],"additionalProperties":{}}},"required":["type","id","name","source_path","edit_mode"],"title":"ProjectTool"}]}},"integrations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tool_names":{"type":"array","items":{"type":"string"}}},"required":["id","name","tool_names"]}},"tool_resolution":{"type":"array","items":{"type":"object","properties":{"tool_name":{"type":"string"},"source_selected":{"type":"boolean"},"catalog_available":{"type":"boolean"},"catalog_state":{"type":"string","enum":["available","removed"]},"effective_authorization":{"type":"string","enum":["authorized","restricted_by_policy","catalog_unavailable"]},"policy":{"type":"object","properties":{"state":{"type":"string","enum":["absent","allowed","restricted"]},"scope":{"type":"string","enum":["project","user"]},"allowed_tools":{"type":["array","null"],"items":{"type":"string"}},"execution_mode":{"type":"string","enum":["real","mock"]}},"required":["state","scope","allowed_tools","execution_mode"]},"credential_requirement":{"type":"object","properties":{"mode":{"type":"string","enum":["oauth_connection","project_credentials","none"]},"managed_oauth":{"type":"boolean"},"byo_oauth_app_override":{"type":"object","properties":{"supported":{"type":"boolean"},"required":{"type":"boolean"},"client_id_env_var":{"type":["string","null"]},"client_secret_env_var":{"type":["string","null"]}},"required":["supported","required","client_id_env_var","client_secret_env_var"]},"mandatory_env_vars":{"type":"array","items":{"type":"string"}}},"required":["mode","managed_oauth","byo_oauth_app_override","mandatory_env_vars"]},"connection_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","required","not_applicable","unknown"]},"scope":{"type":["string","null"],"enum":["project","user",null]},"connected_count":{"type":["integer","null"],"minimum":0}},"required":["status","scope","connected_count"]}},"required":["tool_name","source_selected","catalog_available","catalog_state","effective_authorization","policy","credential_requirement","connection_readiness"]}},"tool_access":{"type":"object","properties":{"version":{"type":"number","enum":[1],"description":"The version associated with this tool result."},"freshness":{"type":"object","properties":{"resolved_at":{"type":"string","format":"date-time","description":"The resolved at associated with this tool result."},"valid_for_ms":{"type":"integer","exclusiveMinimum":0,"description":"The valid for ms associated with this tool result."},"fail_closed_on_expiry":{"type":"boolean","enum":[true],"description":"The fail closed on expiry associated with this tool result."}},"required":["resolved_at","valid_for_ms","fail_closed_on_expiry"],"description":"Structured freshness details associated with this tool result."},"inputs":{"type":"object","properties":{"capabilities":{"type":"array","items":{"type":"string","enum":["project.read","project.settings.manage","project.delete","project.members.read","project.members.manage","project.invites.read","project.invites.manage","project.files.read","project.files.write","project.realtime.connect","project.realtime.write","project.files.admin","project.uploads.read","project.uploads.write","project.uploads.admin","project.knowledge.read","project.knowledge.write","project.releases.read","project.releases.write","project.deployments.read","project.deployments.write","project.deploy.execute","project.runtime.manage","project.sandboxes.manage","project.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.runs.admin","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","project.conversations.create","project.integrations.read","project.integrations.connect","project.integrations.configure","project.api_keys.read","project.api_keys.manage","project.cache.read","project.cache.write","project.logs.read","project.metrics.read","project.resources.read"],"description":"One capability item associated with this tool result."},"description":"List of capabilities associated with this tool result."},"billing":{"type":"object","properties":{"collaboration_allowed":{"type":"boolean","description":"The collaboration allowed associated with this tool result."},"can_invite":{"type":"boolean","description":"The can invite associated with this tool result."}},"required":["collaboration_allowed","can_invite"],"description":"Structured billing details associated with this tool result."},"entitlements":{"type":"object","properties":{"dedicated_runtime":{"type":"boolean","description":"The dedicated runtime associated with this tool result."},"custom_domains":{"type":"boolean","description":"The custom domains associated with this tool result."},"export_apps":{"type":"boolean","description":"The export apps associated with this tool result."}},"required":["dedicated_runtime","custom_domains","export_apps"],"description":"Structured entitlements details associated with this tool result."}},"required":["capabilities","billing","entitlements"],"description":"Structured inputs details associated with this tool result."},"families":{"type":"array","items":{"type":"object","properties":{"family":{"type":"string","enum":["collaboration","runtime","domains","export"],"description":"The family associated with this tool result."},"default_decision":{"type":"object","properties":{"visibility":{"type":"string","enum":["visible","hidden"],"description":"The visibility associated with this tool result."},"reason_code":{"type":"string","enum":["allowed","missing_capability","billing_plan_restriction","billing_seat_limit","target_not_supported","resource_state_restriction","policy_exception","unknown"],"description":"The reason code associated with this tool result."},"message":{"type":"string","description":"The message associated with this tool result."}},"required":["visibility","reason_code"],"description":"Structured default decision details associated with this tool result."},"action_overrides":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["create_invite","delete_member","create_server","delete_server","create_domain","download_release"],"description":"The action associated with this tool result."},"decision":{"type":"object","properties":{"visibility":{"type":"string","enum":["visible","hidden"],"description":"The visibility associated with this tool result."},"reason_code":{"type":"string","enum":["allowed","missing_capability","billing_plan_restriction","billing_seat_limit","target_not_supported","resource_state_restriction","policy_exception","unknown"],"description":"The reason code associated with this tool result."},"message":{"type":"string","description":"The message associated with this tool result."}},"required":["visibility","reason_code"],"description":"Structured default decision details associated with this tool result."}},"required":["action","decision"],"description":"One action override item associated with this tool result."},"description":"List of action overrides associated with this tool result."}},"required":["family","default_decision","action_overrides"],"description":"One family item associated with this tool result."},"description":"List of families associated with this tool result."}},"required":["version","freshness","inputs","families"]},"prompts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]}},"required":["id","name","source_path","edit_mode"]}},"workflows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"version":{"type":["string","null"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}},"schedulable":{"type":"boolean"}},"required":["id","name","target","source_path","edit_mode","schedulable"]}},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}},"schedulable":{"type":"boolean"}},"required":["id","name","target","source_path","edit_mode","schedulable"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"provider":{"type":"object","properties":{"organization":{"type":"string"},"url":{"type":"string"}},"required":["organization","url"]},"version":{"type":"string"},"capabilities":{"type":"object","properties":{"streaming":{"type":"boolean"},"push_notifications":{"type":"boolean"},"extensions":{"type":"array","items":{"type":"string"}}},"required":["streaming","push_notifications","extensions"]},"default_input_modes":{"type":"array","items":{"type":"string"}},"default_output_modes":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["id","name"]}},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1},{"type":"object","properties":{"title":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1}},"required":["title","prompt"],"additionalProperties":false}]}},"kind":{"type":"string","enum":["source_project_agent","installed_project_agent"]},"can_run":{"type":"boolean"},"source_type":{"type":"string","enum":["project","catalog_install"]},"installed_access":{"type":"object","properties":{"grant_id":{"type":"string","format":"uuid"},"relation":{"type":"string","enum":["owner","admin","editor","viewer"]},"service_account_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["grant_id","relation","service_account_id","project_id","status"]},"runtime_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","offline","not_applicable","unknown"]},"reason":{"type":["string","null"]},"runtime_target_kind":{"type":["string","null"],"enum":["registered_push_service","pull_worker",null]},"runtime_service_key":{"type":["string","null"]}},"required":["status","reason","runtime_target_kind","runtime_service_key"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"avatar_url":{"type":["string","null"],"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":["string","null"]},"x-veryfront-url":{"type":"string"}},"required":["id","name","description","provider","version","capabilities","default_input_modes","default_output_modes","tools","skills","kind","can_run","source_type","source_path","edit_mode","x-veryfront-model","x-veryfront-url"]}}},"required":["source_target","runtime_target","skills","tools","integrations","tool_access","prompts","workflows","tasks","agents"]}},"required":["resolved_capabilities"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/agents/{agent_id}/capabilities":{"get":{"operationId":"getAgentCapabilities","tags":["Agent Capabilities"],"summary":"Get agent capabilities","description":"Return agent capabilities for the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Agent identifier"},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Resolved agent capabilities","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"provider":{"type":"object","properties":{"organization":{"type":"string"},"url":{"type":"string"}},"required":["organization","url"]},"version":{"type":"string"},"capabilities":{"type":"object","properties":{"streaming":{"type":"boolean"},"push_notifications":{"type":"boolean"},"extensions":{"type":"array","items":{"type":"string"}}},"required":["streaming","push_notifications","extensions"]},"default_input_modes":{"type":"array","items":{"type":"string"}},"default_output_modes":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["id","name"]}},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1},{"type":"object","properties":{"title":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1}},"required":["title","prompt"],"additionalProperties":false}]}},"kind":{"type":"string","enum":["source_project_agent","installed_project_agent"]},"can_run":{"type":"boolean"},"source_type":{"type":"string","enum":["project","catalog_install"]},"installed_access":{"type":"object","properties":{"grant_id":{"type":"string","format":"uuid"},"relation":{"type":"string","enum":["owner","admin","editor","viewer"]},"service_account_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["grant_id","relation","service_account_id","project_id","status"]},"runtime_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","offline","not_applicable","unknown"]},"reason":{"type":["string","null"]},"runtime_target_kind":{"type":["string","null"],"enum":["registered_push_service","pull_worker",null]},"runtime_service_key":{"type":["string","null"]}},"required":["status","reason","runtime_target_kind","runtime_service_key"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"avatar_url":{"type":["string","null"],"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":["string","null"]},"x-veryfront-url":{"type":"string"}},"required":["id","name","description","provider","version","capabilities","default_input_modes","default_output_modes","tools","skills","kind","can_run","source_type","source_path","edit_mode","x-veryfront-model","x-veryfront-url"]},"resolved_capabilities":{"type":"object","properties":{"source_target":{"type":"object","properties":{"kind":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"skills":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["project"]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"allowed_tools":{"type":"array","items":{"type":"string"}}},"required":["type","id","name","description","source_path","edit_mode"],"title":"ProjectSkill"},{"type":"object","properties":{"type":{"type":"string","enum":["agent"]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["type","id","name"],"title":"AgentSkill"}]}},"tools":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["control_plane"]},"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","additionalProperties":{}}},"required":["type","name"],"title":"ControlPlaneTool"},{"type":"object","properties":{"type":{"type":"string","enum":["integration"]},"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","additionalProperties":{}}},"required":["type","name","description","input_schema"],"title":"IntegrationTool"},{"type":"object","properties":{"type":{"type":"string","enum":["project"]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":["object","null"],"additionalProperties":{}}},"required":["type","id","name","source_path","edit_mode"],"title":"ProjectTool"}]}},"integrations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tool_names":{"type":"array","items":{"type":"string"}}},"required":["id","name","tool_names"]}},"tool_resolution":{"type":"array","items":{"type":"object","properties":{"tool_name":{"type":"string"},"source_selected":{"type":"boolean"},"catalog_available":{"type":"boolean"},"catalog_state":{"type":"string","enum":["available","removed"]},"effective_authorization":{"type":"string","enum":["authorized","restricted_by_policy","catalog_unavailable"]},"policy":{"type":"object","properties":{"state":{"type":"string","enum":["absent","allowed","restricted"]},"scope":{"type":"string","enum":["project","user"]},"allowed_tools":{"type":["array","null"],"items":{"type":"string"}},"execution_mode":{"type":"string","enum":["real","mock"]}},"required":["state","scope","allowed_tools","execution_mode"]},"credential_requirement":{"type":"object","properties":{"mode":{"type":"string","enum":["oauth_connection","project_credentials","none"]},"managed_oauth":{"type":"boolean"},"byo_oauth_app_override":{"type":"object","properties":{"supported":{"type":"boolean"},"required":{"type":"boolean"},"client_id_env_var":{"type":["string","null"]},"client_secret_env_var":{"type":["string","null"]}},"required":["supported","required","client_id_env_var","client_secret_env_var"]},"mandatory_env_vars":{"type":"array","items":{"type":"string"}}},"required":["mode","managed_oauth","byo_oauth_app_override","mandatory_env_vars"]},"connection_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","required","not_applicable","unknown"]},"scope":{"type":["string","null"],"enum":["project","user",null]},"connected_count":{"type":["integer","null"],"minimum":0}},"required":["status","scope","connected_count"]}},"required":["tool_name","source_selected","catalog_available","catalog_state","effective_authorization","policy","credential_requirement","connection_readiness"]}},"tool_access":{"type":"object","properties":{"version":{"type":"number","enum":[1],"description":"The version associated with this tool result."},"freshness":{"type":"object","properties":{"resolved_at":{"type":"string","format":"date-time","description":"The resolved at associated with this tool result."},"valid_for_ms":{"type":"integer","exclusiveMinimum":0,"description":"The valid for ms associated with this tool result."},"fail_closed_on_expiry":{"type":"boolean","enum":[true],"description":"The fail closed on expiry associated with this tool result."}},"required":["resolved_at","valid_for_ms","fail_closed_on_expiry"],"description":"Structured freshness details associated with this tool result."},"inputs":{"type":"object","properties":{"capabilities":{"type":"array","items":{"type":"string","enum":["project.read","project.settings.manage","project.delete","project.members.read","project.members.manage","project.invites.read","project.invites.manage","project.files.read","project.files.write","project.realtime.connect","project.realtime.write","project.files.admin","project.uploads.read","project.uploads.write","project.uploads.admin","project.knowledge.read","project.knowledge.write","project.releases.read","project.releases.write","project.deployments.read","project.deployments.write","project.deploy.execute","project.runtime.manage","project.sandboxes.manage","project.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.runs.admin","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","project.conversations.create","project.integrations.read","project.integrations.connect","project.integrations.configure","project.api_keys.read","project.api_keys.manage","project.cache.read","project.cache.write","project.logs.read","project.metrics.read","project.resources.read"],"description":"One capability item associated with this tool result."},"description":"List of capabilities associated with this tool result."},"billing":{"type":"object","properties":{"collaboration_allowed":{"type":"boolean","description":"The collaboration allowed associated with this tool result."},"can_invite":{"type":"boolean","description":"The can invite associated with this tool result."}},"required":["collaboration_allowed","can_invite"],"description":"Structured billing details associated with this tool result."},"entitlements":{"type":"object","properties":{"dedicated_runtime":{"type":"boolean","description":"The dedicated runtime associated with this tool result."},"custom_domains":{"type":"boolean","description":"The custom domains associated with this tool result."},"export_apps":{"type":"boolean","description":"The export apps associated with this tool result."}},"required":["dedicated_runtime","custom_domains","export_apps"],"description":"Structured entitlements details associated with this tool result."}},"required":["capabilities","billing","entitlements"],"description":"Structured inputs details associated with this tool result."},"families":{"type":"array","items":{"type":"object","properties":{"family":{"type":"string","enum":["collaboration","runtime","domains","export"],"description":"The family associated with this tool result."},"default_decision":{"type":"object","properties":{"visibility":{"type":"string","enum":["visible","hidden"],"description":"The visibility associated with this tool result."},"reason_code":{"type":"string","enum":["allowed","missing_capability","billing_plan_restriction","billing_seat_limit","target_not_supported","resource_state_restriction","policy_exception","unknown"],"description":"The reason code associated with this tool result."},"message":{"type":"string","description":"The message associated with this tool result."}},"required":["visibility","reason_code"],"description":"Structured default decision details associated with this tool result."},"action_overrides":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["create_invite","delete_member","create_server","delete_server","create_domain","download_release"],"description":"The action associated with this tool result."},"decision":{"type":"object","properties":{"visibility":{"type":"string","enum":["visible","hidden"],"description":"The visibility associated with this tool result."},"reason_code":{"type":"string","enum":["allowed","missing_capability","billing_plan_restriction","billing_seat_limit","target_not_supported","resource_state_restriction","policy_exception","unknown"],"description":"The reason code associated with this tool result."},"message":{"type":"string","description":"The message associated with this tool result."}},"required":["visibility","reason_code"],"description":"Structured default decision details associated with this tool result."}},"required":["action","decision"],"description":"One action override item associated with this tool result."},"description":"List of action overrides associated with this tool result."}},"required":["family","default_decision","action_overrides"],"description":"One family item associated with this tool result."},"description":"List of families associated with this tool result."}},"required":["version","freshness","inputs","families"]},"prompts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]}},"required":["id","name","source_path","edit_mode"]}},"workflows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"version":{"type":["string","null"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}},"schedulable":{"type":"boolean"}},"required":["id","name","target","source_path","edit_mode","schedulable"]}},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}},"schedulable":{"type":"boolean"}},"required":["id","name","target","source_path","edit_mode","schedulable"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["source_target","runtime_target","skills","tools","integrations","tool_access","prompts","workflows","tasks"]}},"required":["agent","resolved_capabilities"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/agent-tool-references":{"get":{"operationId":"listAgentToolReferences","tags":["Agent Tool References"],"summary":"Search attachable agent tools","description":"Search valid tool references for agent definitions in the selected source. Returns compact names and descriptions for tool_ids.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"query","in":"query"},{"schema":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":20},"required":false,"name":"names","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Matching attachable tools","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Returned tool identity. Submit this canonical name for a new platform selection."},"legacy_name":{"type":"string","description":"Rollback-compatible identity stored by the API after it validates a canonical platform selection."},"description":{"type":"string","description":"Compact purpose of the referenced tool."},"source":{"type":"string","enum":["platform","project","integration"],"description":"Control-plane source that makes this tool reference valid for the selected project target."},"attach_via":{"type":"string","enum":["tool_ids"],"description":"Agent field used to attach this reference."}},"required":["name","description","source","attach_via"],"description":"Schema-free tool reference that can be attached to a project agent."},"description":"Deterministically ranked and deduplicated matching tool references."},"returned":{"type":"integer","minimum":0,"description":"Number of references returned after applying the limit."},"total_matches":{"type":"integer","minimum":0,"description":"Total matching references before applying the limit."}},"required":["data","returned","total_matches"],"description":"Compact schema-free agent tool reference search result."}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/agents/{agent_id}/labels":{"get":{"operationId":"listProjectAgentLabels","tags":["Agent Labels"],"summary":"List project agent labels","description":"List labels assigned to the agent in the selected project source.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"description":"Project UUID or slug.","name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch","preview_branch"],"default":"project"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Agent labels.","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"$ref":"#/components/schemas/Label"}}},"required":["labels"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createProjectAgentLabel","tags":["Agent Labels"],"summary":"Create project agent label","description":"Add a label to the agent with a key and optional value and color.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"description":"Project UUID or slug.","name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch","preview_branch"],"default":"project"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64,"description":"Required label key. Trimmed and lowercased; starts with a letter or number and allows letters, numbers, dot, underscore and dash."},"value":{"type":["string","null"],"maxLength":128,"description":"Label value. Trimmed; a supplied blank value is invalid. Omit or use null for a key-only label, including on replacement."},"color":{"type":["string","null"],"maxLength":32,"description":"Display color. Omit, use null or supply a blank string to clear it, including on replacement."}},"required":["key"]}}}},"responses":{"200":{"description":"Created label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Label"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/agents/{agent_id}/labels/{label_id}":{"put":{"operationId":"updateProjectAgentLabel","tags":["Agent Labels"],"summary":"Update project agent label","description":"Replaces an agent label in the selected source. Key is required; omitted value and color are cleared. Requires project.agents.write.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"description":"Project UUID or slug.","name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Label UUID within the selected resource."},"required":true,"description":"Label UUID within the selected resource.","name":"label_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch","preview_branch"],"default":"project"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64,"description":"Required label key. Trimmed and lowercased; starts with a letter or number and allows letters, numbers, dot, underscore and dash."},"value":{"type":["string","null"],"maxLength":128,"description":"Label value. Trimmed; a supplied blank value is invalid. Omit or use null for a key-only label, including on replacement."},"color":{"type":["string","null"],"maxLength":32,"description":"Display color. Omit, use null or supply a blank string to clear it, including on replacement."}},"required":["key"]}}}},"responses":{"200":{"description":"Updated label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Label"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteProjectAgentLabel","tags":["Agent Labels"],"summary":"Delete project agent label","description":"Soft-deletes an agent label in the selected source. Requires project.agents.write; API keys also require delete scope. Returns 204 without a body.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"description":"Project UUID or slug.","name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Label UUID within the selected resource."},"required":true,"description":"Label UUID within the selected resource.","name":"label_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch","preview_branch"],"default":"project"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"204":{"description":"Label removed."},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/agents/{agent_id}/avatar.svg":{"get":{"operationId":"getAgentAvatarSvg","tags":["Agent Avatars"],"summary":"Get agent avatar SVG","description":"Returns an SVG rendered from the agent’s saved avatar configuration. Agents in configured template projects allow anonymous access. Other agents require project read access.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Read the avatar from this source target. Defaults to \"project\". Ignored for template projects."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"},{"schema":{"type":"string","description":"Branch ID when source_target_kind=preview_branch."},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"SVG avatar markup","content":{"image/svg+xml":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Authentication required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Agent not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/agents/{agent_id}/avatar":{"post":{"operationId":"generateAgentAvatar","tags":["Agent Avatars"],"summary":"Generate agent avatar","description":"Generates an SVG avatar for an existing or prospective agent ID, stores it as a project upload, and returns the API upload URL. Defaults to upload-only. Set `assign` to true to persist the URL on an existing agent.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Unique identifier for the record."},"required":true,"description":"Unique identifier for the record.","name":"agent_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"assign":{"type":"boolean","default":false,"description":"The assign associated with this record."},"config":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":128,"description":"The seed associated with this record."},"archetype":{"type":"string","enum":["upright","slumped","alert","profile","leaning","crouched","tall","spread","happy","sad","angry","surprised","sleepy","curious"],"description":"The archetype associated with this record."},"texture":{"type":"string","pattern":"^(?:[0-9]|none)$","description":"The texture associated with this record."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"The color associated with this record."},"shape":{"type":"string","enum":["snircle","circle","square"],"description":"The shape associated with this record."},"matrix":{"type":"string","pattern":"^[012]{16}$","description":"The matrix associated with this record."}},"description":"Avatar configuration. Omit `seed` to generate a new avatar. With an explicit seed, omitted visual options use the existing avatar configuration if available. New agents use generator defaults."}}}}}},"responses":{"200":{"description":"Agent avatar generated","content":{"application/json":{"schema":{"type":"object","properties":{"avatar_url":{"type":"string","format":"uri"}},"required":["avatar_url"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/agents/avatar":{"post":{"operationId":"previewAgentAvatar","tags":["Agent Avatars"],"summary":"Preview agent avatar","description":"Renders an SVG avatar before an agent exists. Returns the resolved config so the preview can be replayed and persisted during agent creation.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":128,"description":"The seed associated with this record."},"archetype":{"type":"string","enum":["upright","slumped","alert","profile","leaning","crouched","tall","spread","happy","sad","angry","surprised","sleepy","curious"],"description":"The archetype associated with this record."},"texture":{"type":"string","pattern":"^(?:[0-9]|none)$","description":"The texture associated with this record."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"The color associated with this record."},"shape":{"type":"string","enum":["snircle","circle","square"],"description":"The shape associated with this record."},"matrix":{"type":"string","pattern":"^[012]{16}$","description":"The matrix associated with this record."}},"description":"Avatar configuration. Omit `seed` to generate a new avatar."}}}}}},"responses":{"200":{"description":"Agent avatar preview generated","content":{"application/json":{"schema":{"type":"object","properties":{"svg":{"type":"string","description":"Rendered SVG markup for immediate preview without a separate authenticated fetch."},"config":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":128,"description":"The seed associated with this record."},"archetype":{"type":"string","enum":["upright","slumped","alert","profile","leaning","crouched","tall","spread","happy","sad","angry","surprised","sleepy","curious"],"description":"The archetype associated with this record."},"texture":{"type":"string","pattern":"^(?:[0-9]|none)$","description":"The texture associated with this record."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"The color associated with this record."},"shape":{"type":"string","enum":["snircle","circle","square"],"description":"The shape associated with this record."},"matrix":{"type":"string","pattern":"^[012]{16}$","description":"The matrix associated with this record."}},"description":"Structured avatar details associated with this record."}},"required":["svg","config"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/agents/{agent_id}/install":{"post":{"operationId":"installAgent","tags":["Agent Installation"],"summary":"Install agent","description":"Installs a catalog agent into the project by creating or reusing an agent access grant.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Catalog agent identifier"},"required":true,"name":"agent_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"relation":{"type":"string","enum":["owner","admin","editor","viewer"],"default":"editor"}}}}}},"responses":{"200":{"description":"Existing installed agent card","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"provider":{"type":"object","properties":{"organization":{"type":"string"},"url":{"type":"string"}},"required":["organization","url"]},"version":{"type":"string"},"capabilities":{"type":"object","properties":{"streaming":{"type":"boolean"},"push_notifications":{"type":"boolean"},"extensions":{"type":"array","items":{"type":"string"}}},"required":["streaming","push_notifications","extensions"]},"default_input_modes":{"type":"array","items":{"type":"string"}},"default_output_modes":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["id","name"]}},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1},{"type":"object","properties":{"title":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1}},"required":["title","prompt"],"additionalProperties":false}]}},"kind":{"type":"string","enum":["source_project_agent","installed_project_agent"]},"can_run":{"type":"boolean"},"source_type":{"type":"string","enum":["project","catalog_install"]},"installed_access":{"type":"object","properties":{"grant_id":{"type":"string","format":"uuid"},"relation":{"type":"string","enum":["owner","admin","editor","viewer"]},"service_account_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["grant_id","relation","service_account_id","project_id","status"]},"runtime_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","offline","not_applicable","unknown"]},"reason":{"type":["string","null"]},"runtime_target_kind":{"type":["string","null"],"enum":["registered_push_service","pull_worker",null]},"runtime_service_key":{"type":["string","null"]}},"required":["status","reason","runtime_target_kind","runtime_service_key"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"avatar_url":{"type":["string","null"],"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":["string","null"]},"x-veryfront-url":{"type":"string"}},"required":["id","name","description","provider","version","capabilities","default_input_modes","default_output_modes","tools","skills","kind","can_run","source_type","source_path","edit_mode","x-veryfront-model","x-veryfront-url"]}}}},"201":{"description":"Installed agent card","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"provider":{"type":"object","properties":{"organization":{"type":"string"},"url":{"type":"string"}},"required":["organization","url"]},"version":{"type":"string"},"capabilities":{"type":"object","properties":{"streaming":{"type":"boolean"},"push_notifications":{"type":"boolean"},"extensions":{"type":"array","items":{"type":"string"}}},"required":["streaming","push_notifications","extensions"]},"default_input_modes":{"type":"array","items":{"type":"string"}},"default_output_modes":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["id","name"]}},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1},{"type":"object","properties":{"title":{"type":"string","minLength":1},"prompt":{"type":"string","minLength":1}},"required":["title","prompt"],"additionalProperties":false}]}},"kind":{"type":"string","enum":["source_project_agent","installed_project_agent"]},"can_run":{"type":"boolean"},"source_type":{"type":"string","enum":["project","catalog_install"]},"installed_access":{"type":"object","properties":{"grant_id":{"type":"string","format":"uuid"},"relation":{"type":"string","enum":["owner","admin","editor","viewer"]},"service_account_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["grant_id","relation","service_account_id","project_id","status"]},"runtime_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","offline","not_applicable","unknown"]},"reason":{"type":["string","null"]},"runtime_target_kind":{"type":["string","null"],"enum":["registered_push_service","pull_worker",null]},"runtime_service_key":{"type":["string","null"]}},"required":["status","reason","runtime_target_kind","runtime_service_key"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"avatar_url":{"type":["string","null"],"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":["string","null"]},"x-veryfront-url":{"type":"string"}},"required":["id","name","description","provider","version","capabilities","default_input_modes","default_output_modes","tools","skills","kind","can_run","source_type","source_path","edit_mode","x-veryfront-model","x-veryfront-url"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"delete":{"operationId":"uninstallAgent","tags":["Agent Installation"],"summary":"Uninstall agent","description":"Revoke an installed catalog agent access grant from the project agent surface.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Catalog agent identifier"},"required":true,"name":"agent_id","in":"path"}],"responses":{"204":{"description":"Installed agent grant revoked"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/agents/{agent_id}/install-selected":{"post":{"operationId":"installAgentForSelectedProjects","tags":["Agent Installation"],"summary":"Install agent for selected projects","description":"Installs a catalog agent into selected projects by expanding the selection into explicit project-scoped agent access grants.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Catalog agent identifier"},"required":true,"name":"agent_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_project_references":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100},"selected_project_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100},"relation":{"type":"string","enum":["owner","admin","editor","viewer"],"default":"editor"}}}}}},"responses":{"200":{"description":"Existing installed agent cards","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCardList"}}}},"201":{"description":"Installed agent cards","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCardList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/prompts":{"get":{"operationId":"listPrompts","tags":["Project prompts"],"summary":"List prompts","description":"List prompts from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project prompts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]}},"required":["id","name","description","source_path","edit_mode"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"post":{"operationId":"createPrompt","tags":["Project prompts"],"summary":"Create prompt","description":"Create a structured prompt source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique identifier for the record."},"description":{"type":["string","null"]},"content":{"type":"string","minLength":1},"source":{"type":"string","minLength":1}},"required":["id","content"]}}}},"responses":{"201":{"description":"Created prompt document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"content":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","content","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/prompts/{prompt_id}":{"get":{"operationId":"getPrompt","tags":["Project prompts"],"summary":"Get prompt","description":"Return a prompt from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Prompt identifier"},"required":true,"name":"prompt_id","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project prompt","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]}},"required":["id","name","description","source_path","edit_mode"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"put":{"operationId":"updatePrompt","tags":["Project prompts"],"summary":"Update prompt","description":"Update a structured prompt source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Prompt identifier"},"required":true,"name":"prompt_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":["string","null"]},"content":{"type":"string","minLength":1},"source":{"type":"string","minLength":1}},"required":["content"]}}}},"responses":{"200":{"description":"Updated prompt document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"content":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","content","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"delete":{"operationId":"deletePrompt","tags":["Project prompts"],"summary":"Delete prompt","description":"Delete a structured prompt source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Prompt identifier"},"required":true,"name":"prompt_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Prompt deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/prompts/{prompt_id}/source":{"get":{"operationId":"getPromptSource","tags":["Project prompts"],"summary":"Get prompt source","description":"Return the structured prompt document from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Prompt identifier"},"required":true,"name":"prompt_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Prompt document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"content":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","content","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/skills":{"get":{"operationId":"listSkills","tags":["Project skills"],"summary":"List skills","description":"List skills from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project skills","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"allowed_tools":{"type":"array","items":{"type":"string"}},"owner_agent_id":{"type":"string"},"short_name":{"type":"string"}},"required":["id","name","description","source_path","edit_mode"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"post":{"operationId":"createSkill","tags":["Project skills"],"summary":"Create skill","description":"Create a structured skill document in the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Canonical skill name, also used as the skill directory name. Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen, and must not contain consecutive hyphens."},"id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Deprecated alias for name; when sent it must equal name."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Max 1024 characters. Non-empty. Describes what the skill does and when to use it."},"allowed_tools":{"type":"array","items":{"type":"string","minLength":1}},"instructions":{"type":"string","description":"The Markdown body of `SKILL.md`, excluding frontmatter."},"source":{"type":"string","minLength":1}},"required":["name","description"]}}}},"responses":{"201":{"description":"Created project skill document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillDocument"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/skills/{skill_id}":{"get":{"operationId":"getSkill","tags":["Project skills"],"summary":"Get skill","description":"Return a skill from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Skill identifier"},"required":true,"name":"skill_id","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project skill","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"allowed_tools":{"type":"array","items":{"type":"string"}},"owner_agent_id":{"type":"string"},"short_name":{"type":"string"}},"required":["id","name","description","source_path","edit_mode"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"put":{"operationId":"updateSkill","tags":["Project skills"],"summary":"Update skill","description":"Update a structured skill document in the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Skill identifier"},"required":true,"name":"skill_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Canonical skill name, also used as the skill directory name. Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen, and must not contain consecutive hyphens."},"description":{"type":"string","minLength":1,"maxLength":1024,"description":"Max 1024 characters. Non-empty. Describes what the skill does and when to use it."},"allowed_tools":{"type":"array","items":{"type":"string","minLength":1}},"instructions":{"type":"string","description":"The Markdown body of `SKILL.md`, excluding frontmatter."},"source":{"type":"string","minLength":1}},"required":["description"]}}}},"responses":{"200":{"description":"Updated project skill document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillDocument"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"delete":{"operationId":"deleteSkill","tags":["Project skills"],"summary":"Delete skill","description":"Delete a project skill source file from the selected source target, including source-only recovery files.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Skill identifier"},"required":true,"name":"skill_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/skills/{skill_id}/source":{"get":{"operationId":"getSkillSource","tags":["Project skills"],"summary":"Get skill source","description":"Return the structured skill document from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Skill identifier"},"required":true,"name":"skill_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Project skill document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillDocument"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/tools":{"get":{"operationId":"listTools","tags":["Project tools"],"summary":"List tools","description":"List tools from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project tools","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}}},"required":["id","name","description","source_path","edit_mode","input_schema","output_schema"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"post":{"operationId":"createTool","tags":["Project tools"],"summary":"Create tool","description":"Create a structured tool source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique identifier for the record."},"description":{"type":["string","null"]},"source":{"type":"string","minLength":1}},"required":["id"]}}}},"responses":{"201":{"description":"Created tool document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/tools/{tool_id}":{"get":{"operationId":"getTool","tags":["Project tools"],"summary":"Get tool","description":"Return a tool from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Tool identifier"},"required":true,"name":"tool_id","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project tool","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}}},"required":["id","name","description","source_path","edit_mode","input_schema","output_schema"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"put":{"operationId":"updateTool","tags":["Project tools"],"summary":"Update tool","description":"Update a structured tool source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Tool identifier"},"required":true,"name":"tool_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":["string","null"]},"source":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"Updated tool document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"delete":{"operationId":"deleteTool","tags":["Project tools"],"summary":"Delete tool","description":"Delete a structured tool source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Tool identifier"},"required":true,"name":"tool_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Tool deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/tools/{tool_id}/source":{"get":{"operationId":"getToolSource","tags":["Project tools"],"summary":"Get tool source","description":"Return the structured tool document from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Tool identifier"},"required":true,"name":"tool_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Tool document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/tasks":{"get":{"operationId":"listTasks","tags":["Project tasks"],"summary":"List tasks","description":"List tasks from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project tasks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}},"schedulable":{"type":"boolean"}},"required":["id","name","description","target","source_path","edit_mode","input_schema","output_schema","schedulable"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"post":{"operationId":"createTask","tags":["Project tasks"],"summary":"Create task","description":"Create a structured task source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique identifier for the record."},"name":{"type":"string","minLength":1},"description":{"type":["string","null"]},"schedulable":{"type":"boolean"}},"required":["id","name"]}}}},"responses":{"201":{"description":"Created task document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"schedulable":{"type":"boolean"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","target","source_path","source","schedulable","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/tasks/{task_id}":{"get":{"operationId":"getTask","tags":["Project tasks"],"summary":"Get task","description":"Return a task from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Task identifier"},"required":true,"name":"task_id","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project task","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}},"schedulable":{"type":"boolean"}},"required":["id","name","description","target","source_path","edit_mode","input_schema","output_schema","schedulable"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"put":{"operationId":"updateTask","tags":["Project tasks"],"summary":"Update task","description":"Update a structured task source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Task identifier"},"required":true,"name":"task_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":["string","null"]},"schedulable":{"type":"boolean"}},"required":["name"]}}}},"responses":{"200":{"description":"Updated task document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"schedulable":{"type":"boolean"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","target","source_path","source","schedulable","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"delete":{"operationId":"deleteTask","tags":["Project tasks"],"summary":"Delete task","description":"Delete a structured task source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Task identifier"},"required":true,"name":"task_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Task deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/tasks/{task_id}/source":{"get":{"operationId":"getTaskSource","tags":["Project tasks"],"summary":"Get task source","description":"Return the task source document and its editing status from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Task identifier"},"required":true,"name":"task_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Used as the source target kind when source_target_kind is omitted."},"required":false,"description":"Used as the source target kind when source_target_kind is omitted.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Not supported for source reads; a non-null value is rejected."},"required":false,"description":"Not supported for source reads; a non-null value is rejected.","name":"target_environment_id","in":"query"}],"responses":{"200":{"description":"Task document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"schedulable":{"type":"boolean"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","target","source_path","source","schedulable","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/workflows":{"get":{"operationId":"listWorkflows","tags":["Project workflows"],"summary":"List workflows","description":"List workflows from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project workflows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"version":{"type":["string","null"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}},"schedulable":{"type":"boolean"}},"required":["id","name","description","target","source_path","edit_mode","version","input_schema","output_schema","schedulable"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"post":{"operationId":"createWorkflow","tags":["Project workflows"],"summary":"Create workflow","description":"Create a structured workflow source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique identifier for the record."},"description":{"type":["string","null"]},"version":{"type":["string","null"]},"schedulable":{"type":"boolean"}},"required":["id"]}}}},"responses":{"201":{"description":"Created workflow document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"version":{"type":["string","null"]},"schedulable":{"type":"boolean"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","target","source_path","source","version","schedulable","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/workflows/{workflow_id}":{"get":{"operationId":"getWorkflow","tags":["Project workflows"],"summary":"Get workflow","description":"Return a workflow from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Workflow identifier"},"required":true,"name":"workflow_id","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project workflow","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"version":{"type":["string","null"]},"input_schema":{"type":["object","null"],"additionalProperties":{}},"output_schema":{"type":["object","null"],"additionalProperties":{}},"schedulable":{"type":"boolean"}},"required":["id","name","description","target","source_path","edit_mode","version","input_schema","output_schema","schedulable"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"put":{"operationId":"updateWorkflow","tags":["Project workflows"],"summary":"Update workflow","description":"Update a structured workflow source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Workflow identifier"},"required":true,"name":"workflow_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":["string","null"]},"version":{"type":["string","null"]},"schedulable":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated workflow document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"version":{"type":["string","null"]},"schedulable":{"type":"boolean"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","target","source_path","source","version","schedulable","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"delete":{"operationId":"deleteWorkflow","tags":["Project workflows"],"summary":"Delete workflow","description":"Delete a structured workflow source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Workflow identifier"},"required":true,"name":"workflow_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Workflow deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/workflows/{workflow_id}/source":{"get":{"operationId":"getWorkflowSource","tags":["Project workflows"],"summary":"Get workflow source","description":"Return the workflow source document and its editing status from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Workflow identifier"},"required":true,"name":"workflow_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Used as the source target kind when source_target_kind is omitted."},"required":false,"description":"Used as the source target kind when source_target_kind is omitted.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Not supported for source reads; a non-null value is rejected."},"required":false,"description":"Not supported for source reads; a non-null value is rejected.","name":"target_environment_id","in":"query"}],"responses":{"200":{"description":"Workflow document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"version":{"type":["string","null"]},"schedulable":{"type":"boolean"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","target","source_path","source","version","schedulable","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/resources":{"get":{"operationId":"listProjectResources","tags":["Project resources"],"summary":"List project resources","description":"List project-defined resource documents from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Discovered project resources","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"pattern":{"type":"string"},"description":{"type":"string"},"title":{"type":["string","null"]},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]}},"required":["id","pattern","description","source_path","edit_mode"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"post":{"operationId":"createProjectResource","tags":["Project resources"],"summary":"Create project resource","description":"Create a structured project resource source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"pattern":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"title":{"type":["string","null"]}},"required":["id","pattern","description"]}}}},"responses":{"201":{"description":"Created resource document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"pattern":{"type":"string"},"description":{"type":"string"},"title":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","pattern","description","title","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/resources/{resource_id}":{"get":{"operationId":"getProjectResource","tags":["Project resources"],"summary":"Get project resource","description":"Return the structured project resource document from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Resource identifier"},"required":true,"name":"resource_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Resource document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"pattern":{"type":"string"},"description":{"type":"string"},"title":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","pattern","description","title","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"put":{"operationId":"updateProjectResource","tags":["Project resources"],"summary":"Update project resource","description":"Update a structured project resource source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Resource identifier"},"required":true,"name":"resource_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pattern":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"title":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Updated resource document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"pattern":{"type":"string"},"description":{"type":"string"},"title":{"type":["string","null"]},"source_path":{"type":"string"},"source":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"source_only_reasons":{"type":"array","items":{"type":"string"}}},"required":["id","pattern","description","title","source_path","source","edit_mode","source_only_reasons"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"delete":{"operationId":"deleteProjectResource","tags":["Project resources"],"summary":"Delete project resource","description":"Delete a structured project resource source file.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Resource identifier"},"required":true,"name":"resource_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Resource deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/conversations/{conversation_id}/runs/{run_id}/stream":{"get":{"operationId":"streamConversationAgentRun","tags":["Runtime compatibility"],"summary":"Stream conversation run events (compatibility)","description":"Streams events for a legacy conversation-bound agent run.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"conversation_id","in":"path"}],"responses":{"200":{"description":"Run event frames","content":{"text/event-stream":{"schema":{"type":"string","description":"Legacy PascalCase SSE event names with typed run event rows, including span and origin metadata.","x-event-schema":{"$ref":"#/components/schemas/ConversationRunStreamFrame"}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/runs":{"get":{"operationId":"listRuns","tags":["Run resource"],"summary":"List runs","description":"List runs.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]*$","description":"Discover agent runs with this persisted task identity across conversations. Matches canonical task metadata or the first enqueue request; results are not task authorization evidence."},"required":false,"description":"Filter by the persisted orchestration task identity in task_id; this is distinct from the execution definition target.","name":"task_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Opaque cursor returned by the previous page. Reuse with unchanged filters and ordering."},"required":false,"description":"Opaque page_info.next cursor; reuse with unchanged filters and ordering.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at","status","duration"],"default":"created_at","description":"Field used to order runs: created_at, status or duration. Defaults to created_at."},"required":false,"description":"Field used to order runs: created_at, status or duration. Defaults to created_at.","name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction: asc or desc. Defaults to desc."},"required":false,"description":"Sort direction: asc or desc. Defaults to desc.","name":"sort_order","in":"query"},{"schema":{"type":"array","items":{"type":"string"},"maxItems":32,"description":"Run statuses to include. Values within this filter use OR; different filters use AND."},"required":false,"description":"Filter by status. Repeat the query parameter for multiple values; comma-separated values remain a compatibility alias. Values within this filter use OR; different filters use AND.","style":"form","explode":true,"name":"status","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["agent","task","workflow","eval"]},"minItems":1,"maxItems":4,"description":"Execution definition types to include: agent, task, workflow or legacy eval."},"required":false,"description":"Filter by execution definition type.","style":"form","explode":true,"name":"target_type","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["user","api_key","service_account","system","schedule","webhook","agent","task","workflow"]},"minItems":1,"maxItems":9,"description":"Trigger types to include: user, api_key, service_account, system, schedule, webhook, agent, task or workflow."},"required":false,"description":"Filter by trigger_type.","style":"form","explode":true,"name":"trigger_type","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"true lists only top-level runs (parent_run_id null). Defaults to false."},"required":false,"name":"root_only","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"parent_run_id","in":"query"},{"schema":{"type":"array","items":{"type":"string"},"maxItems":32},"required":false,"description":"Filter by execution definition ID.","style":"form","explode":true,"name":"target_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"description":"Filter by trigger_id.","name":"trigger_id","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Restrict accessible runs to this project; filters intersect and never grant access.","name":"project_id","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Restrict accessible runs to this conversation; filters intersect and never grant access.","name":"conversation_id","in":"query"}],"responses":{"200":{"description":"Run page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsPage"},"examples":{"example":{"summary":"Example response","value":{"data":[{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}},"post":{"operationId":"createRun","tags":["Run resource"],"summary":"Create run","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"description":"Create run.\n\n- 202 means the run was accepted; it can remain pending until an executor is available.\n- Use an authorized user token or a write-scoped project or account/all-projects API key for a root run; child creation requires the parent’s execution credential and applicable child-admission authorization.\n- trigger identifies the authenticated user or credential for a direct run, or the parent execution definition for a child; parent_run_id identifies that exact execution.\n- source selects a saved definition in the create request only; the response returns the resolved target and server-derived trigger when readable by the caller; otherwise it returns only run_id and status. Manual invocation records the authenticated user or credential as trigger.\n- Retry with the same Idempotency-Key and payload to receive the original response; a changed payload with the same key returns 409.\n- Create an agent child with parent_run_id and a verified tool_call_id; task children use the existing durable invocation identity and Idempotency-Key. Existing workflow-node child admissions use node_id and can replay, but new workflow-node child admission currently returns 409. node_id and tool_call_id are mutually exclusive and require parent_run_id. Verify correlation against the authenticated parent execution, derive trigger from the parent target, and reject wrong parent-type correlation and cycles.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the idempotency key."},"required":true,"description":"Provide the idempotency key.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunRequest"},"examples":{"minimal":{"summary":"Minimal request","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"health-check"}}},"agent":{"summary":"API-started agent","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"coordinator"},"input":{"message":"Research the topic and summarize it."}}},"task":{"summary":"Task run","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."}}},"workflow":{"summary":"Workflow run","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"workflow","id":"review"},"input":{"document_id":"document_example"}}},"child":{"summary":"Child run","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"research"},"input":{"question":"Find relevant sources."},"parent_run_id":"22222222-2222-4222-8222-222222222222","tool_call_id":"call_invoke_agent"}},"workflow_child":{"summary":"Workflow starts an agent","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"coordinator"},"input":{"topic":"Energy storage"},"parent_run_id":"11111111-1111-4111-8111-111111111111","node_id":"research"}},"evaluation":{"summary":"Evaluation run","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"eval"},"config":{"eval_id":"eval_example"}}},"relationships":{"summary":"Conversation and batch","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"support"},"input":{"message":"Summarize this document."},"conversation_id":"00000000-0000-4000-8000-000000000002","batch_id":"00000000-0000-4000-8000-000000000003"}},"runtime":{"summary":"Registered runtime","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"execution":{"runtime":{"type":"registered","id":"runtime_example"}}}},"schedule":{"summary":"Saved schedule","value":{"project_id":"00000000-0000-4000-8000-000000000001","source":{"type":"schedule","id":"00000000-0000-4000-8000-000000000002"}}},"webhook":{"summary":"Webhook run","value":{"project_id":"00000000-0000-4000-8000-000000000001","input":{"event":"document_uploaded"},"source":{"type":"webhook","id":"webhook_example"}}},"agent_configuration":{"summary":"Agent with client tools and model configuration","value":{"project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"researcher"},"input":"Research the topic and summarize it.","config":{"conversation_mode":"create_new","tools":[{"name":"read_document","description":"Reads a document.","parameters":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}],"context":[{"type":"text","text":"Use the provided document."}],"forwarded_props":{"model":"provider/model"}}}}}}}},"responses":{"202":{"description":"Run admitted","headers":{"Location":{"schema":{"type":"string","format":"uri-reference"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunResult"},"examples":{"minimal":{"summary":"Minimal request","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"health-check"},"input":null,"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"agent":{"summary":"API-started agent","value":{"id":"22222222-2222-4222-8222-222222222222","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"coordinator"},"input":{"message":"Research the topic and summarize it."},"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"task":{"summary":"Task run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"workflow":{"summary":"Workflow run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"workflow","id":"review"},"input":{"document_id":"document_example"},"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"child":{"summary":"Child run","value":{"id":"33333333-3333-4333-8333-333333333333","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"research"},"input":{"question":"Find relevant sources."},"output":null,"parent_run_id":"22222222-2222-4222-8222-222222222222","root_run_id":"22222222-2222-4222-8222-222222222222","created_at":"2026-10-02T10:00:01Z","updated_at":"2026-10-02T10:00:01Z","trigger":{"type":"agent","id":"coordinator","tool_call_id":"call_invoke_agent"}}},"workflow_child":{"summary":"Workflow starts an agent","value":{"id":"33333333-3333-4333-8333-333333333333","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"coordinator"},"input":{"topic":"Energy storage"},"output":null,"parent_run_id":"11111111-1111-4111-8111-111111111111","root_run_id":"11111111-1111-4111-8111-111111111111","created_at":"2026-10-02T10:00:01Z","updated_at":"2026-10-02T10:00:01Z","trigger":{"type":"workflow","id":"daily-brief","node_id":"research"}}},"evaluation":{"summary":"Evaluation run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"eval"},"input":null,"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"config":{"eval_id":"eval_example"}}},"relationships":{"summary":"Conversation and batch","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"support"},"input":{"message":"Summarize this document."},"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"conversation_id":"00000000-0000-4000-8000-000000000002","batch_id":"00000000-0000-4000-8000-000000000003"}},"runtime":{"summary":"Registered runtime","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"execution":{"runtime":{"type":"registered","id":"runtime_example"}}}},"schedule":{"summary":"Saved schedule","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":null,"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"webhook":{"summary":"Webhook run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"event":"document_uploaded"},"output":null,"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-codeSamples":[{"lang":"json","label":"Request JSON","example":"minimal","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"task\",\n    \"id\": \"health-check\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"agent","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"coordinator\"\n  },\n  \"input\": {\n    \"message\": \"Research the topic and summarize it.\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"task","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"task\",\n    \"id\": \"summarize\"\n  },\n  \"input\": {\n    \"text\": \"A short document.\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"workflow","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"workflow\",\n    \"id\": \"review\"\n  },\n  \"input\": {\n    \"document_id\": \"document_example\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"child","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"research\"\n  },\n  \"input\": {\n    \"question\": \"Find relevant sources.\"\n  },\n  \"parent_run_id\": \"22222222-2222-4222-8222-222222222222\",\n  \"tool_call_id\": \"call_invoke_agent\"\n}"},{"lang":"json","label":"Request JSON","example":"workflow_child","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"coordinator\"\n  },\n  \"input\": {\n    \"topic\": \"Energy storage\"\n  },\n  \"parent_run_id\": \"11111111-1111-4111-8111-111111111111\",\n  \"node_id\": \"research\"\n}"},{"lang":"json","label":"Request JSON","example":"evaluation","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"task\",\n    \"id\": \"eval\"\n  },\n  \"config\": {\n    \"eval_id\": \"eval_example\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"relationships","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"support\"\n  },\n  \"input\": {\n    \"message\": \"Summarize this document.\"\n  },\n  \"conversation_id\": \"00000000-0000-4000-8000-000000000002\",\n  \"batch_id\": \"00000000-0000-4000-8000-000000000003\"\n}"},{"lang":"json","label":"Request JSON","example":"runtime","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"task\",\n    \"id\": \"summarize\"\n  },\n  \"input\": {\n    \"text\": \"A short document.\"\n  },\n  \"execution\": {\n    \"runtime\": {\n      \"type\": \"registered\",\n      \"id\": \"runtime_example\"\n    }\n  }\n}"},{"lang":"json","label":"Request JSON","example":"schedule","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"source\": {\n    \"type\": \"schedule\",\n    \"id\": \"00000000-0000-4000-8000-000000000002\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"webhook","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"input\": {\n    \"event\": \"document_uploaded\"\n  },\n  \"source\": {\n    \"type\": \"webhook\",\n    \"id\": \"webhook_example\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"agent_configuration","contentType":"application/json","source":"{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"researcher\"\n  },\n  \"input\": \"Research the topic and summarize it.\",\n  \"config\": {\n    \"conversation_mode\": \"create_new\",\n    \"tools\": [\n      {\n        \"name\": \"read_document\",\n        \"description\": \"Reads a document.\",\n        \"parameters\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"id\": {\n              \"type\": \"string\"\n            }\n          },\n          \"required\": [\n            \"id\"\n          ]\n        }\n      }\n    ],\n    \"context\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"Use the provided document.\"\n      }\n    ],\n    \"forwarded_props\": {\n      \"model\": \"provider/model\"\n    }\n  }\n}"}]}},"/runs/{run_id}":{"get":{"operationId":"getRun","tags":["Run resource"],"summary":"Get run","description":"Get run.\n\n- Historical runs may lack a trigger or target.id; newly created runs have both.\n- Execution credentials must satisfy run binding and the applicable project and conversation read checks.","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"}],"responses":{"200":{"description":"Run resource","headers":{"ETag":{"schema":{"type":"string"},"description":"Metadata version for If-Match."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"examples":{"example":{"summary":"Example response","value":{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}},"usage":{"summary":"With usage and cost","value":{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z","usage":{"tokens":{"input":120,"output":30,"cache":{"read":50,"write":0},"total":200},"cost":{"currency":"EUR","status":"posted","provider":"0.002","platform":"0.001","total":"0.003","credits":"0.3"},"model_calls":1,"capture_status":"complete"}}},"api_parent":{"summary":"API-started parent","value":{"id":"22222222-2222-4222-8222-222222222222","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"coordinator"},"input":{"message":"Research the topic and summarize it."},"output":{"summary":"Summary based on the research."},"trigger":{"type":"api_key","id":"key_example"},"created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:10Z","started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:10Z"}},"invoked_child":{"summary":"Child created by invoke_agent","value":{"id":"33333333-3333-4333-8333-333333333333","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"agent","id":"research"},"input":{"question":"Find relevant sources."},"output":{"findings":["First finding","Second finding"]},"parent_run_id":"22222222-2222-4222-8222-222222222222","root_run_id":"22222222-2222-4222-8222-222222222222","trigger":{"type":"agent","id":"coordinator","tool_call_id":"call_invoke_agent"},"created_at":"2026-10-02T10:00:01Z","updated_at":"2026-10-02T10:00:08Z","started_at":"2026-10-02T10:00:01Z","finished_at":"2026-10-02T10:00:08Z"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}},"patch":{"operationId":"updateRun","tags":["Run resource"],"summary":"Update run","description":"Update run.\n\n- Only title and labels can change; omitted fields stay unchanged, title:null clears the title and labels:{} clears labels.\n- Send the ETag in If-Match; a stale version returns 412.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"If-Match","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRunRequest"},"examples":{"minimal":{"summary":"Update title","value":{"title":"Summarize text"}},"update":{"summary":"Update title and labels","value":{"title":"Summarize text","labels":{"team":"support"}}}}}}},"responses":{"200":{"description":"Updated run resource","headers":{"ETag":{"schema":{"type":"string"},"description":"Updated metadata version."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"examples":{"minimal":{"summary":"Update title","value":{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}},"update":{"summary":"Update title and labels","value":{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z","labels":{"team":"support"}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"412":{"description":"Precondition failed","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":412}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"428":{"description":"Precondition required","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":428}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-codeSamples":[{"lang":"json","label":"Request JSON","example":"minimal","contentType":"application/json","source":"{\n  \"title\": \"Summarize text\"\n}"},{"lang":"json","label":"Request JSON","example":"update","contentType":"application/json","source":"{\n  \"title\": \"Summarize text\",\n  \"labels\": {\n    \"team\": \"support\"\n  }\n}"}]},"delete":{"operationId":"deleteRun","tags":["Run resource"],"summary":"Delete run","description":"Delete run.\n\n- Administrator access is required. Only a terminal run without direct children can be deleted; its cancelled execution must have stopped and its parent, if present, must be terminal.\n- 204 confirms deletion of the run and its events.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"}],"responses":{"204":{"description":"Run, its events, and owned input requests deleted; referenced artifact files are retained."},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/runs/{run_id}/artifacts/{artifact_id}":{"get":{"operationId":"downloadRunArtifact","tags":["Run resource"],"summary":"Download a run artifact","description":"Requires read access to the owning run. Returns the exact bytes identified by the artifact SHA-256.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"required":true,"name":"artifact_id","in":"path"}],"responses":{"200":{"description":"Artifact bytes","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/runs/{run_id}/cancel":{"post":{"operationId":"cancelRun","tags":["Run actions"],"summary":"Cancel run","description":"Cancel run.\n\n- 202 confirms a cancellation request; inspect status and control.cancellation for confirmation.\n- A terminal state prevents further execution; conflicting terminal actions return 409.\n- Retry with the same Idempotency-Key and payload to receive the original response; a changed payload with the same key returns 409.\n- Cancel requests cancellation of the run and all its descendants. Atomically gate new work and new child admission against cancellation of any ancestor; retry delivery of stop requests. Do not cancel ancestors or unrelated siblings. stopped_at confirms this run’s stop acknowledgement; descendants.active=0 alone does not confirm that descendant executions stopped. Already terminal outcomes are not rewritten.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the idempotency key."},"required":true,"description":"Provide the idempotency key.","name":"Idempotency-Key","in":"header"}],"responses":{"202":{"description":"Cancellation requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"examples":{"example":{"summary":"Example response","value":{"id":"11111111-1111-4111-8111-111111111111","status":"running","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","control":{"cancellation":{"requested_at":"2026-10-02T10:00:00Z","stopped_at":null}}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/runs/{run_id}/resume":{"post":{"operationId":"resumeRun","tags":["Run actions"],"summary":"Resume run","description":"Resume run.\n\n- Only a signal matching the current wait is accepted; a mismatch returns 409.\n- Use type=manual for a confirmed manual pause; workflow approval and event signals must include the current wait_id.\n- Resume preserves the run ID and original trigger. Manual, approval and event resumes requeue the run; tool-result acceptance may requeue it, forward to a live runtime or leave it failed.\n- Retry with the same Idempotency-Key and payload to receive the original response; a changed payload with the same key returns 409.\n- Pause affects this run at its next safe boundary, not its descendants. Manual resume requeues this same run and only clears its matching wait. Child outcomes arriving while manually paused remain durable until resume.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the idempotency key."},"required":true,"description":"Provide the idempotency key.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeRunRequest"},"examples":{"manual":{"summary":"Resume paused run","value":{"type":"manual"}},"tool_result":{"summary":"Return tool result","value":{"type":"tool_result","tool_call_id":"call_example","result":{"approved":true}}},"approval":{"summary":"Approve workflow step","value":{"type":"approval","wait_id":"wait_example","node_id":"review","approved":true}},"event":{"summary":"Deliver awaited event","value":{"type":"event","wait_id":"wait_example","name":"payment_received","payload":{"invoice_id":"invoice_example"}}},"integration":{"summary":"Integration connected","value":{"type":"integration_connected","integration":"example-integration"}}}}}},"responses":{"202":{"description":"Run resumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"examples":{"manual":{"summary":"Resume paused run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"tool_result":{"summary":"Return tool result","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"approval":{"summary":"Approve workflow step","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"event":{"summary":"Deliver awaited event","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}},"integration":{"summary":"Integration connected","value":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-codeSamples":[{"lang":"json","label":"Request JSON","example":"manual","contentType":"application/json","source":"{\n  \"type\": \"manual\"\n}"},{"lang":"json","label":"Request JSON","example":"tool_result","contentType":"application/json","source":"{\n  \"type\": \"tool_result\",\n  \"tool_call_id\": \"call_example\",\n  \"result\": {\n    \"approved\": true\n  }\n}"},{"lang":"json","label":"Request JSON","example":"approval","contentType":"application/json","source":"{\n  \"type\": \"approval\",\n  \"wait_id\": \"wait_example\",\n  \"node_id\": \"review\",\n  \"approved\": true\n}"},{"lang":"json","label":"Request JSON","example":"event","contentType":"application/json","source":"{\n  \"type\": \"event\",\n  \"wait_id\": \"wait_example\",\n  \"name\": \"payment_received\",\n  \"payload\": {\n    \"invoice_id\": \"invoice_example\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"integration","contentType":"application/json","source":"{\n  \"type\": \"integration_connected\",\n  \"integration\": \"example-integration\"\n}"}]}},"/runs/{run_id}/pause":{"post":{"operationId":"pauseRun","tags":["Run actions"],"summary":"Pause run","description":"Pause run.\n\n- 202 confirms the pause request, not that execution stopped.\n- Runs without an accessible canonical project scope return 404. After run authorization succeeds, a running agent without project-bound dispatch stop authority returns 409 RUN_NOT_PAUSABLE.\n- A confirmed pause has status=waiting and control.waiting.reason=manual_pause; control.pause records when it was requested.\n- Retry with the same Idempotency-Key and payload to receive the original response; a changed payload with the same key returns 409.\n- Pause affects this run at its next safe boundary, not its descendants. Resume requeues this same run and only clears its matching wait. Child outcomes arriving while manually paused remain durable until resume.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the idempotency key."},"required":true,"description":"Provide the idempotency key.","name":"Idempotency-Key","in":"header"}],"responses":{"202":{"description":"Pause requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"examples":{"example":{"summary":"Example response","value":{"id":"11111111-1111-4111-8111-111111111111","status":"running","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","control":{"pause":{"requested_at":"2026-10-02T10:00:00Z"}}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/runs/{run_id}/finalize":{"post":{"operationId":"finalizeRun","tags":["Run actions"],"summary":"Finalize a run","description":"Finalizes a run with output or an error.","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"parameters":[{"name":"X-Veryfront-Run-Terminal-Token","in":"header","required":false,"schema":{"type":"string","minLength":1},"description":"Required for execution credentials."},{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the idempotency key."},"required":true,"description":"Provide the idempotency key.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeRunRequest"},"examples":{"completed":{"summary":"Complete run","value":{"status":"completed","output":{"summary":"A short summary."}}},"failed":{"summary":"Fail run","value":{"status":"failed","error":{"code":"TASK_FAILED","message":"The task could not be completed."}}}}}}},"responses":{"200":{"description":"Terminal run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"examples":{"completed":{"summary":"Complete run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}},"failed":{"summary":"Fail run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"failed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"error":{"code":"TASK_FAILED","message":"The task could not be completed."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-codeSamples":[{"lang":"json","label":"Request JSON","example":"completed","contentType":"application/json","source":"{\n  \"status\": \"completed\",\n  \"output\": {\n    \"summary\": \"A short summary.\"\n  }\n}"},{"lang":"json","label":"Request JSON","example":"failed","contentType":"application/json","source":"{\n  \"status\": \"failed\",\n  \"error\": {\n    \"code\": \"TASK_FAILED\",\n    \"message\": \"The task could not be completed.\"\n  }\n}"}]}},"/runs/{run_id}/succeed":{"post":{"operationId":"succeedRun","tags":["Run actions"],"summary":"Succeed a run","description":"Completes a run successfully.","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"parameters":[{"name":"X-Veryfront-Run-Terminal-Token","in":"header","required":false,"schema":{"type":"string","minLength":1},"description":"Required for execution credentials."},{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the idempotency key."},"required":true,"description":"Provide the idempotency key.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SucceedRunRequest"},"examples":{"completed":{"value":{"output":{"summary":"A short summary."}}}}}}},"responses":{"200":{"description":"Terminal run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"examples":{"completed":{"summary":"Complete run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-codeSamples":[{"lang":"json","label":"Request JSON","example":"completed","contentType":"application/json","source":"{\n  \"output\": {\n    \"summary\": \"A short summary.\"\n  }\n}"}]}},"/runs/{run_id}/fail":{"post":{"operationId":"failRun","tags":["Run actions"],"summary":"Fail a run","description":"Fails a run.","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"parameters":[{"name":"X-Veryfront-Run-Terminal-Token","in":"header","required":false,"schema":{"type":"string","minLength":1},"description":"Required for execution credentials."},{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the idempotency key."},"required":true,"description":"Provide the idempotency key.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailRunRequest"},"examples":{"failed":{"value":{"error":{"code":"TASK_FAILED","message":"The task could not be completed."}}}}}}},"responses":{"200":{"description":"Terminal run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"examples":{"failed":{"summary":"Fail run","value":{"id":"11111111-1111-4111-8111-111111111111","status":"failed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":null,"error":{"code":"TASK_FAILED","message":"The task could not be completed."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-codeSamples":[{"lang":"json","label":"Request JSON","example":"failed","contentType":"application/json","source":"{\n  \"error\": {\n    \"code\": \"TASK_FAILED\",\n    \"message\": \"The task could not be completed.\"\n  }\n}"}]}},"/runs/{run_id}/events":{"get":{"operationId":"listRunEvents","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"tags":["Run events"],"summary":"List run events","description":"List run events.\n\n- Filter by event_type only when needed; omit filters to list all visible events.\n- Each known event has a named payload type; unknown historical or future types use the fallback.\n- Recorded payloads retain their original field names, including inputRequest.id; resource renames do not rewrite event history.\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.\n- Execution credentials must satisfy run binding and the applicable project and conversation read checks.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","description":"The previous page’s `page_info.next` event ID, excluded from the next page. With `sort_order=asc`, returns larger IDs; with `sort_order=desc`, returns smaller IDs. If omitted, starts at the oldest event for ascending order or the newest for descending order."},"required":false,"description":"Opaque page_info.next cursor; reuse with unchanged filters and ordering.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Event order. `asc` returns oldest first; `desc` returns newest first. Defaults to `asc`."},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991,"description":"Deprecated. Use `cursor`. Accepted as an ascending cursor; 0 means no cursor."},"required":false,"name":"after_event_id","in":"query"},{"schema":{"type":"string","enum":["fact","delta"],"description":"Event class to include: `fact` for state changes or `delta` for streaming fragments. If omitted, returns both."},"required":false,"description":"The event class associated with this record.","name":"event_class","in":"query"},{"schema":{"type":"array","items":{"type":"string"},"maxItems":32},"required":false,"description":"Filter by event_type. Repeat the query parameter for multiple values; comma-separated values remain a compatibility alias. Values within this filter use OR; different filters use AND.","style":"form","explode":true,"name":"event_type","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"If true, returns only events with `is_error: true`. If false, returns other events. If omitted, returns both."},"required":false,"name":"is_error","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events created at or after this instant (ISO 8601 with a UTC offset, inclusive). A summary bucket start can be sent as is."},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events created before this instant (ISO 8601 with a UTC offset, exclusive). Must be later than start. A summary bucket end can be sent as is."},"required":false,"name":"end","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Only events whose envelope span_id, as served to the caller, is exactly this value (tool:<id>, message:<id>, step:<id>, input_request:<id>, run:<id>, with a non-empty <id>)."},"required":false,"name":"span_id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Only events whose envelope turn_id, as served to the caller, is exactly this value (message:<id>, with a non-empty <id>)."},"required":false,"name":"turn_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Case-insensitive substring of the event payload JSON as served to the caller (1-200 characters after trimming, matched literally)."},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"If true, includes events from readable descendant runs, up to 16 generations. Results share one `event_id` order and cursor. Each event retains its `run_id` and the payload visibility permitted for that run. Runs the caller cannot read are excluded. Defaults to false.\n\nIf at least one descendant is included, task or workflow runs without stored events do not contribute synthetic lifecycle events. Event IDs are allocated before commit. During active writes, ascending pagination can pass an ID that another run commits later."},"required":false,"name":"include_descendants","in":"query"}],"responses":{"200":{"description":"Run events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRunEventsResponse"},"examples":{"example":{"summary":"Example response","value":{"data":[{"event_id":42,"event_type":"MODEL_CALL_COMPLETED","payload":{"type":"MODEL_CALL_COMPLETED","provider":"example-provider","model":"example-model","inputTokens":120,"outputTokens":30,"cacheCreationTokens":0,"cacheReadTokens":0,"totalTokens":150,"costCredits":"0.001","latencyMs":800,"usageCaptureStatus":"complete","providerRequestId":"request_example","modelCallContextEventId":null},"is_error":false,"created_at":"2026-10-02T10:00:00Z","run_id":"11111111-1111-4111-8111-111111111111","event_class":"fact","span_id":"span_example","parent_span_id":null,"turn_id":null,"origin_event_type":"MODEL_CALL_COMPLETED","origin_custom_name":null,"unrecoverable_fields":[]}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}},"post":{"operationId":"appendRunEvents","tags":["Run events"],"summary":"Append run events","description":"Append run events.\n\n- Each event uses its named payload schema; the payload type selects the variant.\n- Append permission is required for the bound run and current execution generation; durable cursors identify persisted events.","security":[{"runEventWriterAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendRunEventsRequest"},"examples":{"text_message":{"summary":"Start an assistant message","value":{"events":[{"type":"TEXT_MESSAGE_START","messageId":"message_example","contentId":"content_example","role":"assistant"}]}}}}}},"responses":{"200":{"description":"Persisted event cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendRunEventsResponse"},"examples":{"model_call":{"summary":"Record completed model call","value":{"run_id":"11111111-1111-4111-8111-111111111111","latest_event_id":42,"appended_count":1}}}}}},"400":{"description":"Bad request","headers":{"X-Run-Latest-Event-Id":{"schema":{"type":"integer","minimum":0,"description":"Current durable cursor after an authenticated append mismatch."},"required":true},"X-Run-Latest-External-Sequence":{"schema":{"type":"integer","minimum":0,"description":"Current external sequence after an authenticated append mismatch."},"required":true}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":503}}}]}}}}},"x-audience":"component-internal","x-codeSamples":[{"lang":"json","label":"Request JSON","example":"text_message","contentType":"application/json","source":"{\n  \"events\": [\n    {\n      \"type\": \"TEXT_MESSAGE_START\",\n      \"messageId\": \"message_example\",\n      \"contentId\": \"content_example\",\n      \"role\": \"assistant\"\n    }\n  ]\n}"}]}},"/runs/{run_id}/events/{event_id}":{"get":{"operationId":"getRunEvent","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"tags":["Run events"],"summary":"Get run event","description":"Get run event.\n\n- Returns the event envelope and payload permitted for the caller.\n- Execution credentials must satisfy run binding and the applicable project and conversation read checks.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":true,"example":1,"name":"event_id","in":"path"}],"responses":{"200":{"description":"Run event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEvent"},"examples":{"example":{"summary":"Example response","value":{"event_id":42,"event_type":"MODEL_CALL_COMPLETED","payload":{"type":"MODEL_CALL_COMPLETED","provider":"example-provider","model":"example-model","inputTokens":120,"outputTokens":30,"cacheCreationTokens":0,"cacheReadTokens":0,"totalTokens":150,"costCredits":"0.001","latencyMs":800,"usageCaptureStatus":"complete","providerRequestId":"request_example","modelCallContextEventId":null},"is_error":false,"created_at":"2026-10-02T10:00:00Z","run_id":"11111111-1111-4111-8111-111111111111","event_class":"fact","span_id":"span_example","parent_span_id":null,"turn_id":null,"origin_event_type":"MODEL_CALL_COMPLETED","origin_custom_name":null,"unrecoverable_fields":[]}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/runs/{run_id}/events/summary":{"get":{"operationId":"getRunEventsSummary","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"tags":["Run events"],"summary":"Get run event summary","description":"Get run event summary.\n\n- Returns event counts, error counts, event-class and event-type breakdowns, and time buckets.\n- Execution credentials must satisfy run binding and the applicable project and conversation read checks.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":60,"description":"Number of time buckets spanning first_event_at up to 1 ms past last_event_at (1-500, default 60). Bucket boundaries are whole milliseconds and every bucket is at least 1 ms wide, so the response holds at most as many buckets as the span has milliseconds and may return fewer than requested (a 10 ms span returns at most 10)."},"required":false,"name":"buckets","in":"query"},{"schema":{"type":"string","enum":["fact","delta"],"description":"Event class to include: `fact` for state changes or `delta` for streaming fragments. If omitted, returns both."},"required":false,"description":"The event class associated with this record.","name":"event_class","in":"query"},{"schema":{"type":"array","items":{"type":"string"},"maxItems":32},"required":false,"description":"Filter by event_type. Repeat the query parameter for multiple values; comma-separated values remain a compatibility alias. Values within this filter use OR; different filters use AND.","style":"form","explode":true,"name":"event_type","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"If true, returns only events with `is_error: true`. If false, returns other events. If omitted, returns both."},"required":false,"name":"is_error","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events created at or after this instant (ISO 8601 with a UTC offset, inclusive). A summary bucket start can be sent as is."},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events created before this instant (ISO 8601 with a UTC offset, exclusive). Must be later than start. A summary bucket end can be sent as is."},"required":false,"name":"end","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Only events whose envelope span_id, as served to the caller, is exactly this value (tool:<id>, message:<id>, step:<id>, input_request:<id>, run:<id>, with a non-empty <id>)."},"required":false,"name":"span_id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Only events whose envelope turn_id, as served to the caller, is exactly this value (message:<id>, with a non-empty <id>)."},"required":false,"name":"turn_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Case-insensitive substring of the event payload JSON as served to the caller (1-200 characters after trimming, matched literally)."},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"If true, includes events from readable descendant runs, up to 16 generations. Results share one `event_id` order and cursor. Each event retains its `run_id` and the payload visibility permitted for that run. Runs the caller cannot read are excluded. Defaults to false.\n\nIf at least one descendant is included, task or workflow runs without stored events do not contribute synthetic lifecycle events. Event IDs are allocated before commit. During active writes, ascending pagination can pass an ID that another run commits later."},"required":false,"name":"include_descendants","in":"query"}],"responses":{"200":{"description":"Run event summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEventSummary"},"examples":{"example":{"summary":"Example response","value":{"run_id":"11111111-1111-4111-8111-111111111111","total":0,"error_count":0,"first_event_id":null,"last_event_id":null,"first_event_at":null,"last_event_at":null,"by_event_class":{"fact":0,"delta":0},"by_event_type":[],"buckets":[]}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":500}}}]}}}}}}},"/runs/{run_id}/snapshot":{"get":{"operationId":"getRunSnapshot","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"tags":["Run events"],"summary":"Get run snapshot","description":"Get run snapshot.\n\n- Returns replay events and after_event_id for continuing event reads.\n- Execution credentials must satisfy run binding and the applicable project and conversation read checks.\n- Task and workflow snapshots capture a fixed event cutoff and allow up to 5000 events or 10 MiB. Larger histories return 400 RUN_SNAPSHOT_LIMIT_EXCEEDED; use paginated run events.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"}],"responses":{"200":{"description":"Run event snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEventSnapshot"},"examples":{"example":{"summary":"Example response","value":{"after_event_id":42,"events":[{"event_id":42,"event_type":"MODEL_CALL_COMPLETED","payload":{"type":"MODEL_CALL_COMPLETED","provider":"example-provider","model":"example-model","inputTokens":120,"outputTokens":30,"cacheCreationTokens":0,"cacheReadTokens":0,"totalTokens":150,"costCredits":"0.001","latencyMs":800,"usageCaptureStatus":"complete","providerRequestId":"request_example","modelCallContextEventId":null},"is_error":false,"created_at":"2026-10-02T10:00:00Z","run_id":"11111111-1111-4111-8111-111111111111","event_class":"fact","span_id":"span_example","parent_span_id":null,"turn_id":null,"origin_event_type":"MODEL_CALL_COMPLETED","origin_custom_name":null,"unrecoverable_fields":[]}]}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/runs/{run_id}/stream":{"get":{"operationId":"streamRunEvents","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"tags":["Run events"],"summary":"Stream run events","description":"Stream run events.\n\n- Live delivery can be repeated and does not prove durable persistence; use recorded events for the durable history.\n- Execution credentials must satisfy run binding and the applicable project and conversation read checks.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"last-event-id","in":"header"}],"responses":{"200":{"description":"Run event stream","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent event frames. Each data field contains a JSON RunStreamFrame.","x-event-schema":{"$ref":"#/components/schemas/RunStreamFrame"}},"examples":{"stream":{"summary":"Illustrative event frame","value":"id: 42\ndata: {\"type\":\"MODEL_CALL_COMPLETED\",\"provider\":\"example-provider\",\"model\":\"example-model\",\"inputTokens\":120,\"outputTokens\":30,\"cacheCreationTokens\":0,\"cacheReadTokens\":0,\"totalTokens\":150,\"costCredits\":\"0.001\",\"latencyMs\":800,\"usageCaptureStatus\":\"complete\",\"providerRequestId\":\"request_example\",\"modelCallContextEventId\":null}\n\n"}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/runs/event-types":{"get":{"operationId":"listRunEventTypes","tags":["Run events"],"summary":"List run event types","description":"List run event types.\n\n- Returns the complete event-type catalog in data; this operation has no filters or pagination.","responses":{"200":{"description":"Run event types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRunEventTypesResponse"},"examples":{"example":{"summary":"Example response","value":{"data":[{"type":"MODEL_CALL_COMPLETED","name":"Model call completed","group":"Model","scope":"ag-ui","event_class":"fact","status":"active","viewer_visibility":"full","description":"Records model usage after a completed call.","fields":["provider","model","inputTokens","outputTokens","cacheCreationTokens","cacheReadTokens","totalTokens","costCredits","latencyMs","usageCaptureStatus","providerRequestId","modelCallContextEventId"]}]}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/schemas/run-events/{schema_file}":{"get":{"operationId":"getRunEventDataSchema","tags":["Run events"],"summary":"Get run event data schema","description":"Return the generated JSON Schema for a current public run event type.","parameters":[{"schema":{"type":"string","maxLength":133,"pattern":"^[A-Z][A-Z0-9_]*\\.json$"},"required":true,"name":"schema_file","in":"path"}],"responses":{"200":{"description":"Run event data JSON Schema","content":{"application/json":{"schema":{"type":"object","properties":{"$schema":{"type":"string","format":"uri"},"$id":{"type":"string","format":"uri"}},"required":["$schema","$id"]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/runs/{run_id}/child-runs":{"get":{"operationId":"listRunChildRuns","tags":["Child runs"],"summary":"List child runs","security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"description":"List child runs.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.\n- Execution credentials require authorized read access to the parent; each child is checked for visibility.\n- Persist terminal child outcome and delivery intent atomically. Delivery is at least once; the parent consumes an outcome once per child and durable invocation, preserving identity across retries/restarts. Handled failure or cancellation allows recovery; unhandled child outcome fails the parent and requests cancellation of its remaining descendants. Do not cancel siblings merely because one child failed while the parent handles it.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"format":"int32"},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"The `page_info.next` of the previous page: the `run_id` of its last child. A cursor that is not a child of this run returns a 400."},"required":false,"description":"Opaque page_info.next cursor; reuse with unchanged filters and ordering.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Child run page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsPage"},"examples":{"example":{"summary":"Example response","value":{"data":[{"id":"44444444-4444-4444-8444-444444444444","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","parent_run_id":"11111111-1111-4111-8111-111111111111","root_run_id":"11111111-1111-4111-8111-111111111111","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/runs/{run_id}/input-requests":{"get":{"operationId":"listRunInputRequests","tags":["Run input request"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"summary":"List run input requests","description":"List run input requests.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.\n- Project and private-conversation permissions apply; password values are never returned.\n- Runtime input reads require conversations:read and authorized access to the bound run.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","enum":["open","submitted","cancelled","expired"],"description":"Lifecycle status for the target record."},"required":false,"description":"Lifecycle status for the target record.","name":"status","in":"query"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"}],"responses":{"200":{"description":"Input request page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListInputRequestsResponse"},"examples":{"example":{"summary":"Example response","value":{"data":[{"input_request_id":"00000000-0000-4000-8000-000000000001","project_id":"00000000-0000-4000-8000-000000000001","run_id":"11111111-1111-4111-8111-111111111111","title":"Approve the result","fields":[{"name":"approved","type":"confirm","label":"Approve the result?","required":true}],"status":"open","requested_responder_type":"human","response":null,"created_at":"2026-10-02T10:00:00Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}},"post":{"operationId":"createRunInputRequest","tags":["Run input request"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"summary":"Create input request","description":"Create input request.\n\n- The run supplies project and conversation scope; send the required title and fields, with optional description, expires_at, requested_responder_type, tool_call_id and metadata.\n- Requires an agent input-wait runtime. Supply tool_call_id unless the runtime already records a waiting tool call; otherwise creation returns 409. Creation does not pause execution; the runtime must register the matching durable wait.\n- Password fields cannot have defaults; values must never appear in reads, events, replay responses or logs.\n- Runtime input creation requires conversations:write, authorized access to the bound run and conversation editor access when applicable.\n- Retry with the same Idempotency-Key and payload to receive the original response; a changed payload with the same key returns 409.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInputRequestRequest"},"examples":{"minimal":{"summary":"Request a decision","value":{"title":"Approve the result","fields":[{"name":"approved","type":"confirm"}]}},"approval":{"summary":"Request approval","value":{"tool_call_id":"call_example","requested_responder_type":"human","title":"Approve the result","fields":[{"name":"approved","type":"confirm","label":"Approve the result?","required":true}]}}}}}},"responses":{"201":{"description":"Input request created or idempotently replayed","headers":{"Location":{"schema":{"type":"string","format":"uri-reference"},"description":"Canonical input request URL."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputRequest"},"examples":{"minimal":{"summary":"Request a decision","value":{"input_request_id":"00000000-0000-4000-8000-000000000001","project_id":"00000000-0000-4000-8000-000000000001","run_id":"11111111-1111-4111-8111-111111111111","title":"Approve the result","fields":[{"required":false,"name":"approved","type":"confirm"}],"status":"open","requested_responder_type":"human","response":null,"created_at":"2026-10-02T10:00:00Z"}},"approval":{"summary":"Request approval","value":{"input_request_id":"00000000-0000-4000-8000-000000000001","project_id":"00000000-0000-4000-8000-000000000001","run_id":"11111111-1111-4111-8111-111111111111","title":"Approve the result","fields":[{"required":true,"name":"approved","type":"confirm","label":"Approve the result?"}],"status":"open","requested_responder_type":"human","response":null,"created_at":"2026-10-02T10:00:00Z","tool_call_id":"call_example"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-codeSamples":[{"lang":"json","label":"Request JSON","example":"minimal","contentType":"application/json","source":"{\n  \"title\": \"Approve the result\",\n  \"fields\": [\n    {\n      \"name\": \"approved\",\n      \"type\": \"confirm\"\n    }\n  ]\n}"},{"lang":"json","label":"Request JSON","example":"approval","contentType":"application/json","source":"{\n  \"tool_call_id\": \"call_example\",\n  \"requested_responder_type\": \"human\",\n  \"title\": \"Approve the result\",\n  \"fields\": [\n    {\n      \"name\": \"approved\",\n      \"type\": \"confirm\",\n      \"label\": \"Approve the result?\",\n      \"required\": true\n    }\n  ]\n}"}]}},"/input-requests/{input_request_id}":{"get":{"operationId":"getInputRequest","tags":["Input request"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"runExecutionAuth":[]}],"summary":"Get input request","description":"Get input request.\n\n- Project and private-conversation permissions apply; password values are never returned.\n- Runtime input reads require conversations:read and authorized access to the bound run.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Provide the input request id."},"required":true,"description":"Provide the input request id.","example":"00000000-0000-4000-8000-000000000001","name":"input_request_id","in":"path"}],"responses":{"200":{"description":"Input request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputRequest"},"examples":{"example":{"summary":"Example response","value":{"input_request_id":"00000000-0000-4000-8000-000000000001","project_id":"00000000-0000-4000-8000-000000000001","run_id":"11111111-1111-4111-8111-111111111111","title":"Approve the result","fields":[{"name":"approved","type":"confirm","label":"Approve the result?","required":true}],"status":"open","requested_responder_type":"human","response":null,"created_at":"2026-10-02T10:00:00Z"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/input-requests/{input_request_id}/responses":{"post":{"operationId":"createInputResponse","tags":["Input request"],"summary":"Respond to input request","description":"Respond to input request.\n\n- Submit values keyed by field name; responder identity comes from authentication.\n- Values must match the stored fields and required responder role; runtime execution credentials do not impersonate human responders.\n- Submission, cancellation and expiry compete atomically; a different resolution after completion returns 409.\n- Only the matching durable wait is resumed; the response returns the updated input request with password values omitted.\n- Retry with the same Idempotency-Key and payload to receive the original response; a changed payload with the same key returns 409.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Provide the input request id."},"required":true,"description":"Provide the input request id.","example":"00000000-0000-4000-8000-000000000001","name":"input_request_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespondToInputRequestRequest"},"examples":{"approval":{"summary":"Submit approval","value":{"values":{"approved":true}}}}}}},"responses":{"200":{"description":"InputRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputRequest"},"examples":{"approval":{"summary":"Submit approval","value":{"input_request_id":"00000000-0000-4000-8000-000000000001","project_id":"00000000-0000-4000-8000-000000000001","run_id":"11111111-1111-4111-8111-111111111111","title":"Approve the result","fields":[{"name":"approved","type":"confirm","label":"Approve the result?","required":true}],"status":"submitted","requested_responder_type":"human","response":{"response_id":"00000000-0000-4000-8000-000000000002","values":{"approved":true},"actor":{"type":"user","id":"user_example"},"created_at":"2026-10-02T10:00:00Z"},"created_at":"2026-10-02T10:00:00Z","resolved_at":"2026-10-02T10:00:00Z"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":503}}}]}}}}},"x-codeSamples":[{"lang":"json","label":"Request JSON","example":"approval","contentType":"application/json","source":"{\n  \"values\": {\n    \"approved\": true\n  }\n}"}]}},"/input-requests/{input_request_id}/cancel":{"post":{"operationId":"cancelInputRequest","tags":["Input request"],"summary":"Cancel input request","description":"Cancel input request.\n\n- Only an open input request can be cancelled; an already resolved request returns 409 unless this is an identical idempotent replay.\n- Cancelling the request does not cancel the run; notify its matching durable wait with cancellation rather than fabricated field values.\n- Retry with the same Idempotency-Key and payload to receive the original response; a changed payload with the same key returns 409.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Provide the input request id."},"required":true,"description":"Provide the input request id.","example":"00000000-0000-4000-8000-000000000001","name":"input_request_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Cancelled input request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputRequest"},"examples":{"example":{"summary":"Example response","value":{"input_request_id":"00000000-0000-4000-8000-000000000001","project_id":"00000000-0000-4000-8000-000000000001","run_id":"11111111-1111-4111-8111-111111111111","title":"Approve the result","fields":[{"name":"approved","type":"confirm","label":"Approve the result?","required":true}],"status":"cancelled","requested_responder_type":"human","response":null,"created_at":"2026-10-02T10:00:00Z","resolved_at":"2026-10-02T10:00:00Z"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/runs/{run_id}/heartbeats":{"post":{"operationId":"createRunHeartbeat","tags":["Runtime"],"security":[{"runExecutionAuth":[]}],"summary":"Send run heartbeat","description":"Send run heartbeat.\n\n- Renews execution authority for the bound run, using 60 seconds when the required JSON body is an empty object ({}).\n- Terminal, cancelled or stale execution authority returns 409; a heartbeat never starts a new execution.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunHeartbeatRequest"},"examples":{"minimal":{"summary":"Renew with default duration","value":{}},"renew":{"summary":"Renew execution authority","value":{"lease_duration_seconds":60}}}}}},"responses":{"200":{"description":"Execution lease renewed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunHeartbeat"},"examples":{"minimal":{"summary":"Renew with default duration","value":{"run_id":"11111111-1111-4111-8111-111111111111","expires_at":"2026-10-02T10:01:00Z"}},"renew":{"summary":"Renew execution authority","value":{"run_id":"11111111-1111-4111-8111-111111111111","expires_at":"2026-10-02T10:01:00Z"}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":413}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-audience":"component-internal","x-codeSamples":[{"lang":"json","label":"Request JSON","example":"minimal","contentType":"application/json","source":"{}"},{"lang":"json","label":"Request JSON","example":"renew","contentType":"application/json","source":"{\n  \"lease_duration_seconds\": 60\n}"}]}},"/runs/{run_id}/event-tokens":{"post":{"operationId":"createRunEventToken","tags":["Runtime"],"security":[{"runExecutionAuth":[]}],"summary":"Create run event token","description":"Create run event token.\n\n- The parent execution credential, or an event token delegated under its execution generation, may mint append-only authority for the direct child identified by run_id.\n- A delegated token may mint event tokens for its own direct children while the root execution generation is current.\n- The token cannot read events, finalize, heartbeat or create children.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Run identifier that scopes the request."},"required":true,"description":"Run identifier that scopes the request.","example":"11111111-1111-4111-8111-111111111111","name":"run_id","in":"path"}],"responses":{"201":{"description":"Scoped event token created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEventToken"},"examples":{"example":{"summary":"Example response","value":{"token":"example-token","token_type":"Bearer","expires_at":"2026-10-02T10:05:00Z","run_id":"11111111-1111-4111-8111-111111111111","permissions":["run.events.append"]}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":409}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}},"x-audience":"component-internal"}},"/projects/{project_reference}/runs":{"get":{"operationId":"listProjectRuns","tags":["Project runs"],"summary":"List project runs","description":"List project runs.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"example":"example","name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]*$","description":"Discover agent runs with this persisted task identity across conversations. Matches canonical task metadata or the first enqueue request; results are not task authorization evidence."},"required":false,"description":"Filter by the persisted orchestration task identity in task_id; this is distinct from the execution definition target.","name":"task_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Opaque cursor returned by the previous page. Reuse with unchanged filters and ordering."},"required":false,"description":"Opaque page_info.next cursor; reuse with unchanged filters and ordering.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at","status","duration"],"default":"created_at","description":"Field used to order runs: created_at, status or duration. Defaults to created_at."},"required":false,"description":"Field used to order runs: created_at, status or duration. Defaults to created_at.","name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction: asc or desc. Defaults to desc."},"required":false,"description":"Sort direction: asc or desc. Defaults to desc.","name":"sort_order","in":"query"},{"schema":{"type":"array","items":{"type":"string"},"maxItems":32,"description":"Run statuses to include. Values within this filter use OR; different filters use AND."},"required":false,"description":"Filter by status. Repeat the query parameter for multiple values; comma-separated values remain a compatibility alias. Values within this filter use OR; different filters use AND.","style":"form","explode":true,"name":"status","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["agent","task","workflow","eval"]},"minItems":1,"maxItems":4,"description":"Execution definition types to include: agent, task, workflow or legacy eval."},"required":false,"description":"Filter by execution definition type.","style":"form","explode":true,"name":"target_type","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["user","api_key","service_account","system","schedule","webhook","agent","task","workflow"]},"minItems":1,"maxItems":9,"description":"Trigger types to include: user, api_key, service_account, system, schedule, webhook, agent, task or workflow."},"required":false,"description":"Filter by trigger_type.","style":"form","explode":true,"name":"trigger_type","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"true lists only top-level runs (parent_run_id null). Defaults to false."},"required":false,"name":"root_only","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"parent_run_id","in":"query"},{"schema":{"type":"array","items":{"type":"string"},"maxItems":32},"required":false,"description":"Filter by execution definition ID.","style":"form","explode":true,"name":"target_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"description":"Filter by trigger_id.","name":"trigger_id","in":"query"}],"responses":{"200":{"description":"Run page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsPage"},"examples":{"example":{"summary":"Example response","value":{"data":[{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/projects/{project_reference}/webhooks/{webhook_definition_id}/runs":{"get":{"operationId":"listProjectWebhookRuns","tags":["Webhook runs"],"summary":"List webhook runs","description":"List webhook runs.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"example":"example","name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"example":"00000000-0000-4000-8000-000000000001","name":"webhook_definition_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid","description":"The `page_info.next` of the previous page: the `webhook_event_id` of its last run. Keep `sort_order` the same across pages."},"required":false,"description":"Opaque page_info.next cursor; reuse with unchanged filters and ordering.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Creation order: desc (newest first, the default) or asc."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Run page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsPage"},"examples":{"example":{"summary":"Example response","value":{"data":[{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"webhook","id":"webhook_definition_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/projects/{project_reference}/evals/{eval_id}/runs":{"get":{"operationId":"listEvalRuns","tags":["Eval runs"],"summary":"List evaluation runs","description":"List evaluation runs.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1},"required":true,"example":"eval_example","name":"eval_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"The `page_info.next` of the previous page: the `run_id` of its last run. Keep `sort_by` and `sort_order` the same across pages."},"required":false,"description":"Opaque page_info.next cursor; reuse with unchanged filters and ordering.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at","status"],"default":"created_at","description":"Sort field. Defaults to \"created_at\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Run page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsPage"},"examples":{"example":{"summary":"Example response","value":{"data":[{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"eval"},"input":{"text":"A short document."},"output":{"report_storage":"inline","report":{"schema_version":1,"run_id":"11111111-1111-4111-8111-111111111111","eval_id":"eval_example","target":"summarize","started_at":"2026-10-02T10:00:00Z","completed_at":"2026-10-02T10:00:02Z","summary":{"records":0,"passed":0,"failed":0,"skipped":0,"pass_rate":0},"records":[]}},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/conversations/{conversation_id}/runs":{"get":{"operationId":"listConversationRuns","tags":["Conversation runs"],"summary":"List conversation runs","description":"List conversation runs.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"example":"00000000-0000-4000-8000-000000000001","name":"conversation_id","in":"path"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"},{"schema":{"type":"array","items":{"type":"string"},"maxItems":32,"description":"Run statuses to include. Values within this filter use OR; different filters use AND."},"required":false,"description":"Filter by status. Repeat the query parameter for multiple values; comma-separated values remain a compatibility alias. Values within this filter use OR; different filters use AND.","style":"form","explode":true,"name":"status","in":"query"}],"responses":{"200":{"description":"Run page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsPage"},"examples":{"example":{"summary":"Example response","value":{"data":[{"id":"11111111-1111-4111-8111-111111111111","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/conversations/{conversation_id}/input-requests":{"get":{"operationId":"listConversationInputRequests","tags":["Conversation runs"],"summary":"List conversation input requests","description":"List conversation input requests.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.\n- Project and private-conversation permissions apply; password values are never returned.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"example":"00000000-0000-4000-8000-000000000001","name":"conversation_id","in":"path"},{"schema":{"type":"string","enum":["open","submitted","cancelled","expired"],"description":"Lifecycle status for the target record."},"required":false,"description":"Lifecycle status for the target record.","name":"status","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"run_id","in":"query"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"}],"responses":{"200":{"description":"Input request page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListInputRequestsResponse"},"examples":{"example":{"summary":"Example response","value":{"data":[{"input_request_id":"00000000-0000-4000-8000-000000000001","project_id":"00000000-0000-4000-8000-000000000001","run_id":"11111111-1111-4111-8111-111111111111","title":"Approve the result","fields":[{"name":"approved","type":"confirm","label":"Approve the result?","required":true}],"status":"open","requested_responder_type":"human","response":null,"created_at":"2026-10-02T10:00:00Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/conversations/{conversation_id}/child-runs":{"get":{"operationId":"listConversationChildRuns","tags":["Conversation runs"],"summary":"List conversation child runs","description":"List conversation child runs.\n\n- Omit optional filters for the default collection; follow page_info.next with unchanged filters when pagination is provided.\n- Persist terminal child outcome and delivery intent atomically. Delivery is at least once; the parent consumes an outcome once per child and durable invocation, preserving identity across retries/restarts. Handled failure or cancellation allows recovery; unhandled child outcome fails the parent and requests cancellation of its remaining descendants. Do not cancel siblings merely because one child failed while the parent handles it.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"example":"00000000-0000-4000-8000-000000000001","name":"conversation_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"description":"Filter by tool_call_id.","name":"tool_call_id","in":"query"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","format":"int32"},"required":false,"description":"Maximum number of records in a page, from 1 to 100. Defaults to 20.","name":"limit","in":"query"}],"responses":{"200":{"description":"Child run page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsPage"},"examples":{"example":{"summary":"Example response","value":{"data":[{"id":"44444444-4444-4444-8444-444444444444","status":"completed","project_id":"00000000-0000-4000-8000-000000000001","target":{"type":"task","id":"summarize"},"input":{"text":"A short document."},"output":{"summary":"A short summary."},"title":"Summarize text","parent_run_id":"11111111-1111-4111-8111-111111111111","root_run_id":"11111111-1111-4111-8111-111111111111","created_at":"2026-10-02T10:00:00Z","updated_at":"2026-10-02T10:00:02Z","trigger":{"type":"api_key","id":"key_example"},"started_at":"2026-10-02T10:00:00Z","finished_at":"2026-10-02T10:00:02Z"}],"page_info":{"next":null}}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}}}}},"/account/analytics/runs":{"get":{"operationId":"getAccountRunAnalytics","tags":["Account runs"],"summary":"Get run analytics","description":"Get run analytics.\n\n- Returns summary, timeframe, daily series, status/model/tool/project breakdowns and authorized recent_runs.","parameters":[{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Relative timeframe preset."},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA timezone for daily bucket boundaries."},"required":false,"name":"timezone","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"}},"required":false,"name":"label","in":"query"},{"schema":{"type":"string","description":"Optional project UUID or slug to scope analytics to a single project."},"required":false,"name":"project_reference","in":"query"}],"responses":{"200":{"description":"Account run analytics statistics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunAnalytics"},"examples":{"example":{"summary":"Example response","value":{"summary":{"total_runs":0,"completed_runs":0,"failed_runs":0,"average_duration_ms":null,"p95_duration_ms":null,"last_run_at":null},"timeframe":{"from":"2026-10-01T00:00:00Z","to":"2026-10-02T00:00:00Z","granularity":"day","timezone":"UTC","bucket_count":1},"series":[],"statuses":[],"models":[],"tools":[],"projects":[],"recent_runs":[]}}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":400}}}]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":401}}}]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":403}}}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":404}}}]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1}}},"content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":429}}}]}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TargetRunProblem"},{"properties":{"status":{"const":500}}}]}}}}}}},"/runs/{run_id}/complete":{"post":{"operationId":"completeRun","tags":["Run runtime callbacks"],"summary":"Complete a runtime turn (compatibility)","description":"Completes a legacy agent runtime turn, or parks it for integration authorization.","deprecated":true,"x-deprecation":{"register_id":"CR-rest-run-complete","deprecated_at":"2026-10-01T00:00:00Z","replacement":"POST /runs/{run_id}/finalize for explicit completed/output or failed/error finalization. Automatic turn callbacks remain on the compatibility route until their parking protocol is migrated.","rollout_state":"announced","old_semantics":"Complete a runtime turn or park it while integration authorization is pending.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"},"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["completed","failed","cancelled"]},"metadata":{"type":["object","null"],"properties":{"provider":{"type":"string"},"model":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"cacheCreationInputTokens":{"type":"number"},"cacheCreation1hInputTokens":{"type":"number"},"cacheReadInputTokens":{"type":"number"},"reasoningTokens":{"type":"number"},"durationMs":{"type":"integer","minimum":0},"latencyMs":{"type":"integer","minimum":0},"timeToFirstTokenMs":{"type":"integer","minimum":0},"costUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerOutputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontOutputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontBilledUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"costCredits":{"anyOf":[{"type":"string"},{"type":"number"}]},"billableInputTokens":{"type":"integer","minimum":0},"billableOutputTokens":{"type":"integer","minimum":0},"billingMode":{"type":"string","enum":["direct","deferred"]},"usageCaptureStatus":{"type":"string","enum":["complete","partial","missing"]},"finishReason":{"type":"string"},"providerRequestId":{"type":"string"}},"required":["provider","model","inputTokens","outputTokens","finishReason"]},"terminal_error_code":{"type":["string","null"]},"terminal_error_message":{"type":["string","null"]}},"required":["status"],"additionalProperties":false}}}},"responses":{"200":{"description":"Completed or parked runtime turn","content":{"application/json":{"schema":{"type":"object","properties":{"completed":{"type":"boolean"},"run":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"id":{"type":"string","minLength":1,"description":"The run id. Same value as run_id, which it replaces."},"kind":{"type":"string","enum":["agent","workflow","task","eval"]},"status":{"type":"string","enum":["pending","running","waiting","completed","failed","cancelled"]},"owner":{"type":"object","properties":{"kind":{"type":"string","enum":["conversation","project"]},"id":{"type":"string","format":"uuid"}},"required":["kind","id"],"additionalProperties":false},"project_id":{"type":["string","null"],"format":"uuid","description":"The project the run belongs to. Null only for platform runs outside a project. With conversation_id, replaces owner."},"conversation_id":{"type":["string","null"],"format":"uuid"},"message_id":{"type":["string","null"],"format":"uuid"},"usage":{"type":["object","null"],"properties":{"requests":{"type":"integer","minimum":0,"description":"Deprecated. Keeps the legacy usage row count (the aggregate rows, or the per-call rows when there is no aggregate row); use model_calls for the billed provider call count."},"model_calls":{"type":["integer","null"],"minimum":0,"description":"Billed provider calls. Null for legacy runs that have only an aggregate usage row, and null in a subtree sum whenever any included run has a null count."},"input_tokens":{"type":"integer","minimum":0,"description":"Input tokens reported by the billed model calls."},"output_tokens":{"type":"integer","minimum":0,"description":"Output tokens reported by the billed model calls."},"cache_creation_input_tokens":{"type":"integer","minimum":0,"description":"Input tokens written to the provider cache."},"cache_read_input_tokens":{"type":"integer","minimum":0,"description":"Input tokens read from the provider cache."},"reasoning_tokens":{"type":"integer","minimum":0,"description":"Reasoning tokens reported by the provider; included in its output token count when the provider reports them that way."},"total_tokens":{"type":"integer","minimum":0,"description":"input_tokens + output_tokens + cache_creation_input_tokens + cache_read_input_tokens."},"cost_credits":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Billed credits as a decimal string; null when no cost was recorded."}},"required":["requests","model_calls","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","reasoning_tokens","total_tokens","cost_credits"],"description":"AI usage summed over the billed provider calls; token totals may undercount calls whose provider usage was not captured."},"tool_error_count":{"type":"integer","minimum":0},"children_failed":{"type":"boolean"},"parent_run_id":{"type":["string","null"],"minLength":1},"root_run_id":{"type":"string","minLength":1},"waiting_reason":{"type":["string","null"],"enum":["tool","approval","event","input","child_run","manual_pause",null]},"waiting_on":{"type":["array","null"],"items":{"type":"object","properties":{"kind":{"type":"string","enum":["run"]},"run_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"correlation":{"type":"object","properties":{"kind":{"type":"string","enum":["tool_call","workflow_node"]},"id":{"type":"string","minLength":1,"maxLength":255}},"required":["kind","id"],"additionalProperties":false,"description":"The tool call or workflow node that started the run this run waits on."}},"required":["kind","run_id","correlation"],"additionalProperties":false,"description":"A run this run waits on."},"description":"Active dependencies while waiting_reason is child_run: every listed run must finish before this run continues. Null otherwise, including runs that waited before this field existed."},"waiting":{"type":["object","null"],"properties":{"reason":{"type":"string","enum":["tool","approval","event","input","child_run","manual_pause"]},"on":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["run"]},"run_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"correlation":{"type":"object","properties":{"kind":{"type":"string","enum":["tool_call","workflow_node"]},"id":{"type":"string","minLength":1,"maxLength":255}},"required":["kind","id"],"additionalProperties":false,"description":"The tool call or workflow node that started the run this run waits on."}},"required":["kind","run_id","correlation"],"additionalProperties":false,"description":"A run this run waits on."},"description":"The runs this run waits on while reason is child_run; empty otherwise."},"pending_approvals":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"maxItems":100,"description":"Workflow approval node IDs accepted by POST /runs/{run_id}/resume as node_id. Empty for other waits."},"resume_at":{"type":["string","null"],"format":"date-time","description":"When a waiting workflow run resumes on its own (a delay or a timeout); null when nothing is scheduled."}},"required":["reason","on","pending_approvals","resume_at"],"additionalProperties":false,"description":"Why the run is waiting. Null unless status is waiting. Replaces waiting_reason and waiting_on."},"metadata":{},"cancellation":{"type":["object","null"],"properties":{"requested_at":{"type":"string","description":"When the cancel was requested."},"stopped_at":{"type":["string","null"],"description":"When the runtime confirmed that execution stopped. Null means the stop is unconfirmed, not that the run is still executing."}},"required":["requested_at","stopped_at"],"description":"Set once the run was cancelled through `POST /runs/{run_id}/cancel`; null otherwise."},"pause":{"type":["object","null"],"properties":{"requested_at":{"type":"string","description":"When the pause was requested."}},"required":["requested_at"],"additionalProperties":false,"description":"Set while a pause requested through `POST /runs/{run_id}/pause` governs the run: requested on a pending or running run, or confirmed as its manual_pause wait. Null otherwise."},"control":{"type":"object","properties":{"pause":{"$ref":"#/components/schemas/RunPause"},"waiting":{"$ref":"#/components/schemas/RunWait"}}},"title":{"type":["string","null"],"description":"The custom title set at creation with request.name; null when none was set."},"target":{"type":["string","null"]},"workflow_id":{"type":["string","null"]},"schedule_id":{"type":["string","null"],"format":"uuid"},"batch_id":{"type":["string","null"],"format":"uuid"},"runtime_target_kind":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"input":{"description":"Business input supplied to this run. Any JSON value; object keys retain their original spelling across API surfaces."},"config":{"description":"Execution configuration supplied to the definition, separate from business input. Object keys retain their original spelling across API surfaces."},"output":{"description":"The final output of a completed run. Its JSON serialization is at most 1,048,576 bytes (1 MiB) of UTF-8. A larger output is never stored or truncated: the run fails with error.code OUTPUT_TOO_LARGE and output null."},"error":{"type":["object","null"],"properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"],"description":"Why the run failed. OUTPUT_TOO_LARGE carries detail { size_bytes, limit_bytes }, and its message names both sizes."},"logs":{"type":["string","null"],"description":"Recorded execution logs; null when none were recorded."},"artifacts":{"type":"array","items":{},"description":"Artifacts recorded by the execution. An empty array means no artifacts were recorded."},"duration_ms":{"type":["integer","null"]},"exit_code":{"type":["integer","null"]},"start_mode":{"type":["string","null"]},"timeout_seconds":{"type":["integer","null"],"description":"Task runs only; null for other kinds. The execution deadline for the whole task run, in seconds, measured from its first started_at and spanning every attempt. At the deadline the runtime aborts ctx.signal and the run fails with error.code RUN_TIMEOUT. Task code that ignores ctx.signal can keep running inside the runtime process. Default 300; task:eval defaults to 7200."},"backoff_limit":{"type":["integer","null"],"description":"Task runs only; null for other kinds. How many times a failed task run is retried, with exponential backoff, before it fails: at most backoff_limit + 1 attempts. Only two failures are retried: the runtime never started the task (connection refused, or HTTP 503 with the runtime RUNTIME_SHUTTING_DOWN admission refusal), or the task threw the framework RetryableError. Every other failure, and any retry whose backoff would pass the timeout_seconds deadline, fails the run at once. Default 3; task:eval defaults to 0."},"input_schema_sha256":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"Lowercase sha256 hex of the canonical JSON Schema of the declared input schema this run ran against. Null when none is declared or the run predates schema identities."},"output_schema_sha256":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"Lowercase sha256 hex of the canonical JSON Schema of the declared output schema this run ran against. Null when none is declared or the run predates schema identities."},"input_schema_hash":{"type":["string","null"],"pattern":"^sha256:[0-9a-f]{64}$","description":"The declared input schema this run ran against, as sha256:<hex>. Replaces input_schema_sha256."},"output_schema_hash":{"type":["string","null"],"pattern":"^sha256:[0-9a-f]{64}$","description":"The declared output schema this run ran against, as sha256:<hex>. Replaces output_schema_sha256."},"trigger":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["manual","schedule","webhook","api"]},"id":{"type":["string","null"],"description":"The schedule, webhook or API key that fired the run, when there is one."},"principal":{"type":"object","properties":{"kind":{"type":"string","enum":["system","user","api_key","service_account"]},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false,"description":"Who started the run."}},"required":["kind","id","principal"],"additionalProperties":false,"description":"How and by whom the run was started. Null for runs recorded without a trigger principal. Replaces trigger_kind, trigger_id and trigger_principal_*."},"trigger_kind":{"type":["string","null"],"enum":["manual","schedule","webhook","api",null]},"trigger_id":{"type":["string","null"]},"trigger_principal_type":{"type":["string","null"],"enum":["system","user","api_key","service_account",null]},"trigger_principal_id":{"type":["string","null"]},"created_by":{"type":["string","null"],"minLength":1,"maxLength":255},"updated_at":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["run_id","id","kind","status","owner","project_id","conversation_id","message_id","usage","tool_error_count","children_failed","parent_run_id","root_run_id","waiting_reason","waiting_on","waiting","cancellation","pause","title","target","workflow_id","schedule_id","batch_id","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","error","logs","artifacts","duration_ms","exit_code","start_mode","timeout_seconds","backoff_limit","input_schema_sha256","output_schema_sha256","input_schema_hash","output_schema_hash","trigger","trigger_kind","trigger_id","created_by","updated_at","created_at","started_at","completed_at"]}},"required":["completed","run"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Gone","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-audience":"component-internal"}},"/runs/{run_id}/cancellation-ack":{"post":{"operationId":"acknowledgeProjectRunCancellationStop","tags":["Run runtime callbacks"],"security":[{"projectRunStopAuth":[]}],"summary":"Acknowledge run cancellation","description":"Confirms that an API-owned task or workflow stopped after cancellation. Requires a capability bound to the run, project, and executor attempt.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Runtime stop acknowledgement result","content":{"application/json":{"schema":{"type":"object","properties":{"acknowledged":{"type":"boolean"}},"required":["acknowledged"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-audience":"component-internal"}},"/runs/{run_id}/pause-ack":{"post":{"operationId":"acknowledgeProjectRunPause","tags":["Run runtime callbacks"],"security":[{"projectRunStopAuth":[]}],"summary":"Acknowledge run pause","description":"Called by the runtime executing an API-owned agent, task or workflow at a safe boundary. `stop` is true when a requested pause was confirmed for this attempt, or when the attempt no longer holds the run; the runtime then stops there. False means continue. An agent retains its settled model/tool step in the private checkpoint and stops there. Its original dispatch retains the lease until output flush, cleanup, and execution have positively ended, then confirms using settled=true with the same capability. A workflow stops between nodes; a task continues through its atomic invocation, then its executor retains the settled response at the pause boundary until manual resume. Repeating it after a lost reply returns the same answer. Requires a capability bound to the run, project, and executor attempt.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"checkpoint":{"type":["object","null"],"additionalProperties":{}},"settlement_required":{"type":"boolean","enum":[true]}},"additionalProperties":false},{"type":"object","properties":{"settled":{"type":"boolean","enum":[true]}},"required":["settled"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Whether the runtime stops at this boundary","content":{"application/json":{"schema":{"type":"object","properties":{"stop":{"type":"boolean"}},"required":["stop"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-audience":"component-internal"}},"/runs/{run_id}/pause-checkpoint":{"get":{"operationId":"getProjectRunPauseCheckpoint","tags":["Run runtime callbacks"],"security":[{"projectRunStopAuth":[]}],"summary":"Read the current agent dispatch continuation","description":"Private runtime continuation. Requires a capability bound to this run, project, and dispatch. A superseded dispatch receives stop=true and no checkpoint.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"string","enum":["true"]},"required":false,"name":"boundary","in":"query"}],"responses":{"200":{"description":"Private continuation for the current dispatch","content":{"application/json":{"schema":{"type":"object","properties":{"stop":{"type":"boolean"},"pauseRequested":{"type":"boolean"},"checkpoint":{"type":["object","null"],"additionalProperties":{}}},"required":["stop","checkpoint"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-audience":"component-internal"}},"/conversations":{"get":{"operationId":"listConversations","tags":["Conversations"],"summary":"List conversations","description":"List conversations for the current user.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Project UUID or slug"},"required":false,"description":"Project UUID or slug","name":"project_reference","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Provide the type."},"required":false,"description":"Provide the type.","name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"participant_ids","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Provide the agent id."},"required":false,"description":"Provide the agent id.","name":"agent_id","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Provide the user id."},"required":false,"description":"Provide the user id.","name":"user_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Provide the search."},"required":false,"description":"Provide the search.","name":"search","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["updated_at","created_at","title","message_count"],"default":"updated_at","description":"Provide the sort by."},"required":false,"description":"Provide the sort by.","name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Provide the sort order."},"required":false,"description":"Provide the sort order.","name":"sort_order","in":"query"}],"responses":{"200":{"description":"Conversation list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"project_id":{"type":["string","null"]},"responding_agent_id":{"type":["string","null"],"default":null},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":["string","null"]},"summary":{"type":["string","null"]},"status":{"type":"string","enum":["active","archived","deleted"]},"current_node":{"type":["string","null"]},"message_count":{"type":"number"},"last_message_at":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{}},"created_by":{"type":["string","null"]},"archived_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"participant_id":{"type":["string","null"]},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":["string","null"]},"agent_id":{"type":["string","null"]},"display_name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"role":{"type":"string","enum":["owner","member","viewer"]}},"required":["id","role"]},"default":[]}},"required":["id","type","status","message_count","created_by","created_at","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createConversation","tags":["Conversations"],"summary":"Create conversation","description":"Create a conversation and can atomically persist its first user message.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_reference":{"type":"string","minLength":1,"description":"Project UUID or slug"},"project_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":"string","maxLength":500,"description":"Short human-readable title for the record."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255,"description":"Provide the idempotency key."},"metadata":{"type":"object","additionalProperties":{}},"initial_message":{"type":"object","properties":{"composing_user_id":{"type":"string","format":"uuid","description":"Provide the composing user id."},"role":{"type":"string","enum":["user"],"description":"Provide the role."},"parts":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."}},"required":["type","text"],"description":"Structured option 1 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"url":{"type":"string","description":"Provide the url."}},"required":["type","upload_id","media_type"],"description":"Structured option 2 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["file"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"filename":{"type":"string","description":"Provide the filename."},"url":{"type":"string","description":"Provide the url."}},"required":["type","media_type"],"description":"Structured option 3 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_call"],"description":"Provide the type."},"id":{"type":"string","description":"Unique identifier for the target record."},"name":{"type":"string","description":"Human-readable name for the target record."},"input":{"type":"object","additionalProperties":{"description":"Additional structured values supplied to the tool."},"description":"Structured input details used by the tool."},"state":{"type":"string","enum":["streaming","pending","completed","error"],"description":"Provide the state."}},"required":["type","id","name","input","state"],"description":"Structured option 4 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"],"description":"Provide the type."},"tool_call_id":{"type":"string","description":"Tool call identifier that links this request to a prior tool invocation."},"output":{"description":"Provide the output."},"is_error":{"type":"boolean","description":"Provide the is error."}},"required":["type","tool_call_id"],"description":"Structured option 5 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["reasoning"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."},"signature":{"type":"string","description":"Provide the signature."}},"required":["type","text"],"description":"Structured option 6 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["citation"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"url":{"type":"string","description":"Provide the url."},"title":{"type":"string","description":"Short human-readable title for the record."},"quote":{"type":"string","description":"Provide the quote."}},"required":["type","source_id"],"description":"Structured option 7 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["source_document"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"media_type":{"type":"string","description":"Provide the media type."},"title":{"type":"string","description":"Short human-readable title for the record."},"filename":{"type":"string","description":"Provide the filename."}},"required":["type","source_id","media_type","title"],"description":"Structured option 8 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["step_start"],"description":"Provide the type."}},"required":["type"],"description":"Structured option 9 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["error"],"description":"Provide the type."},"code":{"type":"string","description":"Provide the code."},"message":{"type":"string","description":"Provide the message."}},"required":["type","code","message"],"description":"Structured option 10 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["data"],"description":"Provide the type."},"name":{"type":"string","description":"Human-readable name for the target record."},"value":{"description":"Provide the value."}},"required":["type","name"],"description":"Structured option 11 details used by the tool."}],"description":"One part item supplied to the tool."},"minItems":1,"maxItems":200,"description":"Provide one or more part values."},"idempotency_key":{"type":"string","maxLength":255,"description":"Provide the idempotency key."},"metadata":{"type":"object","additionalProperties":{"description":"Additional structured values supplied to the tool."},"description":"Additional structured metadata for the request."}},"required":["role","parts"],"additionalProperties":false}}}}}},"responses":{"201":{"description":"Created conversation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"project_id":{"type":["string","null"]},"responding_agent_id":{"type":["string","null"],"default":null},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":["string","null"]},"summary":{"type":["string","null"]},"status":{"type":"string","enum":["active","archived","deleted"]},"current_node":{"type":["string","null"]},"message_count":{"type":"number"},"last_message_at":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{}},"created_by":{"type":["string","null"]},"archived_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"participant_id":{"type":["string","null"]},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":["string","null"]},"agent_id":{"type":["string","null"]},"display_name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"role":{"type":"string","enum":["owner","member","viewer"]}},"required":["id","role"]},"default":[]},"initial_message_id":{"type":["string","null"],"format":"uuid"}},"required":["id","type","status","message_count","created_by","created_at","updated_at","initial_message_id"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/conversations/{id}":{"get":{"operationId":"getConversation","tags":["Conversations"],"summary":"Get conversation","description":"Return a conversation by ID.","parameters":[{"schema":{"$ref":"#/components/schemas/Uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Conversation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"project_id":{"type":["string","null"]},"responding_agent_id":{"type":["string","null"],"default":null},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":["string","null"]},"summary":{"type":["string","null"]},"status":{"type":"string","enum":["active","archived","deleted"]},"current_node":{"type":["string","null"]},"message_count":{"type":"number"},"last_message_at":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{}},"created_by":{"type":["string","null"]},"archived_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"participant_id":{"type":["string","null"]},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":["string","null"]},"agent_id":{"type":["string","null"]},"display_name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"role":{"type":"string","enum":["owner","member","viewer"]}},"required":["id","role"]},"default":[]}},"required":["id","type","status","message_count","created_by","created_at","updated_at"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateConversation","tags":["Conversations"],"summary":"Update conversation","description":"Update a conversation.","parameters":[{"schema":{"$ref":"#/components/schemas/Uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":500,"description":"Short human-readable title for the record."},"status":{"type":"string","enum":["active","archived"]},"summary":{"type":"string","maxLength":5000,"description":"Provide the summary."},"project_reference":{"type":"string","minLength":1,"description":"Project UUID or slug"},"project_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Updated conversation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"project_id":{"type":["string","null"]},"responding_agent_id":{"type":["string","null"],"default":null},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":["string","null"]},"summary":{"type":["string","null"]},"status":{"type":"string","enum":["active","archived","deleted"]},"current_node":{"type":["string","null"]},"message_count":{"type":"number"},"last_message_at":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{}},"created_by":{"type":["string","null"]},"archived_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"participant_id":{"type":["string","null"]},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":["string","null"]},"agent_id":{"type":["string","null"]},"display_name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"role":{"type":"string","enum":["owner","member","viewer"]}},"required":["id","role"]},"default":[]}},"required":["id","type","status","message_count","created_by","created_at","updated_at"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteConversation","tags":["Conversations"],"summary":"Delete conversation","description":"Soft-deletes a conversation.","parameters":[{"schema":{"$ref":"#/components/schemas/Uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Conversation deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/conversations/{id}/tree":{"get":{"operationId":"getConversationTree","tags":["Conversations"],"summary":"Get conversation tree","description":"Returns up to 1,000 conversation messages, including branches. The truncated flag indicates more messages.","parameters":[{"schema":{"$ref":"#/components/schemas/Uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Message tree and truncation status","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"}},"truncated":{"type":"boolean"}},"required":["items","truncated"]}}}}}}},"/conversations/{id}/messages":{"get":{"operationId":"listMessages","tags":["Conversation Messages"],"summary":"List messages","description":"List messages in a conversation.","parameters":[{"schema":{"$ref":"#/components/schemas/Uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Message list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"sendMessage","tags":["Conversation Messages"],"summary":"Send message","description":"Send a user message in a conversation.","parameters":[{"schema":{"$ref":"#/components/schemas/Uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"composing_user_id":{"type":"string","format":"uuid","description":"Provide the composing user id."},"parent_id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["user"],"description":"Provide the role."},"parts":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."}},"required":["type","text"],"description":"Structured option 1 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"url":{"type":"string","description":"Provide the url."}},"required":["type","upload_id","media_type"],"description":"Structured option 2 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["file"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"filename":{"type":"string","description":"Provide the filename."},"url":{"type":"string","description":"Provide the url."}},"required":["type","media_type"],"description":"Structured option 3 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_call"],"description":"Provide the type."},"id":{"type":"string","description":"Unique identifier for the target record."},"name":{"type":"string","description":"Human-readable name for the target record."},"input":{"type":"object","additionalProperties":{"description":"Additional structured values supplied to the tool."},"description":"Structured input details used by the tool."},"state":{"type":"string","enum":["streaming","pending","completed","error"],"description":"Provide the state."}},"required":["type","id","name","input","state"],"description":"Structured option 4 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"],"description":"Provide the type."},"tool_call_id":{"type":"string","description":"Tool call identifier that links this request to a prior tool invocation."},"output":{"description":"Provide the output."},"is_error":{"type":"boolean","description":"Provide the is error."}},"required":["type","tool_call_id"],"description":"Structured option 5 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["reasoning"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."},"signature":{"type":"string","description":"Provide the signature."}},"required":["type","text"],"description":"Structured option 6 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["citation"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"url":{"type":"string","description":"Provide the url."},"title":{"type":"string","description":"Short human-readable title for the record."},"quote":{"type":"string","description":"Provide the quote."}},"required":["type","source_id"],"description":"Structured option 7 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["source_document"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"media_type":{"type":"string","description":"Provide the media type."},"title":{"type":"string","description":"Short human-readable title for the record."},"filename":{"type":"string","description":"Provide the filename."}},"required":["type","source_id","media_type","title"],"description":"Structured option 8 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["step_start"],"description":"Provide the type."}},"required":["type"],"description":"Structured option 9 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["error"],"description":"Provide the type."},"code":{"type":"string","description":"Provide the code."},"message":{"type":"string","description":"Provide the message."}},"required":["type","code","message"],"description":"Structured option 10 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["data"],"description":"Provide the type."},"name":{"type":"string","description":"Human-readable name for the target record."},"value":{"description":"Provide the value."}},"required":["type","name"],"description":"Structured option 11 details used by the tool."}],"description":"One part item supplied to the tool."},"minItems":1,"maxItems":200,"description":"Provide one or more part values."},"idempotency_key":{"type":"string","maxLength":255,"description":"Provide the idempotency key."},"metadata":{"type":"object","additionalProperties":{"description":"Additional structured values supplied to the tool."},"description":"Additional structured metadata for the request."}},"required":["role","parts"]}}}},"responses":{"201":{"description":"Created message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessage"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/conversations/{conversation_id}/messages/{message_id}":{"get":{"operationId":"getMessage","tags":["Conversation Messages"],"summary":"Get message","description":"Return a message by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Message ID"},"required":true,"name":"message_id","in":"path"}],"responses":{"200":{"description":"Message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessage"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"editMessage","tags":["Conversation Messages"],"summary":"Edit message","description":"Edits a message.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Message ID"},"required":true,"name":"message_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"parts":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."}},"required":["type","text"],"description":"Structured option 1 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"url":{"type":"string","description":"Provide the url."}},"required":["type","upload_id","media_type"],"description":"Structured option 2 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["file"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"filename":{"type":"string","description":"Provide the filename."},"url":{"type":"string","description":"Provide the url."}},"required":["type","media_type"],"description":"Structured option 3 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_call"],"description":"Provide the type."},"id":{"type":"string","description":"Unique identifier for the target record."},"name":{"type":"string","description":"Human-readable name for the target record."},"input":{"type":"object","additionalProperties":{"description":"Additional structured values supplied to the tool."},"description":"Structured input details used by the tool."},"state":{"type":"string","enum":["streaming","pending","completed","error"],"description":"Provide the state."}},"required":["type","id","name","input","state"],"description":"Structured option 4 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"],"description":"Provide the type."},"tool_call_id":{"type":"string","description":"Tool call identifier that links this request to a prior tool invocation."},"output":{"description":"Provide the output."},"is_error":{"type":"boolean","description":"Provide the is error."}},"required":["type","tool_call_id"],"description":"Structured option 5 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["reasoning"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."},"signature":{"type":"string","description":"Provide the signature."}},"required":["type","text"],"description":"Structured option 6 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["citation"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"url":{"type":"string","description":"Provide the url."},"title":{"type":"string","description":"Short human-readable title for the record."},"quote":{"type":"string","description":"Provide the quote."}},"required":["type","source_id"],"description":"Structured option 7 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["source_document"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"media_type":{"type":"string","description":"Provide the media type."},"title":{"type":"string","description":"Short human-readable title for the record."},"filename":{"type":"string","description":"Provide the filename."}},"required":["type","source_id","media_type","title"],"description":"Structured option 8 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["step_start"],"description":"Provide the type."}},"required":["type"],"description":"Structured option 9 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["error"],"description":"Provide the type."},"code":{"type":"string","description":"Provide the code."},"message":{"type":"string","description":"Provide the message."}},"required":["type","code","message"],"description":"Structured option 10 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["data"],"description":"Provide the type."},"name":{"type":"string","description":"Human-readable name for the target record."},"value":{"description":"Provide the value."}},"required":["type","name"],"description":"Structured option 11 details used by the tool."}],"description":"One part item supplied to the tool."},"minItems":1,"maxItems":200}},"required":["parts"]}}}},"responses":{"200":{"description":"Updated message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessage"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteMessage","tags":["Conversation Messages"],"summary":"Delete message","description":"Soft-deletes a message.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Message ID"},"required":true,"name":"message_id","in":"path"}],"responses":{"204":{"description":"Message deleted"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/conversations/{conversation_id}/branches":{"post":{"operationId":"forkMessage","tags":["Conversation Branches"],"summary":"Fork message","description":"Create a new branch from a message.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","format":"uuid"},"composing_user_id":{"type":"string","format":"uuid"},"parts":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."}},"required":["type","text"],"description":"Structured option 1 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"url":{"type":"string","description":"Provide the url."}},"required":["type","upload_id","media_type"],"description":"Structured option 2 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["file"],"description":"Provide the type."},"upload_id":{"type":"string","format":"uuid","description":"Provide the upload id."},"media_type":{"type":"string","description":"Provide the media type."},"filename":{"type":"string","description":"Provide the filename."},"url":{"type":"string","description":"Provide the url."}},"required":["type","media_type"],"description":"Structured option 3 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_call"],"description":"Provide the type."},"id":{"type":"string","description":"Unique identifier for the target record."},"name":{"type":"string","description":"Human-readable name for the target record."},"input":{"type":"object","additionalProperties":{"description":"Additional structured values supplied to the tool."},"description":"Structured input details used by the tool."},"state":{"type":"string","enum":["streaming","pending","completed","error"],"description":"Provide the state."}},"required":["type","id","name","input","state"],"description":"Structured option 4 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"],"description":"Provide the type."},"tool_call_id":{"type":"string","description":"Tool call identifier that links this request to a prior tool invocation."},"output":{"description":"Provide the output."},"is_error":{"type":"boolean","description":"Provide the is error."}},"required":["type","tool_call_id"],"description":"Structured option 5 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["reasoning"],"description":"Provide the type."},"text":{"type":"string","maxLength":100000,"description":"Provide the text."},"signature":{"type":"string","description":"Provide the signature."}},"required":["type","text"],"description":"Structured option 6 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["citation"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"url":{"type":"string","description":"Provide the url."},"title":{"type":"string","description":"Short human-readable title for the record."},"quote":{"type":"string","description":"Provide the quote."}},"required":["type","source_id"],"description":"Structured option 7 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["source_document"],"description":"Provide the type."},"source_id":{"type":"string","description":"Provide the source id."},"media_type":{"type":"string","description":"Provide the media type."},"title":{"type":"string","description":"Short human-readable title for the record."},"filename":{"type":"string","description":"Provide the filename."}},"required":["type","source_id","media_type","title"],"description":"Structured option 8 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["step_start"],"description":"Provide the type."}},"required":["type"],"description":"Structured option 9 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["error"],"description":"Provide the type."},"code":{"type":"string","description":"Provide the code."},"message":{"type":"string","description":"Provide the message."}},"required":["type","code","message"],"description":"Structured option 10 details used by the tool."},{"type":"object","properties":{"type":{"type":"string","enum":["data"],"description":"Provide the type."},"name":{"type":"string","description":"Human-readable name for the target record."},"value":{"description":"Provide the value."}},"required":["type","name"],"description":"Structured option 11 details used by the tool."}],"description":"One part item supplied to the tool."},"minItems":1,"maxItems":200}},"required":["message_id","parts"]}}}},"responses":{"201":{"description":"Created sibling message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessage"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/conversations/{conversation_id}/branches/{message_id}":{"get":{"operationId":"listMessageBranches","tags":["Conversation Branches"],"summary":"List message branches","description":"List branches for a message.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Parent message ID"},"required":true,"name":"message_id","in":"path"}],"responses":{"200":{"description":"Branch messages","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/conversations/{conversation_id}/branch-selection":{"get":{"operationId":"getBranchSelection","tags":["Conversation Branches"],"summary":"Get branch selection","description":"Return the active branch selection for a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"}],"responses":{"200":{"description":"Current branch selection","content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":["string","null"],"format":"uuid"}},"required":["message_id"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"updateBranchSelection","tags":["Conversation Branches"],"summary":"Update branch selection","description":"Update the active branch selection for a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","format":"uuid"}},"required":["message_id"]}}}},"responses":{"200":{"description":"Updated branch selection","content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":["string","null"],"format":"uuid"}},"required":["message_id"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/conversations/{conversation_id}/participants":{"get":{"operationId":"listParticipants","tags":["Conversation Participants"],"summary":"List participants","description":"List participants in a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"}],"responses":{"200":{"description":"Participant list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"participant_id":{"type":["string","null"]},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":["string","null"]},"agent_id":{"type":["string","null"]},"display_name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"role":{"type":"string","enum":["owner","member","viewer"]},"last_read_message_id":{"type":["string","null"]},"notification_preference":{"type":"string"},"joined_at":{"type":"string"}},"required":["id","conversation_id","role","notification_preference","joined_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}}}},"post":{"operationId":"addParticipant","tags":["Conversation Participants"],"summary":"Add participant","description":"Add a participant to a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["member","viewer"],"default":"member"}},"required":["user_id"]}}}},"responses":{"201":{"description":"Added participant","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"participant_id":{"type":["string","null"]},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":["string","null"]},"agent_id":{"type":["string","null"]},"display_name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"role":{"type":"string","enum":["owner","member","viewer"]},"last_read_message_id":{"type":["string","null"]},"notification_preference":{"type":"string"},"joined_at":{"type":"string"}},"required":["id","conversation_id","role","notification_preference","joined_at"]}}}}}}},"/conversations/{conversation_id}/participants/{user_id}":{"delete":{"operationId":"removeParticipant","tags":["Conversation Participants"],"summary":"Remove participant","description":"Remove a participant from a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"User ID to remove"},"required":true,"name":"user_id","in":"path"}],"responses":{"204":{"description":"Participant removed"}}}},"/conversations/{conversation_id}/read-state":{"get":{"operationId":"getReadState","tags":["Conversation Read State"],"summary":"Get read state","description":"Return the read state for the current user in a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"}],"responses":{"200":{"description":"Read state","content":{"application/json":{"schema":{"type":"object","properties":{"last_read_message_id":{"type":["string","null"],"format":"uuid"},"unread_count":{"type":"integer","minimum":0}},"required":["last_read_message_id","unread_count"]}}}}}},"put":{"operationId":"updateReadState","tags":["Conversation Read State"],"summary":"Update read state","description":"Advances the read cursor for the current user and returns its effective persisted state. Older message markers do not move the cursor backward.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","format":"uuid"}},"required":["message_id"]}}}},"responses":{"200":{"description":"Updated read state","content":{"application/json":{"schema":{"type":"object","properties":{"last_read_message_id":{"type":["string","null"],"format":"uuid"},"unread_count":{"type":"integer","minimum":0}},"required":["last_read_message_id","unread_count"]}}}}}}},"/participants":{"get":{"operationId":"listParticipantIdentities","tags":["Participant lookup"],"summary":"List participant identities","description":"Return conversation participant identities for the specified user or agent IDs.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"agent","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"user","in":"query"}],"responses":{"200":{"description":"Participant identities","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"participant_type":{"type":"string","enum":["user","agent"]},"user_id":{"type":["string","null"],"format":"uuid"},"agent_id":{"type":["string","null"]},"project_id":{"type":["string","null"],"format":"uuid"},"display_name":{"type":["string","null"]}},"required":["id","participant_type"]}},"page_info":{"type":"object","properties":{"self":{"type":["string","null"]},"first":{"type":["string","null"]},"next":{"type":["string","null"]},"prev":{"type":["string","null"]}}}},"required":["data","page_info"]}}}}}}},"/projects/{project_reference}/schedules":{"get":{"operationId":"listProjectSchedules","tags":["Project schedules"],"summary":"List project schedules","description":"Lists recurring project schedules that trigger task, workflow, or agent runs.\n\n**Pagination:** `schedules` holds up to `limit` schedules (default 100). Pass `page_info.next` as `cursor` for the next page, with the same filters and sort. `source_schedules` and `diagnostics` are returned on the first page only.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["active","paused","deleting"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"source_trigger_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"},{"schema":{"type":"string","enum":["created_at","name"],"default":"created_at"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"string","format":"uuid","description":"The `page_info.next` of the previous page: the id of its last schedule. Keep the filters, `sort_by` and `sort_order` the same across pages. Only `schedules` is paged; `source_schedules` is listed on the first page only."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Project schedules","content":{"application/json":{"schema":{"type":"object","properties":{"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleting"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["task","workflow","agent"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"schedule":{"type":"string"},"timezone":{"type":"string"},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"The runtime target kind associated with this record."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"config":{"type":"object","additionalProperties":{}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"last_scheduled_at":{"type":["string","null"]},"last_successful_at":{"type":["string","null"]},"health":{"type":["object","null"],"properties":{"maxStalenessSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The max staleness seconds associated with this record."}},"required":["maxStalenessSeconds"],"additionalProperties":false,"description":"Structured health details associated with this record."},"max_runs":{"type":["integer","null"],"exclusiveMinimum":0},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":["string","null"]},"paused_reason":{"type":["string","null"]},"paused_at":{"type":["string","null"]},"last_failure_at":{"type":["string","null"]},"last_failure_code":{"type":["string","null"]},"last_failure_message":{"type":["string","null"]},"last_failure_run_id":{"type":["string","null"],"format":"uuid"},"created_by":{"type":["string","null"],"format":"uuid"},"integration_requirements":{"type":"array","items":{"type":"object","properties":{"integration":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"The integration associated with this record."},"required_scopes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255,"description":"One required scope item associated with this record."},"maxItems":50,"default":[],"description":"The required scopes associated with this record."},"resources":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."},"parent":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."}},"required":["kind","id"],"additionalProperties":false,"description":"The parent associated with this record."}},"required":["kind","id"],"additionalProperties":false,"description":"One resource item associated with this record."},"maxItems":50,"default":[],"description":"The resources associated with this record."}},"required":["integration"],"additionalProperties":false,"description":"One integration requirement item associated with this record."},"maxItems":20,"default":[],"description":"List of integration requirements associated with this record."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","status","target","schedule","timezone","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","config","timeout_seconds","backoff_limit","concurrency_policy","definition_source","source_trigger_id","source_path","source_hash","last_scheduled_at","last_successful_at","health","max_runs","run_count","completed_at","paused_reason","paused_at","last_failure_at","last_failure_code","last_failure_message","last_failure_run_id","created_by","created_at","updated_at"],"additionalProperties":false}},"page_info":{"$ref":"#/components/schemas/PageInfo"},"source_schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Unique identifier for the record."},"name":{"type":"string","description":"Human-readable name for the record."},"description":{"type":["string","null"],"description":"Human-readable description for the record."},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["task","workflow","agent"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"schedule":{"type":"string","description":"The schedule associated with this record."},"timezone":{"type":"string","description":"The timezone associated with this record."},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"The runtime target kind associated with this record."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid","description":"The runtime target environment id associated with this record."},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid","description":"The runtime target branch id associated with this record."},"config":{"type":"object","additionalProperties":{"description":"Additional structured values associated with this result."},"description":"Structured config details associated with this record."},"timeout_seconds":{"type":"integer","exclusiveMinimum":0,"description":"The timeout seconds associated with this record."},"backoff_limit":{"type":"integer","minimum":0,"description":"The backoff limit associated with this record."},"concurrency_policy":{"type":"string","description":"The concurrency policy associated with this record."},"max_runs":{"type":["integer","null"],"exclusiveMinimum":0,"description":"The max runs associated with this record."},"health":{"type":["object","null"],"properties":{"maxStalenessSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The max staleness seconds associated with this record."}},"required":["maxStalenessSeconds"],"additionalProperties":false,"description":"The health associated with this record."},"definition_source":{"type":"string","enum":["source"],"description":"The definition source associated with this record."},"source_trigger_id":{"type":"string","description":"The source trigger id associated with this record."},"source_path":{"type":"string","description":"The source path associated with this record."},"source_hash":{"type":"string","description":"The source hash associated with this record."},"edit_mode":{"type":"string","enum":["structured","source_only"],"description":"The edit mode associated with this record."}},"required":["id","name","description","target","schedule","timezone","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","config","timeout_seconds","backoff_limit","concurrency_policy","max_runs","health","definition_source","source_trigger_id","source_path","source_hash","edit_mode"],"additionalProperties":false,"description":"One source schedule item associated with this record."},"default":[]},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["schedules","page_info"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createProjectSchedule","tags":["Project schedules"],"summary":"Create project schedule","description":"Creates a recurring schedule. New schedules are active by default.\n\nIf a schedule with the same source trigger ID already exists, creating it from a source definition can return the existing schedule with its current status. A paused schedule remains paused.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["task","workflow","agent"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"schedule":{"type":"string","minLength":1,"maxLength":255},"timezone":{"type":"string","minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"The runtime target kind associated with this record."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"config":{"type":"object","additionalProperties":{}},"timeout_seconds":{"type":"integer","exclusiveMinimum":0},"backoff_limit":{"type":"integer","minimum":0},"concurrency_policy":{"type":"string","enum":["Allow","Forbid","Replace"]},"max_runs":{"type":["integer","null"],"exclusiveMinimum":0},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","minLength":1,"maxLength":255},"source_path":{"type":"string","minLength":1,"maxLength":1024},"source_hash":{"type":"string","minLength":1,"maxLength":255}},"required":["name","target","schedule"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created schedule","content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleting"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["task","workflow","agent"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"schedule":{"type":"string"},"timezone":{"type":"string"},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"The runtime target kind associated with this record."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"config":{"type":"object","additionalProperties":{}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"last_scheduled_at":{"type":["string","null"]},"last_successful_at":{"type":["string","null"]},"health":{"type":["object","null"],"properties":{"maxStalenessSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The max staleness seconds associated with this record."}},"required":["maxStalenessSeconds"],"additionalProperties":false,"description":"Structured health details associated with this record."},"max_runs":{"type":["integer","null"],"exclusiveMinimum":0},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":["string","null"]},"paused_reason":{"type":["string","null"]},"paused_at":{"type":["string","null"]},"last_failure_at":{"type":["string","null"]},"last_failure_code":{"type":["string","null"]},"last_failure_message":{"type":["string","null"]},"last_failure_run_id":{"type":["string","null"],"format":"uuid"},"created_by":{"type":["string","null"],"format":"uuid"},"integration_requirements":{"type":"array","items":{"type":"object","properties":{"integration":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"The integration associated with this record."},"required_scopes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255,"description":"One required scope item associated with this record."},"maxItems":50,"default":[],"description":"The required scopes associated with this record."},"resources":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."},"parent":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."}},"required":["kind","id"],"additionalProperties":false,"description":"The parent associated with this record."}},"required":["kind","id"],"additionalProperties":false,"description":"One resource item associated with this record."},"maxItems":50,"default":[],"description":"The resources associated with this record."}},"required":["integration"],"additionalProperties":false,"description":"One integration requirement item associated with this record."},"maxItems":20,"default":[],"description":"List of integration requirements associated with this record."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","status","target","schedule","timezone","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","config","timeout_seconds","backoff_limit","concurrency_policy","definition_source","source_trigger_id","source_path","source_hash","last_scheduled_at","last_successful_at","health","max_runs","run_count","completed_at","paused_reason","paused_at","last_failure_at","last_failure_code","last_failure_message","last_failure_run_id","created_by","created_at","updated_at"],"additionalProperties":false}},"required":["schedule"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/schedules/{schedule_id}":{"get":{"operationId":"getProjectSchedule","tags":["Project schedules"],"summary":"Get project schedule","description":"Return one project schedule.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"schedule_id","in":"path"}],"responses":{"200":{"description":"Project schedule","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleting"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["task","workflow","agent"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"schedule":{"type":"string"},"timezone":{"type":"string"},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"The runtime target kind associated with this record."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"config":{"type":"object","additionalProperties":{}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"last_scheduled_at":{"type":["string","null"]},"last_successful_at":{"type":["string","null"]},"health":{"type":["object","null"],"properties":{"maxStalenessSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The max staleness seconds associated with this record."}},"required":["maxStalenessSeconds"],"additionalProperties":false,"description":"Structured health details associated with this record."},"max_runs":{"type":["integer","null"],"exclusiveMinimum":0},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":["string","null"]},"paused_reason":{"type":["string","null"]},"paused_at":{"type":["string","null"]},"last_failure_at":{"type":["string","null"]},"last_failure_code":{"type":["string","null"]},"last_failure_message":{"type":["string","null"]},"last_failure_run_id":{"type":["string","null"],"format":"uuid"},"created_by":{"type":["string","null"],"format":"uuid"},"integration_requirements":{"type":"array","items":{"type":"object","properties":{"integration":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"The integration associated with this record."},"required_scopes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255,"description":"One required scope item associated with this record."},"maxItems":50,"default":[],"description":"The required scopes associated with this record."},"resources":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."},"parent":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."}},"required":["kind","id"],"additionalProperties":false,"description":"The parent associated with this record."}},"required":["kind","id"],"additionalProperties":false,"description":"One resource item associated with this record."},"maxItems":50,"default":[],"description":"The resources associated with this record."}},"required":["integration"],"additionalProperties":false,"description":"One integration requirement item associated with this record."},"maxItems":20,"default":[],"description":"List of integration requirements associated with this record."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","status","target","schedule","timezone","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","config","timeout_seconds","backoff_limit","concurrency_policy","definition_source","source_trigger_id","source_path","source_hash","last_scheduled_at","last_successful_at","health","max_runs","run_count","completed_at","paused_reason","paused_at","last_failure_at","last_failure_code","last_failure_message","last_failure_run_id","created_by","created_at","updated_at"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updateProjectSchedule","tags":["Project schedules"],"summary":"Update project schedule","description":"Update schedule metadata, timing, target, runtime target, or status.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"schedule_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["task","workflow","agent"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"Structured target details associated with this record."},"schedule":{"type":"string","minLength":1,"maxLength":255},"timezone":{"type":"string","minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"The runtime target kind associated with this record."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"config":{"type":"object","additionalProperties":{}},"timeout_seconds":{"type":"integer","exclusiveMinimum":0},"backoff_limit":{"type":"integer","minimum":0},"concurrency_policy":{"type":"string","enum":["Allow","Forbid","Replace"]},"max_runs":{"type":["integer","null"],"exclusiveMinimum":0},"status":{"type":"string","enum":["active","paused"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated schedule","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleting"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["task","workflow","agent"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"schedule":{"type":"string"},"timezone":{"type":"string"},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"The runtime target kind associated with this record."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"config":{"type":"object","additionalProperties":{}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"last_scheduled_at":{"type":["string","null"]},"last_successful_at":{"type":["string","null"]},"health":{"type":["object","null"],"properties":{"maxStalenessSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The max staleness seconds associated with this record."}},"required":["maxStalenessSeconds"],"additionalProperties":false,"description":"Structured health details associated with this record."},"max_runs":{"type":["integer","null"],"exclusiveMinimum":0},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":["string","null"]},"paused_reason":{"type":["string","null"]},"paused_at":{"type":["string","null"]},"last_failure_at":{"type":["string","null"]},"last_failure_code":{"type":["string","null"]},"last_failure_message":{"type":["string","null"]},"last_failure_run_id":{"type":["string","null"],"format":"uuid"},"created_by":{"type":["string","null"],"format":"uuid"},"integration_requirements":{"type":"array","items":{"type":"object","properties":{"integration":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"The integration associated with this record."},"required_scopes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255,"description":"One required scope item associated with this record."},"maxItems":50,"default":[],"description":"The required scopes associated with this record."},"resources":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."},"parent":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."}},"required":["kind","id"],"additionalProperties":false,"description":"The parent associated with this record."}},"required":["kind","id"],"additionalProperties":false,"description":"One resource item associated with this record."},"maxItems":50,"default":[],"description":"The resources associated with this record."}},"required":["integration"],"additionalProperties":false,"description":"One integration requirement item associated with this record."},"maxItems":20,"default":[],"description":"List of integration requirements associated with this record."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","status","target","schedule","timezone","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","config","timeout_seconds","backoff_limit","concurrency_policy","definition_source","source_trigger_id","source_path","source_hash","last_scheduled_at","last_successful_at","health","max_runs","run_count","completed_at","paused_reason","paused_at","last_failure_at","last_failure_code","last_failure_message","last_failure_run_id","created_by","created_at","updated_at"],"additionalProperties":false}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deleteProjectSchedule","tags":["Project schedules"],"summary":"Delete project schedule","description":"Marks a schedule as deleting after project run-write permission and token delete-scope checks so the scheduler operator can remove cloud recurrence resources.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"schedule_id","in":"path"}],"responses":{"200":{"description":"Deleted schedule","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"schedule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleting"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["task","workflow","agent"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"schedule":{"type":"string"},"timezone":{"type":"string"},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"The runtime target kind associated with this record."},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"config":{"type":"object","additionalProperties":{}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"last_scheduled_at":{"type":["string","null"]},"last_successful_at":{"type":["string","null"]},"health":{"type":["object","null"],"properties":{"maxStalenessSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The max staleness seconds associated with this record."}},"required":["maxStalenessSeconds"],"additionalProperties":false,"description":"Structured health details associated with this record."},"max_runs":{"type":["integer","null"],"exclusiveMinimum":0},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":["string","null"]},"paused_reason":{"type":["string","null"]},"paused_at":{"type":["string","null"]},"last_failure_at":{"type":["string","null"]},"last_failure_code":{"type":["string","null"]},"last_failure_message":{"type":["string","null"]},"last_failure_run_id":{"type":["string","null"],"format":"uuid"},"created_by":{"type":["string","null"],"format":"uuid"},"integration_requirements":{"type":"array","items":{"type":"object","properties":{"integration":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"The integration associated with this record."},"required_scopes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255,"description":"One required scope item associated with this record."},"maxItems":50,"default":[],"description":"The required scopes associated with this record."},"resources":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."},"parent":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":512,"description":"Unique identifier for the record."}},"required":["kind","id"],"additionalProperties":false,"description":"The parent associated with this record."}},"required":["kind","id"],"additionalProperties":false,"description":"One resource item associated with this record."},"maxItems":50,"default":[],"description":"The resources associated with this record."}},"required":["integration"],"additionalProperties":false,"description":"One integration requirement item associated with this record."},"maxItems":20,"default":[],"description":"List of integration requirements associated with this record."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","status","target","schedule","timezone","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","config","timeout_seconds","backoff_limit","concurrency_policy","definition_source","source_trigger_id","source_path","source_hash","last_scheduled_at","last_successful_at","health","max_runs","run_count","completed_at","paused_reason","paused_at","last_failure_at","last_failure_code","last_failure_message","last_failure_run_id","created_by","created_at","updated_at"],"additionalProperties":false}},"required":["ok","schedule"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/webhooks":{"get":{"operationId":"listProjectWebhooks","tags":["Project webhooks"],"summary":"List project webhooks","description":"Lists webhook definitions for project automation, newest first.\n\n**Pagination:** Without `limit` and `cursor` the response lists every webhook and `page_info.next` is null. Send `limit` to page, and pass `page_info.next` as `cursor` for the next page. `source_webhooks` and `diagnostics` are returned on the first page only.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum webhooks to return, from 1 to 100. Without `limit` and `cursor` the response lists every webhook; with a `cursor` alone, the page holds up to 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid","description":"The `page_info.next` of the previous page: the id of its last webhook. Keep `sort_order` the same across pages. Only `webhooks` is paged; `source_webhooks` is listed on the first page only."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Creation order: desc (newest first, the default) or asc."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Project webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["webhook"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","task","workflow","event"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"prompt_template":{"type":["string","null"]},"event_filter":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["all","any"]},"conditions":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":255},"operator":{"type":"string","enum":["equals","not_equals","in","exists","contains"]},"value":{}},"required":["path","operator"],"additionalProperties":false},"maxItems":50}},"required":["mode","conditions"],"additionalProperties":false},"status":{"type":"string","enum":["draft","enabled","disabled"]},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid"},"enabled_at":{"type":["string","null"]},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","source","target","prompt_template","event_filter","status","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","definition_source","source_trigger_id","source_path","source_hash","webhook_id","webhook_url","created_by_user_id","enabled_at","disabled_at","disabled_reason","created_at","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"},"source_webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Unique identifier for the record."},"name":{"type":"string","description":"Human-readable name for the record."},"description":{"type":["string","null"],"description":"Human-readable description for the record."},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","task","workflow","event"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"prompt_template":{"type":["string","null"],"description":"The prompt template associated with this record."},"event_filter":{"description":"The event filter associated with this record."},"definition_source":{"type":"string","enum":["source"],"description":"The definition source associated with this record."},"source_trigger_id":{"type":"string","description":"The source trigger id associated with this record."},"source_path":{"type":"string","description":"The source path associated with this record."},"source_hash":{"type":"string","description":"The source hash associated with this record."},"edit_mode":{"type":"string","enum":["structured","source_only"],"description":"The edit mode associated with this record."}},"required":["id","name","description","target","prompt_template","definition_source","source_trigger_id","source_path","source_hash","edit_mode"],"description":"One source webhook item associated with this record."}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["webhooks","page_info"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createProjectWebhook","tags":["Project webhooks"],"summary":"Create project webhook","description":"Create an enabled webhook definition and returns its secret once.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","task","workflow","event"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"prompt_template":{"type":"string","minLength":1,"maxLength":20000},"event_filter":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["all","any"]},"conditions":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":255},"operator":{"type":"string","enum":["equals","not_equals","in","exists","contains"]},"value":{}},"required":["path","operator"],"additionalProperties":false},"maxItems":50}},"required":["mode","conditions"],"additionalProperties":false}},"required":["name","target"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created webhook","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["webhook"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","task","workflow","event"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"prompt_template":{"type":["string","null"]},"event_filter":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["all","any"]},"conditions":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":255},"operator":{"type":"string","enum":["equals","not_equals","in","exists","contains"]},"value":{}},"required":["path","operator"],"additionalProperties":false},"maxItems":50}},"required":["mode","conditions"],"additionalProperties":false},"status":{"type":"string","enum":["draft","enabled","disabled"]},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid"},"enabled_at":{"type":["string","null"]},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","source","target","prompt_template","event_filter","status","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","definition_source","source_trigger_id","source_path","source_hash","webhook_id","webhook_url","created_by_user_id","enabled_at","disabled_at","disabled_reason","created_at","updated_at"]},"webhook_secret":{"type":"string"}},"required":["webhook","webhook_secret"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/webhooks/{webhook_definition_id}":{"get":{"operationId":"getProjectWebhook","tags":["Project webhooks"],"summary":"Get project webhook","description":"Return a single webhook definition for the resolved project.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"webhook_definition_id","in":"path"}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["webhook"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","task","workflow","event"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"prompt_template":{"type":["string","null"]},"event_filter":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["all","any"]},"conditions":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":255},"operator":{"type":"string","enum":["equals","not_equals","in","exists","contains"]},"value":{}},"required":["path","operator"],"additionalProperties":false},"maxItems":50}},"required":["mode","conditions"],"additionalProperties":false},"status":{"type":"string","enum":["draft","enabled","disabled"]},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid"},"enabled_at":{"type":["string","null"]},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","source","target","prompt_template","event_filter","status","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","definition_source","source_trigger_id","source_path","source_hash","webhook_id","webhook_url","created_by_user_id","enabled_at","disabled_at","disabled_reason","created_at","updated_at"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updateProjectWebhook","tags":["Project webhooks"],"summary":"Update project webhook","description":"Update webhook metadata or status.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"webhook_definition_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","task","workflow","event"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"Structured target details associated with this record."},"prompt_template":{"type":"string","minLength":1,"maxLength":20000},"event_filter":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["all","any"]},"conditions":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":255},"operator":{"type":"string","enum":["equals","not_equals","in","exists","contains"]},"value":{}},"required":["path","operator"],"additionalProperties":false},"maxItems":50}},"required":["mode","conditions"],"additionalProperties":false},"status":{"type":"string","enum":["draft","enabled","disabled"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated webhook","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["webhook"]},"target":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","task","workflow","event"],"description":"The kind associated with this record."},"id":{"type":"string","minLength":1,"maxLength":128,"description":"Unique identifier for the record."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"description":"Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."}},"required":["kind","id"],"additionalProperties":false,"description":"The target associated with this record."},"prompt_template":{"type":["string","null"]},"event_filter":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["all","any"]},"conditions":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":255},"operator":{"type":"string","enum":["equals","not_equals","in","exists","contains"]},"value":{}},"required":["path","operator"],"additionalProperties":false},"maxItems":50}},"required":["mode","conditions"],"additionalProperties":false},"status":{"type":"string","enum":["draft","enabled","disabled"]},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"runtime_target_environment_id":{"type":["string","null"],"format":"uuid"},"runtime_target_branch_id":{"type":["string","null"],"format":"uuid"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":["string","null"]},"source_path":{"type":["string","null"]},"source_hash":{"type":["string","null"]},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid"},"enabled_at":{"type":["string","null"]},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","source","target","prompt_template","event_filter","status","runtime_target_kind","runtime_target_environment_id","runtime_target_branch_id","definition_source","source_trigger_id","source_path","source_hash","webhook_id","webhook_url","created_by_user_id","enabled_at","disabled_at","disabled_reason","created_at","updated_at"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deleteProjectWebhook","tags":["Project webhooks"],"summary":"Delete project webhook","description":"Delete a project webhook definition and disables future webhook deliveries for it.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"webhook_definition_id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/webhooks/{webhook_definition_id}/events":{"get":{"operationId":"listProjectWebhookEvents","tags":["Project webhooks"],"summary":"List webhook delivery events","description":"Lists persisted webhook deliveries, including filtered deliveries without an execution. Use webhook_event_id with the replay operation. The optional run_id identifies an associated execution.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"webhook_definition_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum runs to return, from 1 to 100. Defaults to 50."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid","description":"The `page_info.next` of the previous page: the `webhook_event_id` of its last run. Keep `sort_order` the same across pages."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Creation order: desc (newest first, the default) or asc."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Webhook delivery events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryEventListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/webhooks/{webhook_definition_id}/events/{webhook_event_id}/replay":{"post":{"operationId":"replayProjectWebhookEvent","tags":["Project webhooks"],"summary":"Replay project webhook event","description":"Create a new webhook event from a stored event payload and runs it through the webhook target.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"webhook_definition_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"webhook_event_id","in":"path"}],"responses":{"202":{"description":"Webhook event replay accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRun"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/webhooks/{webhook_id}":{"post":{"operationId":"receiveWebhook","tags":["Webhook delivery"],"summary":"Receive webhook","description":"Public webhook ingress for enabled webhook definitions. Authenticate with the X-Veryfront-Webhook-Secret header; include an optional Idempotency-Key header for duplicate delivery detection. For native GitHub repository webhooks, use a ?secret= query param and GitHub supplies the idempotency key via its X-GitHub-Delivery header.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"webhook_id","in":"path"}],"responses":{"200":{"description":"Duplicate webhook delivery accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRun"}}}},"202":{"description":"Webhook accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRun"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Dedupe conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-audience":"component-internal"}},"/agent-runtimes/projects/{project_reference}/targets":{"get":{"operationId":"listProjectAgentRuntimeTargets","tags":["Agent runtime registration"],"summary":"List project agent runtime targets","description":"Lists project-scoped push runtime services and pull workers through one runtime-target view. Requires project.runtime.manage.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Agent runtime targets for the project","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"service_name":{"type":"string","minLength":1,"maxLength":128},"service_key":{"type":"string","minLength":1,"maxLength":128},"scope_kind":{"type":"string","enum":["global","project"]},"scope_key":{"type":"string","minLength":1},"project_id":{"type":["string","null"],"format":"uuid"},"agent_id":{"type":["string","null"]},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{},"metadata":{},"managed_source":{"type":["object","null"],"properties":{"project_id":{"type":"string","format":"uuid"},"environment_id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"}},"required":["project_id","environment_id","release_id"],"additionalProperties":false},"version":{"type":["string","null"]},"runtime":{"type":["string","null"]},"region":{"type":["string","null"]},"last_heartbeat_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","enum":["registered_push_service"]},"mode":{"type":"string","enum":["push"]},"source":{"type":"string","enum":["runtime_service_registry"]},"connection_status":{"type":"string","enum":["online","offline","disabled"]}},"required":["id","service_name","service_key","scope_kind","scope_key","project_id","agent_id","base_url","invoke_url","status","managed_source","version","runtime","region","last_heartbeat_at","created_at","updated_at","kind","mode","source","connection_status"],"title":"RegisteredPushServiceTarget"},{"type":"object","properties":{"kind":{"type":"string","enum":["pull_worker"]},"mode":{"type":"string","enum":["pull"]},"source":{"type":"string","enum":["agent_worker_registry"]},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"worker_key":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"The worker key associated with this tool result."},"display_name":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"]},"metadata":{},"last_heartbeat_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["kind","mode","source","id","project_id","implementation_kind","worker_key","display_name","status","connection_status","last_heartbeat_at","created_at","updated_at"],"title":"PullWorkerTarget"}]}}},"required":["data"]}}}}},"x-audience":"component-internal"}},"/agent-runtimes/push-services":{"get":{"operationId":"listGlobalAgentPushRuntimeServices","tags":["Agent runtime registration"],"summary":"List global agent push runtime services","description":"Lists globally registered push-based agent runtime services for operational visibility. Requires platform administrator access.","responses":{"200":{"description":"Global agent push runtime services","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"service_name":{"type":"string","minLength":1,"maxLength":128},"service_key":{"type":"string","minLength":1,"maxLength":128},"scope_kind":{"type":"string","enum":["global","project"]},"scope_key":{"type":"string","minLength":1},"project_id":{"type":["string","null"],"format":"uuid"},"agent_id":{"type":["string","null"]},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{},"metadata":{},"managed_source":{"type":["object","null"],"properties":{"project_id":{"type":"string","format":"uuid"},"environment_id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"}},"required":["project_id","environment_id","release_id"],"additionalProperties":false},"version":{"type":["string","null"]},"runtime":{"type":["string","null"]},"region":{"type":["string","null"]},"last_heartbeat_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","enum":["registered_push_service"]},"mode":{"type":"string","enum":["push"]},"source":{"type":"string","enum":["runtime_service_registry"]},"connection_status":{"type":"string","enum":["online","offline","disabled"]}},"required":["id","service_name","service_key","scope_kind","scope_key","project_id","agent_id","base_url","invoke_url","status","managed_source","version","runtime","region","last_heartbeat_at","created_at","updated_at","kind","mode","source","connection_status"],"title":"RegisteredPushServiceTarget"},{"type":"object","properties":{"kind":{"type":"string","enum":["pull_worker"]},"mode":{"type":"string","enum":["pull"]},"source":{"type":"string","enum":["agent_worker_registry"]},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"worker_key":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"The worker key associated with this tool result."},"display_name":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"]},"metadata":{},"last_heartbeat_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["kind","mode","source","id","project_id","implementation_kind","worker_key","display_name","status","connection_status","last_heartbeat_at","created_at","updated_at"],"title":"PullWorkerTarget"}]}}},"required":["data"]}}}}},"x-audience":"component-internal"},"post":{"operationId":"registerAgentPushRuntimeService","tags":["Agent runtime registration"],"summary":"Register an agent push runtime service","description":"Registers or refreshes a push-based agent runtime service endpoint. Project-scoped registrations require project.runtime.manage; global registrations require platform administrator access.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"service_name":{"type":"string","minLength":1,"maxLength":128},"service_key":{"type":"string","minLength":1,"maxLength":128},"scope_kind":{"type":"string","enum":["global","project"],"default":"global"},"project_reference":{"type":["string","null"]},"project_id":{"type":["string","null"],"description":"Deprecated project ID or slug alias. Use project_reference."},"projectId":{"type":["string","null"],"description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"agent_id":{"type":["string","null"],"minLength":1,"maxLength":128},"base_url":{"type":"string","format":"uri"},"managed_source":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"environment_id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"}},"required":["project_id","environment_id","release_id"],"additionalProperties":false},"invoke_url":{"type":"string","format":"uri"},"capabilities":{"type":["object","null"],"additionalProperties":{}},"metadata":{"type":["object","null"],"additionalProperties":{}},"version":{"type":["string","null"],"minLength":1,"maxLength":128},"runtime":{"type":["string","null"],"minLength":1,"maxLength":128},"region":{"type":["string","null"],"minLength":1,"maxLength":128}},"required":["service_name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Agent push runtime service registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPushRuntimeServiceResponse"}}}}},"x-audience":"component-internal"}},"/agent-runtimes/push-services/{service_id}/drain":{"post":{"operationId":"drainAgentPushRuntimeService","tags":["Agent runtime registration"],"summary":"Drain an agent push runtime service","description":"Disables runtime selection. For a managed source connection this also revokes queued and child dispatch; either project may revoke.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"service_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Agent push runtime service drain accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPushRuntimeServiceResponse"}}}}},"x-audience":"component-internal"}},"/agent-runtimes/push-services/{service_id}/heartbeat":{"post":{"operationId":"heartbeatAgentPushRuntimeService","tags":["Agent runtime registration"],"summary":"Heartbeat an agent push runtime service","description":"Refreshes the liveness timestamp for an existing push runtime service after verifying access to its global or project scope.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"service_id","in":"path"}],"requestBody":{"description":"A required, strictly empty JSON object -- heartbeats carry no fields.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Agent push runtime service heartbeat accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPushRuntimeServiceResponse"}}}}},"x-audience":"component-internal"}},"/agent-runtimes/push-services/{service_id}/resume":{"post":{"operationId":"resumeAgentPushRuntimeService","tags":["Agent runtime registration"],"summary":"Resume an agent push runtime service","description":"Re-enables runtime selection. Managed source connections require project.runtime.manage in both projects.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"service_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Agent push runtime service resume accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPushRuntimeServiceResponse"}}}}},"x-audience":"component-internal"}},"/agent-workers/projects/{project_reference}/workers":{"get":{"operationId":"listConnectedAgentWorkers","tags":["Agent workers"],"summary":"List agent workers","description":"List project agent workers, including disabled or offline workers.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of agent workers to return per page","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned in page_info.next to fetch the next page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Project agent workers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"worker_key":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"The worker key associated with this tool result."},"display_name":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"],"description":"The connection status associated with this tool result."},"metadata":{},"last_heartbeat_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","implementation_kind","worker_key","display_name","status","connection_status","last_heartbeat_at","created_at","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}}},"x-audience":"component-internal"},"post":{"operationId":"registerAgentWorker","tags":["Agent workers"],"summary":"Register an agent worker","description":"Registers a worker that can claim and execute runs for a project.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"implementation_display_name":{"type":"string","minLength":1,"maxLength":128},"worker_key":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"The worker key associated with this tool result."},"display_name":{"type":["string","null"],"minLength":1,"maxLength":128},"metadata":{"type":["object","null"],"additionalProperties":{}}},"required":["implementation_kind","worker_key"],"additionalProperties":false}}}},"responses":{"201":{"description":"Agent worker registered","content":{"application/json":{"schema":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"worker_key":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"The worker key associated with this tool result."},"display_name":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"],"description":"The connection status associated with this tool result."},"metadata":{},"last_heartbeat_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","implementation_kind","worker_key","display_name","status","connection_status","last_heartbeat_at","created_at","updated_at"]},"token":{"type":["string","null"]}},"required":["worker"]}}}}},"x-audience":"component-internal"}},"/agent-workers/workers/{worker_id}":{"delete":{"operationId":"disableAgentWorker","tags":["Agent workers"],"summary":"Disable an agent worker","description":"Disables an agent worker so it stops claiming additional runs for its project.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"worker_id","in":"path"}],"responses":{"204":{"description":"Agent worker disabled"}},"x-audience":"component-internal"}},"/agent-workers/workers/{worker_id}/claim":{"post":{"operationId":"claimNextAgentRun","tags":["Agent workers"],"summary":"Claim the next runnable agent run","description":"Claims the next runnable agent run for a worker and returns lease metadata when work is available.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"worker_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lease_duration_seconds":{"type":"integer","minimum":5,"maximum":300}},"additionalProperties":false}}}},"responses":{"200":{"description":"Claim result","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":["object","null"],"properties":{"run_id":{"type":"string","minLength":1},"canonical_run_id":{"type":["string","null"],"format":"uuid","description":"Canonical Run identifier for Runs event and lifecycle operations; null when no canonical run exists."},"conversation_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"project_id":{"type":["string","null"],"format":"uuid"},"agent_id":{"type":"string","minLength":1},"status":{"type":"string","enum":["pending","running","waiting_for_tool","completed","failed","cancelled"]},"source_target_kind":{"type":["string","null"],"enum":["project","main_branch","environment","preview_branch","release",null]},"source_target_environment_id":{"type":["string","null"],"format":"uuid"},"source_target_branch_id":{"type":["string","null"],"format":"uuid"},"source_target_release_version":{"type":["string","null"],"minLength":1,"maxLength":128},"request_snapshot":{"type":["object","null"],"properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"role":{"type":"string","minLength":1},"parts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1}},"required":["type"]},"default":[]},"metadata":{"type":"object","additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","role"]}},"taskId":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]*$","description":"Provide the task id."},"agentServiceId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]*$"},"agentSource":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["branch"]},"branch":{"type":"string","minLength":1,"maxLength":255}},"required":["type","branch"]},{"type":"object","properties":{"type":{"type":"string","enum":["environment"]},"environmentName":{"type":"string","minLength":1,"maxLength":255},"releaseId":{"type":"string","minLength":1,"maxLength":255}},"required":["type","environmentName","releaseId"]},{"type":"object","properties":{"type":{"type":"string","enum":["release"]},"releaseId":{"type":"string","minLength":1,"maxLength":255}},"required":["type","releaseId"]}]},"managedRuntimeSource":{"type":"object","properties":{"serviceId":{"type":"string","format":"uuid"},"sourceBinding":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"releaseId":{"type":"string","format":"uuid"}},"required":["projectId","environmentId","releaseId"],"additionalProperties":false},"sourceProject":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"projectSlug":{"type":"string","minLength":1,"maxLength":255},"runtimeTargetKind":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"runtimeTargetEnvironmentId":{"type":["string","null"],"format":"uuid"},"runtimeTargetEnvironmentName":{"type":"string","minLength":1,"maxLength":255},"runtimeTargetBranchName":{"type":"string","minLength":1,"maxLength":255},"executionEnvironmentId":{"type":"string","format":"uuid"},"runtimeTargetBranchId":{"type":["string","null"],"format":"uuid"}},"required":["projectId","projectSlug"]},"agentSource":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["branch"]},"branch":{"type":"string","minLength":1,"maxLength":255}},"required":["type","branch"]},{"type":"object","properties":{"type":{"type":"string","enum":["environment"]},"environmentName":{"type":"string","minLength":1,"maxLength":255},"releaseId":{"type":"string","minLength":1,"maxLength":255}},"required":["type","environmentName","releaseId"]},{"type":"object","properties":{"type":{"type":"string","enum":["release"]},"releaseId":{"type":"string","minLength":1,"maxLength":255}},"required":["type","releaseId"]}]}},"required":["serviceId","sourceBinding","sourceProject","agentSource"],"additionalProperties":false},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z][a-zA-Z0-9._:-]*$"},"description":{"type":"string","maxLength":1024},"parameters":{"type":"object","additionalProperties":{}},"inputSchema":{"type":"object","additionalProperties":{}},"outputSchema":{"type":"object","additionalProperties":{}}},"required":["name"]},"default":[]},"context":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"title":{"type":"string","maxLength":256},"text":{"type":"string","maxLength":16384}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["json"]},"title":{"type":"string","maxLength":256},"data":{"type":"object","additionalProperties":{}}},"required":["type","data"]},{"type":"object","properties":{"type":{"type":"string","enum":["resource"]},"title":{"type":"string","maxLength":256},"uri":{"type":"string","maxLength":2048},"mimeType":{"type":"string","maxLength":256},"text":{"type":"string","maxLength":16384}},"required":["type","uri"]}]},"default":[]},"allowDelegation":{"type":"boolean"},"agentConfig":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":256},"description":{"type":"string","maxLength":1024,"default":""},"instructions":{"type":"string","minLength":1,"maxLength":64000},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budgetTokens":{"type":"number","exclusiveMinimum":0}},"required":["enabled"],"additionalProperties":false},"model":{"type":"string","minLength":1,"maxLength":256},"temperature":{"type":"number","minimum":0,"maximum":2},"maxSteps":{"type":"integer","exclusiveMinimum":0},"providerTools":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500},"skills":{"anyOf":[{"type":"boolean","enum":[true]},{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500}]},"tools":{"anyOf":[{"type":"boolean","enum":[true]},{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500}]},"deniedTools":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500},"delegates":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500}},"required":["id","name","instructions"]},"forwardedProps":{"type":"object","additionalProperties":{}},"integrationConnectionBindings":{"type":"array","items":{"anyOf":[{"oneOf":[{"type":"object","properties":{"integration":{"type":"string","minLength":1},"kind":{"type":"string","enum":["oauth"]},"source":{"type":"string","enum":["project_policy","user_config"]},"connectionId":{"type":"string","format":"uuid"},"connectionGenerationId":{"type":"string","format":"uuid"},"policyGenerationId":{"type":["string","null"],"format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["user"]},"ownerKind":{"type":"string","enum":["user"]}},"required":["integration","connectionId","connectionGenerationId","ownerId","scope","ownerKind"]},{"type":"object","properties":{"integration":{"type":"string","minLength":1},"kind":{"type":"string","enum":["oauth"]},"source":{"type":"string","enum":["project_policy","user_config"]},"connectionId":{"type":"string","format":"uuid"},"connectionGenerationId":{"type":"string","format":"uuid"},"policyGenerationId":{"type":["string","null"],"format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["project"]},"ownerKind":{"type":"string","enum":["project"]}},"required":["integration","connectionId","connectionGenerationId","ownerId","scope","ownerKind"]}]},{"type":"object","properties":{"kind":{"type":"string","enum":["service_identity"]},"integration":{"type":"string","enum":["github","jira","salesforce"]},"ownerKind":{"type":"string","enum":["project"]},"ownerId":{"type":"string","format":"uuid"},"targetEnvironmentId":{"type":["string","null"],"minLength":1},"policyGenerationId":{"type":["string","null"],"format":"uuid"}},"required":["kind","integration","ownerKind","ownerId","targetEnvironmentId"],"additionalProperties":false}]},"maxItems":128,"default":[]},"traceContext":{"type":"object","properties":{"traceId":{"type":"string","pattern":"^[0-9a-f]{32}$"},"spanId":{"type":"string","pattern":"^[0-9a-f]{16}$"},"traceFlags":{"type":"integer","minimum":0,"maximum":255}},"required":["traceId","spanId","traceFlags"]},"triggerPrincipal":{"type":"object","properties":{"type":{"type":"string","enum":["system","user","api_key","service_account"]},"id":{"type":"string","minLength":1,"maxLength":255}},"required":["type","id"],"additionalProperties":false},"authorization":{"type":"object","additionalProperties":{}}},"required":["messages","agentSource"]},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"lease_owner":{"type":["string","null"]},"lease_expires_at":{"type":["string","null"]},"effective_deadline_at":{"type":"string","format":"date-time"},"worker_session":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"run_id":{"type":"string","minLength":1},"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"worker_id":{"type":["string","null"],"format":"uuid"},"session_key":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","completed","failed","cancelled"]},"metadata":{},"created_at":{"type":"string"},"updated_at":{"type":"string"},"ended_at":{"type":["string","null"]}},"required":["id","run_id","implementation_kind","worker_id","session_key","status","created_at","updated_at","ended_at"]}},"required":["run_id","conversation_id","message_id","project_id","agent_id","status","request_snapshot","latest_event_id","latest_external_event_sequence","lease_owner","lease_expires_at","worker_session"]},"credentials":{"type":"object","properties":{"auth_token":{"type":"string","minLength":1},"run_event_token":{"type":"string","minLength":1},"run_terminal_token":{"type":"string","minLength":1}},"required":["auth_token","run_event_token","run_terminal_token"]}},"required":["run"]}}}}},"x-audience":"component-internal"}},"/agent-workers/workers/{worker_id}/heartbeat":{"post":{"operationId":"heartbeatAgentWorker","tags":["Agent workers"],"summary":"Heartbeat an agent worker","description":"Refreshes the liveness timestamp for an existing agent worker after verifying project access.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"worker_id","in":"path"}],"responses":{"200":{"description":"Agent worker heartbeat accepted","content":{"application/json":{"schema":{"type":"object","properties":{"worker":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"worker_key":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"The worker key associated with this tool result."},"display_name":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"],"description":"The connection status associated with this tool result."},"metadata":{},"last_heartbeat_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","implementation_kind","worker_key","display_name","status","connection_status","last_heartbeat_at","created_at","updated_at"]},"token":{"type":["string","null"]}},"required":["worker"]}}}}},"x-audience":"component-internal"}},"/agent-workers/workers/{worker_id}/runs/{run_id}/lease":{"post":{"operationId":"renewAgentRunLease","tags":["Agent workers"],"summary":"Renew a claimed agent run lease","description":"Extends the active lease for a worker-owned run while the agent worker continues processing it.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"worker_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"run_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lease_duration_seconds":{"type":"integer","minimum":5,"maximum":300}},"additionalProperties":false}}}},"responses":{"200":{"description":"Lease renewal result","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":["object","null"],"properties":{"run_id":{"type":"string","minLength":1},"canonical_run_id":{"type":["string","null"],"format":"uuid","description":"Canonical Run identifier for Runs event and lifecycle operations; null when no canonical run exists."},"conversation_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"project_id":{"type":["string","null"],"format":"uuid"},"agent_id":{"type":"string","minLength":1},"status":{"type":"string","enum":["pending","running","waiting_for_tool","completed","failed","cancelled"]},"source_target_kind":{"type":["string","null"],"enum":["project","main_branch","environment","preview_branch","release",null]},"source_target_environment_id":{"type":["string","null"],"format":"uuid"},"source_target_branch_id":{"type":["string","null"],"format":"uuid"},"source_target_release_version":{"type":["string","null"],"minLength":1,"maxLength":128},"request_snapshot":{"type":["object","null"],"properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"role":{"type":"string","minLength":1},"parts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1}},"required":["type"]},"default":[]},"metadata":{"type":"object","additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","role"]}},"taskId":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]*$","description":"Provide the task id."},"agentServiceId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]*$"},"agentSource":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["branch"]},"branch":{"type":"string","minLength":1,"maxLength":255}},"required":["type","branch"]},{"type":"object","properties":{"type":{"type":"string","enum":["environment"]},"environmentName":{"type":"string","minLength":1,"maxLength":255},"releaseId":{"type":"string","minLength":1,"maxLength":255}},"required":["type","environmentName","releaseId"]},{"type":"object","properties":{"type":{"type":"string","enum":["release"]},"releaseId":{"type":"string","minLength":1,"maxLength":255}},"required":["type","releaseId"]}]},"managedRuntimeSource":{"type":"object","properties":{"serviceId":{"type":"string","format":"uuid"},"sourceBinding":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"releaseId":{"type":"string","format":"uuid"}},"required":["projectId","environmentId","releaseId"],"additionalProperties":false},"sourceProject":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"projectSlug":{"type":"string","minLength":1,"maxLength":255},"runtimeTargetKind":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"runtimeTargetEnvironmentId":{"type":["string","null"],"format":"uuid"},"runtimeTargetEnvironmentName":{"type":"string","minLength":1,"maxLength":255},"runtimeTargetBranchName":{"type":"string","minLength":1,"maxLength":255},"executionEnvironmentId":{"type":"string","format":"uuid"},"runtimeTargetBranchId":{"type":["string","null"],"format":"uuid"}},"required":["projectId","projectSlug"]},"agentSource":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["branch"]},"branch":{"type":"string","minLength":1,"maxLength":255}},"required":["type","branch"]},{"type":"object","properties":{"type":{"type":"string","enum":["environment"]},"environmentName":{"type":"string","minLength":1,"maxLength":255},"releaseId":{"type":"string","minLength":1,"maxLength":255}},"required":["type","environmentName","releaseId"]},{"type":"object","properties":{"type":{"type":"string","enum":["release"]},"releaseId":{"type":"string","minLength":1,"maxLength":255}},"required":["type","releaseId"]}]}},"required":["serviceId","sourceBinding","sourceProject","agentSource"],"additionalProperties":false},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z][a-zA-Z0-9._:-]*$"},"description":{"type":"string","maxLength":1024},"parameters":{"type":"object","additionalProperties":{}},"inputSchema":{"type":"object","additionalProperties":{}},"outputSchema":{"type":"object","additionalProperties":{}}},"required":["name"]},"default":[]},"context":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"title":{"type":"string","maxLength":256},"text":{"type":"string","maxLength":16384}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["json"]},"title":{"type":"string","maxLength":256},"data":{"type":"object","additionalProperties":{}}},"required":["type","data"]},{"type":"object","properties":{"type":{"type":"string","enum":["resource"]},"title":{"type":"string","maxLength":256},"uri":{"type":"string","maxLength":2048},"mimeType":{"type":"string","maxLength":256},"text":{"type":"string","maxLength":16384}},"required":["type","uri"]}]},"default":[]},"allowDelegation":{"type":"boolean"},"agentConfig":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":256},"description":{"type":"string","maxLength":1024,"default":""},"instructions":{"type":"string","minLength":1,"maxLength":64000},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budgetTokens":{"type":"number","exclusiveMinimum":0}},"required":["enabled"],"additionalProperties":false},"model":{"type":"string","minLength":1,"maxLength":256},"temperature":{"type":"number","minimum":0,"maximum":2},"maxSteps":{"type":"integer","exclusiveMinimum":0},"providerTools":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500},"skills":{"anyOf":[{"type":"boolean","enum":[true]},{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500}]},"tools":{"anyOf":[{"type":"boolean","enum":[true]},{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500}]},"deniedTools":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500},"delegates":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500}},"required":["id","name","instructions"]},"forwardedProps":{"type":"object","additionalProperties":{}},"integrationConnectionBindings":{"type":"array","items":{"anyOf":[{"oneOf":[{"type":"object","properties":{"integration":{"type":"string","minLength":1},"kind":{"type":"string","enum":["oauth"]},"source":{"type":"string","enum":["project_policy","user_config"]},"connectionId":{"type":"string","format":"uuid"},"connectionGenerationId":{"type":"string","format":"uuid"},"policyGenerationId":{"type":["string","null"],"format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["user"]},"ownerKind":{"type":"string","enum":["user"]}},"required":["integration","connectionId","connectionGenerationId","ownerId","scope","ownerKind"]},{"type":"object","properties":{"integration":{"type":"string","minLength":1},"kind":{"type":"string","enum":["oauth"]},"source":{"type":"string","enum":["project_policy","user_config"]},"connectionId":{"type":"string","format":"uuid"},"connectionGenerationId":{"type":"string","format":"uuid"},"policyGenerationId":{"type":["string","null"],"format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["project"]},"ownerKind":{"type":"string","enum":["project"]}},"required":["integration","connectionId","connectionGenerationId","ownerId","scope","ownerKind"]}]},{"type":"object","properties":{"kind":{"type":"string","enum":["service_identity"]},"integration":{"type":"string","enum":["github","jira","salesforce"]},"ownerKind":{"type":"string","enum":["project"]},"ownerId":{"type":"string","format":"uuid"},"targetEnvironmentId":{"type":["string","null"],"minLength":1},"policyGenerationId":{"type":["string","null"],"format":"uuid"}},"required":["kind","integration","ownerKind","ownerId","targetEnvironmentId"],"additionalProperties":false}]},"maxItems":128,"default":[]},"traceContext":{"type":"object","properties":{"traceId":{"type":"string","pattern":"^[0-9a-f]{32}$"},"spanId":{"type":"string","pattern":"^[0-9a-f]{16}$"},"traceFlags":{"type":"integer","minimum":0,"maximum":255}},"required":["traceId","spanId","traceFlags"]},"triggerPrincipal":{"type":"object","properties":{"type":{"type":"string","enum":["system","user","api_key","service_account"]},"id":{"type":"string","minLength":1,"maxLength":255}},"required":["type","id"],"additionalProperties":false},"authorization":{"type":"object","additionalProperties":{}}},"required":["messages","agentSource"]},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"lease_owner":{"type":["string","null"]},"lease_expires_at":{"type":["string","null"]},"effective_deadline_at":{"type":"string","format":"date-time"},"worker_session":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"run_id":{"type":"string","minLength":1},"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"worker_id":{"type":["string","null"],"format":"uuid"},"session_key":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","completed","failed","cancelled"]},"metadata":{},"created_at":{"type":"string"},"updated_at":{"type":"string"},"ended_at":{"type":["string","null"]}},"required":["id","run_id","implementation_kind","worker_id","session_key","status","created_at","updated_at","ended_at"]}},"required":["run_id","conversation_id","message_id","project_id","agent_id","status","request_snapshot","latest_event_id","latest_external_event_sequence","lease_owner","lease_expires_at","worker_session"]},"credentials":{"type":"object","properties":{"auth_token":{"type":"string","minLength":1},"run_event_token":{"type":"string","minLength":1},"run_terminal_token":{"type":"string","minLength":1}},"required":["auth_token","run_event_token","run_terminal_token"]}},"required":["run"]}}}}},"x-audience":"component-internal"}},"/agent-workers/workers/{worker_id}/runs/{run_id}/session":{"put":{"operationId":"recordAgentWorkerRunSession","tags":["Agent workers"],"summary":"Record agent worker session state for a run","description":"Create or updates agent worker session metadata for a worker-owned run.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"worker_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"run_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"session_key":{"type":"string","minLength":1,"maxLength":512},"status":{"type":"string","enum":["active","completed","failed","cancelled"]},"metadata":{"type":["object","null"],"additionalProperties":{}}},"required":["session_key"],"additionalProperties":false}}}},"responses":{"200":{"description":"Agent worker session recorded","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"run_id":{"type":"string","minLength":1},"implementation_kind":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$","description":"The implementation kind associated with this tool result."},"worker_id":{"type":["string","null"],"format":"uuid"},"session_key":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","completed","failed","cancelled"]},"metadata":{},"created_at":{"type":"string"},"updated_at":{"type":"string"},"ended_at":{"type":["string","null"]}},"required":["id","run_id","implementation_kind","worker_id","session_key","status","created_at","updated_at","ended_at"]}},"required":["session"]}}}}},"x-audience":"component-internal"}},"/projects/{project_reference}/evals":{"get":{"operationId":"listEvals","tags":["Evaluation Definitions"],"summary":"List evaluations","description":"List source-backed evaluation definitions from the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Project eval source documents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EvalSourceDocument"}},"errors":{"type":"array","items":{"type":"object","properties":{"filePath":{"type":"string"},"error":{"type":"string"}},"required":["filePath","error"]}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["source_file_diagnostic","source_agent_discovery_error","source_trigger_discovery_error"]},"source_kind":{"type":"string","enum":["agent","prompt","tool","task","workflow","resource","skill","eval","schedule","webhook"]},"source_path":{"type":"string","minLength":1},"source_id":{"type":"string","minLength":1},"code":{"type":"string","enum":["parse_error","invalid_definition","dynamic_definition","duplicate_source_id","unsupported_target","manual_conflict"]},"message":{"type":"string","minLength":1},"details":{"type":"object","additionalProperties":{}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"post":{"operationId":"createEval","tags":["Evaluation Definitions"],"summary":"Create evaluation","description":"Create a structured evaluation source document in the selected source target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["eval-source-create"]},"fields":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"},"target":{"type":"string","minLength":1},"dataset":{"type":"object","properties":{"kind":{"type":"string","enum":["inline","json","jsonl","dynamic"]},"path":{"type":"string"},"examples":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"input":{},"reference":{},"metadata":{"type":"object","additionalProperties":{}}},"required":["id"]}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["kind","editable","dynamic"]},"repetitions":{"type":"integer","exclusiveMinimum":0,"default":1},"tags":{"type":"array","items":{"type":"string"},"default":[]},"metadata":{"type":"object","additionalProperties":{},"default":{}},"metrics":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"family":{"type":"string","enum":["answer","agent","ops","judge","knowledge","check"]},"severity":{"type":"string","enum":["gate","soft","budget"]},"threshold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"config":{"type":"object","additionalProperties":{}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["name","family","severity","editable","dynamic"]},"default":[]}},"required":["name","target","dataset"]}},"required":["kind","fields"]}}}},"responses":{"201":{"description":"Created eval source document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSourceDocument"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/projects/{project_reference}/evals/{eval_id}/source":{"get":{"operationId":"getEvalSource","tags":["Evaluation Definitions"],"summary":"Get evaluation source","description":"Return an evaluation source document and editable source content.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1},"required":true,"name":"eval_id","in":"path"},{"schema":{"type":["string","null"],"enum":["main_branch","environment","preview_branch",null],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target environment id."},"required":false,"description":"Provide the target environment id.","name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid","description":"Provide the target branch id."},"required":false,"description":"Provide the target branch id.","name":"target_branch_id","in":"query"},{"schema":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"required":false,"description":"Provide the source target kind.","name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Eval source document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSourceDocument"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}},"patch":{"operationId":"updateEvalSource","tags":["Evaluation Definitions"],"summary":"Update evaluation source","description":"Update a structured evaluation source document.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1},"required":true,"name":"eval_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["eval-source-patch"]},"id":{"type":"string"},"source":{"type":"object","properties":{"filePath":{"type":"string"},"exportName":{"type":"string"},"content":{"type":"string"}},"required":["filePath","exportName"]},"fields":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"},"target":{"type":"string","minLength":1},"dataset":{"type":"object","properties":{"kind":{"type":"string","enum":["inline","json","jsonl","dynamic"]},"path":{"type":"string"},"examples":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"input":{},"reference":{},"metadata":{"type":"object","additionalProperties":{}}},"required":["id"]}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["kind","editable","dynamic"]},"repetitions":{"type":"integer","exclusiveMinimum":0},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{}},"metrics":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"family":{"type":"string","enum":["answer","agent","ops","judge","knowledge","check"]},"severity":{"type":"string","enum":["gate","soft","budget"]},"threshold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"config":{"type":"object","additionalProperties":{}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["name","family","severity","editable","dynamic"]}}}}},"required":["kind","id","source","fields"]}}}},"responses":{"200":{"description":"Updated eval source document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSourceDocument"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePrimitiveErrorEnvelope"}}}}}}},"/internal/application-agui-inference/admissions":{"post":{"operationId":"admitInternalApplicationAguiInference","tags":["Application Inference"],"security":[{"hostBasicAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","format":"uuid"},"projectSlug":{"type":"string","minLength":1,"maxLength":255},"environmentName":{"type":"string","minLength":1,"maxLength":255},"releaseId":{"type":"string","format":"uuid"},"routePath":{"type":"string","maxLength":2048},"requestId":{"type":"string","minLength":1,"maxLength":255},"agentId":{"type":"string","minLength":1,"maxLength":255},"inferencePublicKey":{"type":"string","minLength":60,"maxLength":60,"pattern":"^[A-Za-z0-9+/]+={0,2}$"}},"required":["projectId","projectSlug","environmentName","releaseId","routePath","requestId","agentId","inferencePublicKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"Private run-bound inference admission","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"encryptedInferenceToken":{"type":"object","properties":{"ephemeralPublicKey":{"type":"string","minLength":1},"iv":{"type":"string","minLength":1},"tag":{"type":"string","minLength":1},"ciphertext":{"type":"string","minLength":1}},"required":["ephemeralPublicKey","iv","tag","ciphertext"],"additionalProperties":false}},"required":["runId","expiresAt","encryptedInferenceToken"],"additionalProperties":false}}}},"400":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid internal host Basic credentials","headers":{"WWW-Authenticate":{"schema":{"type":"string","enum":["Basic realm=\"Fluent Bit Log Ingestion\""]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["Authentication required","Invalid credentials"]},"code":{"type":"string","enum":["BASIC_AUTH_MISSING","BASIC_AUTH_INVALID"]}},"required":["error","code"],"additionalProperties":false}}}},"402":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Redacted application inference conflict","headers":{"Retry-After":{"description":"Seconds before retrying an in-progress admission conflict","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"413":{"description":"Request body exceeds the maximum allowed size","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Redacted application inference refusal or shutdown notice","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string","enum":["Service Unavailable"]},"message":{"type":"string","enum":["Server is shutting down"]}},"required":["error","message"],"additionalProperties":false}]}}}}},"x-audience":"component-internal"}},"/internal/application-agui-inference/runs/{runId}/finalize":{"post":{"operationId":"finalizeInternalApplicationAguiInference","tags":["Application Inference"],"security":[{"hostBasicAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"runId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["completed","failed","cancelled"]},"errorCode":{"type":"string","pattern":"^[A-Z0-9_]{1,64}$"},"inferenceToken":{"type":"string","minLength":1,"maxLength":16384}},"required":["status","inferenceToken"],"additionalProperties":false}}}},"responses":{"200":{"description":"Application inference run finalized","content":{"application/json":{"schema":{"type":"object","properties":{"finalized":{"type":"boolean","enum":[true]}},"required":["finalized"],"additionalProperties":false}}}},"400":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid internal host Basic credentials","headers":{"WWW-Authenticate":{"schema":{"type":"string","enum":["Basic realm=\"Fluent Bit Log Ingestion\""]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["Authentication required","Invalid credentials"]},"code":{"type":"string","enum":["BASIC_AUTH_MISSING","BASIC_AUTH_INVALID"]}},"required":["error","code"],"additionalProperties":false}}}},"402":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Redacted application inference conflict","headers":{"Retry-After":{"description":"Seconds before retrying an in-progress admission conflict","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"413":{"description":"Request body exceeds the maximum allowed size","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Redacted application inference refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Redacted application inference refusal or shutdown notice","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"idempotency":{"type":"object","properties":{"state":{"type":"string","enum":["in_progress","payload_mismatch","outcome_unknown"]},"operation":{"type":"string","minLength":1},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"]},"recovery":{"type":"object","properties":{"available":{"type":"boolean"},"description":{"type":"string"},"resource_url":{"type":"string"}},"required":["available","description"]}},"required":["state","operation","retryable","retry_after_seconds","expires_at"]}},"required":["error"],"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string","enum":["Service Unavailable"]},"message":{"type":"string","enum":["Server is shutting down"]}},"required":["error","message"],"additionalProperties":false}]}}}}},"x-audience":"component-internal"}},"/ai/models":{"get":{"operationId":"listModels","tags":["Model discovery"],"summary":"List models","description":"Returns available AI models and providers. A project-scoped credential, or a selector header naming a project the caller can see, narrows the list to what that project's inference policy permits.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"}],"responses":{"200":{"description":"Model catalog","content":{"application/json":{"schema":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Model identifier.","example":"claude-sonnet-4-6"},"modelId":{"type":"string","description":"Unified model ID (provider/model).","example":"anthropic/claude-sonnet-4-6"},"provider":{"type":"string","description":"Provider name.","example":"anthropic"},"providerLabel":{"type":"string","description":"Public provider display name.","example":"Anthropic"},"providerLogoKey":{"type":"string","description":"Public provider logo key.","example":"anthropic"},"surface":{"type":"string","description":"Gateway protocol for the model’s provider under `/ai/gateway/{provider}`. Known values are `openai`, `anthropic`, and `google`; clients must accept unknown values. Omitted if no gateway protocol is configured, in which case the gateway accepts no paths for the provider.","example":"anthropic"},"operations":{"type":"array","items":{"type":"string"},"description":"Operations of `surface` this model is served on, each at its canonical path (for Google, the `models/<id>:<operation>` form). Known values: `chat-completions`, `responses`, `embeddings` on `openai`; `messages` on `anthropic`; `generate-content`, `stream-generate-content`, `embed-content`, `batch-embed-contents`, `predict`, `openai-responses`, `openai-chat-completions`, `openai-embeddings` on `google`. Not a closed enum — tolerate values you have not seen. Present exactly when `surface` is.","example":["messages"]},"name":{"type":"string","description":"Display name.","example":"Claude Sonnet"},"description":{"type":"string","description":"Short description.","example":"Most efficient for everyday tasks"},"aliases":{"type":"array","items":{"type":"string"},"description":"Accepted aliases for backward-compatible model selection.","example":["sonnet","anthropic/claude-sonnet-4-6"]},"capabilities":{"type":"object","properties":{"webResearch":{"type":"boolean","description":"Whether Studio default chat can enable live web research."},"streaming":{"type":"boolean","description":"Whether streaming responses are supported."},"tools":{"type":"boolean","description":"Whether tool calls are supported."},"vision":{"type":"boolean","description":"Whether image inputs are supported."},"thinking":{"type":"boolean","description":"Whether thinking/reasoning controls are supported."},"supported_parameters":{"type":"array","items":{"type":"string"},"description":"Supported request parameters, using OpenRouter names. Parameters not listed are removed or rejected. Parameters are listed only when support has been verified.","example":["max_tokens","temperature","top_p","tools","tool_choice"]},"reasoning":{"type":"boolean","description":"Whether the model reasons before answering."},"tool_call":{"type":"boolean","description":"Whether the model can call tools."},"temperature":{"type":"boolean","description":"Whether a caller-set temperature reaches the model."},"open_weights":{"type":"boolean","description":"Whether the model weights are publicly released."},"attachment":{"type":"boolean","description":"Whether file input is supported. Omitted if support has not been verified."},"structured_output":{"type":"boolean","description":"Whether schema-constrained output is supported. Omitted if support has not been verified."},"modalities":{"type":"object","properties":{"input":{"type":"array","items":{"type":"string"},"description":"Input modalities.","example":["text","image"]}},"required":["input"],"description":"Supported input modalities. Output modalities are omitted because they have not been verified."},"limit":{"type":"object","properties":{"context":{"type":"integer","exclusiveMinimum":0,"description":"Context window in tokens: the provider's documented limit for the deployment Veryfront serves. Input plus requested output must fit within it. Absent while unevidenced.","example":1000000},"output":{"type":"integer","exclusiveMinimum":0,"description":"Maximum output tokens. Absent while unevidenced.","example":128000}},"description":"Known token ceilings. Each is absent while unevidenced; `limit` is absent while neither is known."},"reasoning_mode":{"type":"string","description":"Supported reasoning control. Known values are `budget` and `adaptive`. Omitted if the model does not reason or support has not been verified. Clients must accept unknown values.","example":"budget"},"transport":{"type":"string","description":"OpenAI wire API the client must use. Known values: `chat-completions`, `responses`. Absent when unconstrained. Not a closed enum.","example":"chat-completions"},"reasoning_budget_tokens":{"type":"integer","exclusiveMinimum":0,"description":"Default thinking budget in tokens when the caller does not specify one. Omitted if no default is configured or the model does not accept a budget, including models without reasoning and models with adaptive thinking.","example":2048},"chat_completions_reasoning_with_function_tools":{"type":"boolean","description":"Whether `chat-completions` supports reasoning and function tools in the same request. If false, choose one. Omitted if support has not been verified.","example":false},"chat_completions_consecutive_system_messages":{"type":"boolean","description":"Whether `chat-completions` accepts consecutive system messages. If true, clients can send system instructions separately. Omitted if support has not been verified.","example":true}},"required":["webResearch","streaming","tools","vision","supported_parameters","reasoning","tool_call","temperature","open_weights","modalities"],"description":"Model capability flags. The camelCase keys are the original Veryfront flags; the snake_case keys are the de facto names clients already parse (OpenRouter, models.dev) and are derived from the capability records."},"temperature":{"type":["object","null"],"properties":{"min":{"type":"number","minimum":0,"description":"Minimum supported temperature."},"max":{"type":"number","minimum":0,"description":"Maximum supported temperature."}},"required":["min","max"],"description":"Per-model temperature limits; null when the runtime fixes or omits temperature."},"supportedProviderTools":{"type":"array","items":{"type":"string"},"description":"Provider-executed agent tools supported on the deployment a request for this model is served from.","example":["web_search","web_fetch"]},"pricing":{"type":"object","properties":{"inputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Input-token price, USD per 1M tokens. Use `inputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"outputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Output-token price, USD per 1M tokens. Use `outputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreationInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Default-retention cache-write input-token price, USD per 1M tokens. Use `cacheCreationInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreation1hInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. One-hour cache-write input-token price, USD per 1M tokens. Use `cacheCreation1hInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Cache-read input-token price, USD per 1M tokens. Use `cacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio input-token price, USD per 1M tokens. Use `audioInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioOutputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio output-token price, USD per 1M tokens. Use `audioOutputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioCacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio cache-read token price, USD per 1M tokens. Use `audioCacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"inputEurPer1M":{"type":"number","minimum":0,"description":"Input-token price. EUR per 1M tokens; see `fx`."},"outputEurPer1M":{"type":"number","minimum":0,"description":"Output-token price. EUR per 1M tokens; see `fx`."},"cacheCreationInputEurPer1M":{"type":"number","minimum":0,"description":"Default-retention cache-write input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"cacheCreation1hInputEurPer1M":{"type":"number","minimum":0,"description":"One-hour cache-write input-token price, when the provider bills it apart from the default cache write. EUR per 1M tokens; see `fx`."},"cacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioInputEurPer1M":{"type":"number","minimum":0,"description":"Audio input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioOutputEurPer1M":{"type":"number","minimum":0,"description":"Audio output-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioCacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."}},"required":["inputUsdPer1M","outputUsdPer1M","inputEurPer1M","outputEurPer1M"],"description":"Public Veryfront customer pricing after markup, used for client-side customer cost estimates."},"providerPricing":{"type":"object","properties":{"inputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Input-token price, USD per 1M tokens. Use `inputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"outputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Output-token price, USD per 1M tokens. Use `outputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreationInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Default-retention cache-write input-token price, USD per 1M tokens. Use `cacheCreationInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreation1hInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. One-hour cache-write input-token price, USD per 1M tokens. Use `cacheCreation1hInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Cache-read input-token price, USD per 1M tokens. Use `cacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio input-token price, USD per 1M tokens. Use `audioInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioOutputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio output-token price, USD per 1M tokens. Use `audioOutputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioCacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio cache-read token price, USD per 1M tokens. Use `audioCacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"inputEurPer1M":{"type":"number","minimum":0,"description":"Input-token price. EUR per 1M tokens; see `fx`."},"outputEurPer1M":{"type":"number","minimum":0,"description":"Output-token price. EUR per 1M tokens; see `fx`."},"cacheCreationInputEurPer1M":{"type":"number","minimum":0,"description":"Default-retention cache-write input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"cacheCreation1hInputEurPer1M":{"type":"number","minimum":0,"description":"One-hour cache-write input-token price, when the provider bills it apart from the default cache write. EUR per 1M tokens; see `fx`."},"cacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioInputEurPer1M":{"type":"number","minimum":0,"description":"Audio input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioOutputEurPer1M":{"type":"number","minimum":0,"description":"Audio output-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioCacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"tiers":{"type":"array","items":{"type":"object","properties":{"inputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Input-token price, USD per 1M tokens. Use `inputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"outputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Output-token price, USD per 1M tokens. Use `outputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreationInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Default-retention cache-write input-token price, USD per 1M tokens. Use `cacheCreationInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreation1hInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. One-hour cache-write input-token price, USD per 1M tokens. Use `cacheCreation1hInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Cache-read input-token price, USD per 1M tokens. Use `cacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio input-token price, USD per 1M tokens. Use `audioInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioOutputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio output-token price, USD per 1M tokens. Use `audioOutputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioCacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio cache-read token price, USD per 1M tokens. Use `audioCacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"inputEurPer1M":{"type":"number","minimum":0,"description":"Input-token price. EUR per 1M tokens; see `fx`."},"outputEurPer1M":{"type":"number","minimum":0,"description":"Output-token price. EUR per 1M tokens; see `fx`."},"cacheCreationInputEurPer1M":{"type":"number","minimum":0,"description":"Default-retention cache-write input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"cacheCreation1hInputEurPer1M":{"type":"number","minimum":0,"description":"One-hour cache-write input-token price, when the provider bills it apart from the default cache write. EUR per 1M tokens; see `fx`."},"cacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioInputEurPer1M":{"type":"number","minimum":0,"description":"Audio input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioOutputEurPer1M":{"type":"number","minimum":0,"description":"Audio output-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioCacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"id":{"type":"string","description":"Stable provider pricing tier identifier","example":"long-context"},"label":{"type":"string","description":"Human-readable pricing tier label","example":"Long context"},"appliesTo":{"type":"string","description":"Condition where this provider pricing tier applies.","example":"Prompts over 200k tokens"}},"required":["inputUsdPer1M","outputUsdPer1M","inputEurPer1M","outputEurPer1M","id","label","appliesTo"],"description":"Raw provider pricing tier that is not the default catalog billing rate."},"description":"Additional raw provider pricing tiers not currently represented by the default public price."}},"required":["inputUsdPer1M","outputUsdPer1M","inputEurPer1M","outputEurPer1M"],"description":"What the provider charges Veryfront (our upstream cost), before markup. For a host that invoices in EUR the EUR prices are that host's published EUR list, unconverted and unrounded."},"pricingSources":{"type":"object","properties":{"directProvider":{"type":"string","format":"uri","description":"Official provider pricing source URL."},"azure":{"type":"string","format":"uri","description":"Official Azure-hosted model pricing source URL."}},"required":["directProvider"],"description":"Official pricing source links for this model."},"deployments":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string","description":"Residency tier of this deployment. Known values: `qualified-sovereign`, `eu-owned`, `eu-resident`, `standard`.","example":"eu-resident"},"jurisdiction":{"type":"string","description":"Legal domicile (ISO 3166-1 alpha-2) of the company operating the inference, or `unknown` where unevidenced. This is the operator's home country, NOT where inference is processed: an EU-resident deployment run by a US company reads `US`. Read `processing` for the location.","example":"US"},"region":{"type":"string","description":"Where inference is PROCESSED — not where the cloud resource was created. `eu` is an EU boundary (the EU Data Zone or an EU multi-region, depending on the host), `europe-west1` / `europe-west4` are single EU member-state regions, `global` means the route is worldwide and no region may be claimed, and `unknown` means unevidenced.","example":"europe-west1"},"processing":{"type":"string","description":"Where inference is processed, normalised from `region` and `tier`. Known values: `eu` (inside a recorded EU boundary), `us` (in the United States), `worldwide` (in any region the operator runs), `unknown` (no processing region is recorded for this route). An open string: tolerate values you have not seen.","example":"eu"},"processing_label":{"type":"string","description":"The processing location in words, for display, e.g. `EU (EEA + Switzerland data zone)`, `EU (europe-west1, Belgium)`, `United States`, `Worldwide (any region)`, `Unknown (processing region not recorded)`. Display text only: branch on `processing`.","example":"EU (europe-west1, Belgium)"},"operator":{"type":"string","description":"Legal entity operating the inference service for this deployment, e.g. `Microsoft Corporation`, `Google LLC`, `OpenAI`, `Scaleway SAS`, or `unknown` where unrecorded.","example":"Google LLC"},"quantization":{"type":"string","description":"Weight precision served. Known values: `bf16`, `fp16`, `fp8`, `fp4`, `nvfp4`, `int4`, `unknown`.","example":"unknown"},"precisionSource":{"type":"string","description":"How `quantization` is evidenced. Known values: `contractual`, `published`, `reported`, `unknown`.","example":"unknown"},"certifications":{"type":"array","items":{"type":"string"},"description":"Certifications evidenced for this deployment. Empty when none is recorded."},"dataRetention":{"anyOf":[{"type":"string"},{"type":"object","properties":{"days":{"type":"integer","minimum":0}},"required":["days"]}],"description":"Prompt retention on this deployment. Known values: `zero`, `metadata-only`, `unknown`, or `{ \"days\": N }`.","example":"unknown"},"supportedProviderTools":{"type":"array","items":{"type":"string"},"description":"Provider-executed agent tools this deployment supports.","example":["web_search"]},"pricing":{"type":"object","properties":{"inputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Input-token price, USD per 1M tokens. Use `inputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"outputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Output-token price, USD per 1M tokens. Use `outputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreationInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Default-retention cache-write input-token price, USD per 1M tokens. Use `cacheCreationInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheCreation1hInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. One-hour cache-write input-token price, USD per 1M tokens. Use `cacheCreation1hInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"cacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Cache-read input-token price, USD per 1M tokens. Use `cacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio input-token price, USD per 1M tokens. Use `audioInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioOutputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio output-token price, USD per 1M tokens. Use `audioOutputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"audioCacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Deprecated. Audio cache-read token price, USD per 1M tokens. Use `audioCacheReadInputEurPer1M`.","deprecated":true,"x-deprecation":{"register_id":"CR-model-catalog-usd-pricing","deprecated_at":"2026-09-27","replacement":"The EUR twin on the same object (`inputEurPer1M`, `cacheReadInputEurPer1M`, …; `input_eur_per_1m`, … on MCP). Converted from USD at the `fx` rate each response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host.","rollout_state":"announced","old_semantics":"Customer price (after markup) or provider cost (before markup) in USD per 1M tokens, as unrounded numbers. Each is present exactly when the model bills that dimension separately, and keeps that meaning while this entry is open.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"}},"inputEurPer1M":{"type":"number","minimum":0,"description":"Input-token price. EUR per 1M tokens; see `fx`."},"outputEurPer1M":{"type":"number","minimum":0,"description":"Output-token price. EUR per 1M tokens; see `fx`."},"cacheCreationInputEurPer1M":{"type":"number","minimum":0,"description":"Default-retention cache-write input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"cacheCreation1hInputEurPer1M":{"type":"number","minimum":0,"description":"One-hour cache-write input-token price, when the provider bills it apart from the default cache write. EUR per 1M tokens; see `fx`."},"cacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioInputEurPer1M":{"type":"number","minimum":0,"description":"Audio input-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioOutputEurPer1M":{"type":"number","minimum":0,"description":"Audio output-token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."},"audioCacheReadInputEurPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price, when the provider bills it separately. EUR per 1M tokens; see `fx`."}},"required":["inputUsdPer1M","outputUsdPer1M","inputEurPer1M","outputEurPer1M"],"description":"Customer price for this deployment after markup. Excludes provider cost and the markup amount."}},"required":["tier","jurisdiction","region","processing","processing_label","operator","quantization","precisionSource","certifications","dataRetention","supportedProviderTools","pricing"],"description":"A model deployment, including its location, terms, and pricing."},"description":"Available deployments in routing preference order. Without a policy, requests use the first deployment. Only eligible hosts are listed. If a production deployment is eligible, only production deployments appear. Otherwise, an eligible rollout fallback appears with its own tier, region, and retention settings."}},"required":["id","modelId","provider","providerLabel","providerLogoKey","name","aliases","capabilities","temperature","supportedProviderTools","pricing","providerPricing","pricingSources","deployments"]},"description":"Available AI models."},"providers":{"type":"array","items":{"type":"string"},"description":"Available provider names."},"defaultModelId":{"type":"string","description":"Default unified model ID recommended by the API.","example":"mistral/mistral-small-2503"},"fx":{"type":"object","properties":{"base":{"type":"string","description":"The currency one unit of which `rate` prices","example":"EUR"},"quote":{"type":"string","description":"The currency `rate` is expressed in","example":"USD"},"rate":{"type":"number","exclusiveMinimum":0,"description":"1 `base` = `rate` `quote`","example":1.1403},"source":{"type":"string","description":"Where the rate is published","example":"ECB euro foreign exchange reference rate"},"date":{"type":"string","description":"The reference date of the rate (YYYY-MM-DD)","example":"2026-09-25"}},"required":["base","quote","rate","source","date"],"description":"1 `base` = `rate` `quote`. EUR prices converted from USD are the USD price divided by `rate`, rounded to 6 decimal places. For a host that invoices in EUR the EUR prices are that host's published EUR list, unconverted and unrounded."},"web_tools":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","description":"The platform agent tool: `web_search` or `web_fetch`.","example":"web_search"},"data_sent":{"type":"string","description":"What the tool sends out. Known values: `query_and_search_options` (the search query, plus any domain filters and approximate user location the call states), `url_and_fetched_content` (the URL is requested and the page is returned into the run). An open string: tolerate values you have not seen.","example":"query_and_search_options"},"recipient_class":{"type":"string","description":"Who receives it. Known values: `third_party_search_provider` (the search backend of the selected deployment), `fetch_target` (the site the URL names).","example":"third_party_search_provider"},"boundary_covered":{"type":"boolean","description":"Whether this flow is covered by the accepted processing boundary. False unless a deployment carries evidence for it; never inferred from where inference runs."},"available":{"type":"boolean","description":"Whether agent runs are offered the tool in this environment, under this project's policy."},"unavailable_reason":{"type":"string","description":"Why the tool is not offered. Known values: `no_search_deployment`, `boundary_not_covered`, `policy_denied`.","example":"boundary_not_covered"}},"required":["tool","data_sent","recipient_class","boundary_covered","available"],"description":"What a platform web tool sends, to whom, and whether it is offered."},"description":"The platform web tools' data flows. Facts about the tool, not about the model: inference residency says nothing about where a search query or fetched URL goes."}},"required":["models","providers","defaultModelId","fx","web_tools"]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"This project's inference policy could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGatewayError"}}}}}}},"/catalog/models":{"get":{"operationId":"listPublicModelCatalog","tags":["Model discovery"],"summary":"List public model catalog","description":"Returns the public platform model catalog: models, capabilities, customer pricing, provider cost and, per deployment, the residency tier, the legal domicile of the operator (`jurisdiction`), the processing region, the normalised processing location (`processing`: `eu`, `us`, `worldwide` or `unknown`, with a display `processing_label`), precision, certifications and retention. Requires no authentication, reads no caller context and is identical for every caller, so it is cacheable. Provider cost (`providerPricing`) is served in EUR only; EUR prices are converted from USD at the `fx` rate the response states, except provider cost on a host that invoices in EUR, which is the published EUR list of that host. Pricing source links are not part of this payload; the authenticated `GET /ai/models` carries those.","security":[],"responses":{"200":{"description":"Public model catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicModelCatalog"}}}},"304":{"description":"The catalog has not changed since the ETag in `If-None-Match`"}}}},"/ai/v1/messages":{"post":{"operationId":"neutralMessages","tags":["Anthropic Messages"],"summary":"Messages (vendor-neutral)","description":"Anthropic-compatible Messages on the vendor-neutral base URL. Set an Anthropic SDK or Claude Code base URL (`ANTHROPIC_BASE_URL`) to `https://api.<domain>/ai`.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":245,"description":"Durable run ID. Required for run-bound service-account credentials."},"required":false,"name":"x-veryfront-agent-run-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable conversation ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-conversation-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable message ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-message-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Agent ID. Must match the authenticated run-bound credential."},"required":false,"name":"x-veryfront-agent-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Optional billing group. Run requests are pinned to agent-run:<run-id>."},"required":false,"name":"x-veryfront-billing-group-id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"title":"NeutralAnthropicMessagesRequest","type":"object","properties":{"model":{"type":"string","description":"Catalog model ID or alias. Required: the request is routed by model, not by base URL."},"messages":{"type":"array","items":{},"description":"Vendor-shaped messages, forwarded as sent."},"max_tokens":{"type":"integer","minimum":1}},"required":["model","messages","max_tokens"],"additionalProperties":true}}}},"responses":{"200":{"description":"Upstream provider response (forwarded as-is)"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"402":{"description":"Insufficient AI credits, an exhausted monthly AI budget, or a provider spend limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"403":{"description":"Project access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"404":{"description":"No deployment of this model speaks this protocol natively","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"413":{"description":"Request body over the 32 MiB limit (code request_too_large), or an upstream 413 re-rendered in this envelope"},"429":{"description":"The calling API key's requests-per-minute limit (code key-rate-limited), or an upstream provider rate limit re-rendered in this envelope with its Retry-After"},"500":{"description":"Gateway error, or an upstream 500 re-rendered in this envelope"},"502":{"description":"Gateway proxy error, or an upstream 502 re-rendered in this envelope"},"503":{"description":"No available deployment, auth unavailable, or an upstream 503 re-rendered in this envelope"},"529":{"description":"Upstream provider overloaded, re-rendered in this envelope"},"default":{"description":"Any other status the upstream provider returned, with the upstream status and its body (if any) re-rendered in this envelope"}}}},"/ai/v1/messages/count_tokens":{"post":{"operationId":"neutralCountTokens","tags":["Anthropic Messages"],"summary":"Count Message Tokens (vendor-neutral)","description":"Anthropic-compatible token counting. No deployment serves it today, so it answers a typed 404 that clients degrade from.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":245,"description":"Durable run ID. Required for run-bound service-account credentials."},"required":false,"name":"x-veryfront-agent-run-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable conversation ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-conversation-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable message ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-message-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Agent ID. Must match the authenticated run-bound credential."},"required":false,"name":"x-veryfront-agent-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Optional billing group. Run requests are pinned to agent-run:<run-id>."},"required":false,"name":"x-veryfront-billing-group-id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"title":"NeutralAnthropicCountTokensRequest","type":"object","properties":{"model":{"type":"string","description":"Catalog model ID or alias. Required: the request is routed by model, not by base URL."},"messages":{"type":"array","items":{},"description":"Vendor-shaped messages, forwarded as sent."}},"required":["model","messages"],"additionalProperties":true}}}},"responses":{"200":{"description":"Upstream provider response (forwarded as-is)"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"402":{"description":"Insufficient AI credits, an exhausted monthly AI budget, or a provider spend limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"403":{"description":"Project access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"404":{"description":"No deployment of this model speaks this protocol natively","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralAnthropicError"}}}},"413":{"description":"Request body over the 32 MiB limit (code request_too_large), or an upstream 413 re-rendered in this envelope"},"429":{"description":"The calling API key's requests-per-minute limit (code key-rate-limited), or an upstream provider rate limit re-rendered in this envelope with its Retry-After"},"500":{"description":"Gateway error, or an upstream 500 re-rendered in this envelope"},"502":{"description":"Gateway proxy error, or an upstream 502 re-rendered in this envelope"},"503":{"description":"No available deployment, auth unavailable, or an upstream 503 re-rendered in this envelope"},"529":{"description":"Upstream provider overloaded, re-rendered in this envelope"},"default":{"description":"Any other status the upstream provider returned, with the upstream status and its body (if any) re-rendered in this envelope"}}}},"/ai/v1/chat/completions":{"post":{"operationId":"neutralChatCompletions","tags":["OpenAI Chat Completions"],"summary":"Create a chat completion","description":"Generates a chat completion using the OpenAI-compatible format. The model ID selects the deployment.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":245,"description":"Durable run ID. Required for run-bound service-account credentials."},"required":false,"name":"x-veryfront-agent-run-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable conversation ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-conversation-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable message ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-message-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Agent ID. Must match the authenticated run-bound credential."},"required":false,"name":"x-veryfront-agent-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Optional billing group. Run requests are pinned to agent-run:<run-id>."},"required":false,"name":"x-veryfront-billing-group-id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"title":"NeutralChatCompletionsRequest","type":"object","properties":{"model":{"type":"string","description":"Catalog model ID or alias. Required: the request is routed by model, not by base URL."},"messages":{"type":"array","items":{},"description":"Vendor-shaped messages, forwarded as sent."}},"required":["model","messages"],"additionalProperties":true}}}},"responses":{"200":{"description":"Upstream provider response (forwarded as-is)"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"402":{"description":"Insufficient AI credits, an exhausted monthly AI budget, or a provider spend limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"403":{"description":"Project access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"404":{"description":"No deployment of this model speaks this protocol natively","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"413":{"description":"Request body over the 32 MiB limit (code request_too_large), or an upstream 413 re-rendered in this envelope"},"429":{"description":"The calling API key's requests-per-minute limit (code key-rate-limited), or an upstream provider rate limit re-rendered in this envelope with its Retry-After"},"500":{"description":"Gateway error, or an upstream 500 re-rendered in this envelope"},"502":{"description":"Gateway proxy error, or an upstream 502 re-rendered in this envelope"},"503":{"description":"No available deployment, auth unavailable, or an upstream 503 re-rendered in this envelope"},"529":{"description":"Upstream provider overloaded, re-rendered in this envelope"},"default":{"description":"Any other status the upstream provider returned, with the upstream status and its body (if any) re-rendered in this envelope"}}}},"/ai/v1/responses":{"post":{"operationId":"neutralResponses","tags":["OpenAI Responses"],"summary":"Create a response","description":"Generates a response using the OpenAI-compatible Responses API format.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":245,"description":"Durable run ID. Required for run-bound service-account credentials."},"required":false,"name":"x-veryfront-agent-run-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable conversation ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-conversation-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable message ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-message-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Agent ID. Must match the authenticated run-bound credential."},"required":false,"name":"x-veryfront-agent-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Optional billing group. Run requests are pinned to agent-run:<run-id>."},"required":false,"name":"x-veryfront-billing-group-id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"title":"NeutralResponsesRequest","type":"object","properties":{"model":{"type":"string","description":"Catalog model ID or alias. Required: the request is routed by model, not by base URL."},"input":{"description":"Vendor-shaped input, forwarded as sent."}},"required":["model"],"additionalProperties":true}}}},"responses":{"200":{"description":"Upstream provider response (forwarded as-is)"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"402":{"description":"Insufficient AI credits, an exhausted monthly AI budget, or a provider spend limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"403":{"description":"Project access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"404":{"description":"No deployment of this model speaks this protocol natively","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"413":{"description":"Request body over the 32 MiB limit (code request_too_large), or an upstream 413 re-rendered in this envelope"},"429":{"description":"The calling API key's requests-per-minute limit (code key-rate-limited), or an upstream provider rate limit re-rendered in this envelope with its Retry-After"},"500":{"description":"Gateway error, or an upstream 500 re-rendered in this envelope"},"502":{"description":"Gateway proxy error, or an upstream 502 re-rendered in this envelope"},"503":{"description":"No available deployment, auth unavailable, or an upstream 503 re-rendered in this envelope"},"529":{"description":"Upstream provider overloaded, re-rendered in this envelope"},"default":{"description":"Any other status the upstream provider returned, with the upstream status and its body (if any) re-rendered in this envelope"}}}},"/ai/v1/embeddings":{"post":{"operationId":"neutralEmbeddings","tags":["Embeddings"],"summary":"Create embeddings","description":"Generates embeddings using the OpenAI-compatible request and response format.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":245,"description":"Durable run ID. Required for run-bound service-account credentials."},"required":false,"name":"x-veryfront-agent-run-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable conversation ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-conversation-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable message ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-message-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Agent ID. Must match the authenticated run-bound credential."},"required":false,"name":"x-veryfront-agent-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Optional billing group. Run requests are pinned to agent-run:<run-id>."},"required":false,"name":"x-veryfront-billing-group-id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"title":"NeutralEmbeddingsRequest","type":"object","properties":{"model":{"type":"string","description":"Catalog model ID or alias. Required: the request is routed by model, not by base URL."},"input":{"description":"Vendor-shaped input, forwarded as sent."}},"required":["model","input"],"additionalProperties":true}}}},"responses":{"200":{"description":"Upstream provider response (forwarded as-is)"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"402":{"description":"Insufficient AI credits, an exhausted monthly AI budget, or a provider spend limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"403":{"description":"Project access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"404":{"description":"No deployment of this model speaks this protocol natively","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralOpenAiError"}}}},"413":{"description":"Request body over the 32 MiB limit (code request_too_large), or an upstream 413 re-rendered in this envelope"},"429":{"description":"The calling API key's requests-per-minute limit (code key-rate-limited), or an upstream provider rate limit re-rendered in this envelope with its Retry-After"},"500":{"description":"Gateway error, or an upstream 500 re-rendered in this envelope"},"502":{"description":"Gateway proxy error, or an upstream 502 re-rendered in this envelope"},"503":{"description":"No available deployment, auth unavailable, or an upstream 503 re-rendered in this envelope"},"529":{"description":"Upstream provider overloaded, re-rendered in this envelope"},"default":{"description":"Any other status the upstream provider returned, with the upstream status and its body (if any) re-rendered in this envelope"}}}},"/ai/v1/models":{"get":{"operationId":"neutralOpenAiModelList","tags":["Inference Models"],"summary":"List Models (OpenAI or Anthropic format)","description":"Lists the Veryfront catalog in OpenAI's list format, or in Anthropic's when the request carries an `anthropic-version` header, as Anthropic SDKs and Claude Code do. With that header, errors are in Anthropic's envelope and the Anthropic cursors `after_id` and `before_id` apply. Never forwarded to a vendor.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":1000,"description":"Maximum number of models to return.","example":1000},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Anthropic format only (`anthropic-version` sent): return the models that follow this model id."},"required":false,"name":"after_id","in":"query"},{"schema":{"type":"string","description":"Anthropic format only (`anthropic-version` sent): return the models that precede this model id."},"required":false,"name":"before_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"},{"schema":{"type":"string","description":"Present on an Anthropic client's request. Selects Anthropic's list format and error envelope.","example":"2023-06-01"},"required":false,"name":"anthropic-version","in":"header"}],"responses":{"200":{"description":"Model list, answered from the Veryfront catalog","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NeutralOpenAiModelList"},{"$ref":"#/components/schemas/NeutralAnthropicModelList"}]}}}},"400":{"description":"No project selector, or a selector that names no usable project","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NeutralOpenAiError"},{"$ref":"#/components/schemas/NeutralAnthropicError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NeutralOpenAiError"},{"$ref":"#/components/schemas/NeutralAnthropicError"}]}}}},"403":{"description":"Project access denied, or a credential restricted to template inference","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NeutralOpenAiError"},{"$ref":"#/components/schemas/NeutralAnthropicError"}]}}}},"500":{"description":"Gateway error","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NeutralOpenAiError"},{"$ref":"#/components/schemas/NeutralAnthropicError"}]}}}},"503":{"description":"Authentication or the project inference policy is temporarily unavailable","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NeutralOpenAiError"},{"$ref":"#/components/schemas/NeutralAnthropicError"}]}}}}}}},"/ai/v1beta/models":{"get":{"operationId":"neutralGoogleModelList","tags":["Inference Models"],"summary":"List Models (Gemini format)","description":"Lists the Veryfront catalog's Gemini models in Google's list format. Never forwarded to a vendor.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":1000,"description":"Maximum number of models to return.","example":50},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"description":"The `nextPageToken` of the previous page."},"required":false,"name":"pageToken","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"}],"responses":{"200":{"description":"Model list, answered from the Veryfront catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleModelList"}}}},"400":{"description":"No project selector, or a selector that names no usable project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"403":{"description":"Project access denied, or a credential restricted to template inference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"500":{"description":"Gateway error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"503":{"description":"Authentication or the project inference policy is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}}}}},"/ai/v1beta/models/{model_method}":{"post":{"operationId":"neutralGoogleModelMethod","tags":["Gemini Models"],"summary":"Gemini model method (vendor-neutral)","description":"Gemini-native API on the vendor-neutral base URL `/ai/v1beta`, served through the same gateway pipeline as the vendor route. The model in the URL selects the deployment; `streamGenerateContent` streams, and honours `?alt=sse`.","parameters":[{"schema":{"type":"string","description":"The model and the Gemini method, `<model>:<method>`. The model is a catalog id or alias (`gemini-2.5-flash`, `google/gemini-2.5-flash`); the method is `generateContent`, `streamGenerateContent`, `embedContent` or `batchEmbedContents`.","example":"gemini-2.5-flash:generateContent"},"required":true,"name":"model_method","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":245,"description":"Durable run ID. Required for run-bound service-account credentials."},"required":false,"name":"x-veryfront-agent-run-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable conversation ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-conversation-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable message ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-message-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Agent ID. Must match the authenticated run-bound credential."},"required":false,"name":"x-veryfront-agent-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Optional billing group. Run requests are pinned to agent-run:<run-id>."},"required":false,"name":"x-veryfront-billing-group-id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"title":"NeutralGoogleRequest","type":"object","description":"Gemini-native request body (`contents` for generateContent, `content` for embedContent, `requests` for batchEmbedContents), forwarded as sent.","additionalProperties":true}}}},"responses":{"200":{"description":"Upstream provider response (forwarded as-is)"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"402":{"description":"Insufficient AI credits, an exhausted monthly AI budget, or a provider spend limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"403":{"description":"Project access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"404":{"description":"No deployment of this model speaks this protocol natively","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"413":{"description":"Request body over the 32 MiB limit (code request_too_large), or an upstream 413 re-rendered in this envelope"},"429":{"description":"The calling API key's requests-per-minute limit (code key-rate-limited), or an upstream provider rate limit re-rendered in this envelope with its Retry-After"},"500":{"description":"Gateway error, or an upstream 500 re-rendered in this envelope"},"502":{"description":"Gateway proxy error, or an upstream 502 re-rendered in this envelope"},"503":{"description":"No available deployment, auth unavailable, or an upstream 503 re-rendered in this envelope"},"529":{"description":"Upstream provider overloaded, re-rendered in this envelope"},"default":{"description":"Any other status the upstream provider returned, with the upstream status and its body (if any) re-rendered in this envelope"}}}},"/ai/v1beta/models/{vendor}/{model_method}":{"post":{"operationId":"neutralGooglePrefixedModelMethod","tags":["Gemini Models"],"summary":"Gemini model method, vendor-prefixed model id (vendor-neutral)","description":"Gemini-native API on the vendor-neutral base URL `/ai/v1beta`, served through the same gateway pipeline as the vendor route. The model in the URL selects the deployment; `streamGenerateContent` streams, and honours `?alt=sse`. Accepts a model id written with its vendor prefix, e.g. `models/google/gemini-2.5-flash:generateContent`.","parameters":[{"schema":{"type":"string","description":"The vendor prefix of the model id: `google` or `google-ai-studio`.","example":"google"},"required":true,"name":"vendor","in":"path"},{"schema":{"type":"string","description":"The model and the Gemini method, `<model>:<method>`. The model is a catalog id or alias (`gemini-2.5-flash`, `google/gemini-2.5-flash`); the method is `generateContent`, `streamGenerateContent`, `embedContent` or `batchEmbedContents`.","example":"gemini-2.5-flash:generateContent"},"required":true,"name":"model_method","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":245,"description":"Durable run ID. Required for run-bound service-account credentials."},"required":false,"name":"x-veryfront-agent-run-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable conversation ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-conversation-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Durable message ID. Required with agent run attribution."},"required":false,"name":"x-veryfront-message-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Agent ID. Must match the authenticated run-bound credential."},"required":false,"name":"x-veryfront-agent-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Optional billing group. Run requests are pinned to agent-run:<run-id>."},"required":false,"name":"x-veryfront-billing-group-id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"title":"NeutralGoogleRequest","type":"object","description":"Gemini-native request body (`contents` for generateContent, `content` for embedContent, `requests` for batchEmbedContents), forwarded as sent.","additionalProperties":true}}}},"responses":{"200":{"description":"Upstream provider response (forwarded as-is)"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"402":{"description":"Insufficient AI credits, an exhausted monthly AI budget, or a provider spend limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"403":{"description":"Project access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"404":{"description":"No deployment of this model speaks this protocol natively","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeutralGoogleError"}}}},"413":{"description":"Request body over the 32 MiB limit (code request_too_large), or an upstream 413 re-rendered in this envelope"},"429":{"description":"The calling API key's requests-per-minute limit (code key-rate-limited), or an upstream provider rate limit re-rendered in this envelope with its Retry-After"},"500":{"description":"Gateway error, or an upstream 500 re-rendered in this envelope"},"502":{"description":"Gateway proxy error, or an upstream 502 re-rendered in this envelope"},"503":{"description":"No available deployment, auth unavailable, or an upstream 503 re-rendered in this envelope"},"529":{"description":"Upstream provider overloaded, re-rendered in this envelope"},"default":{"description":"Any other status the upstream provider returned, with the upstream status and its body (if any) re-rendered in this envelope"}}}},"/projects/{project_reference}/images/generate":{"post":{"operationId":"generateProjectImages","tags":["Image generation"],"summary":"Generate project images","description":"Generates AI images using the EU Azure FLUX.2-pro deployment. Images are stored as project uploads and returned as API upload URLs.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":1000,"description":"Text description of the desired image (max 1000 characters)"},"count":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Number of images to generate (1-10, default: 1)"},"seed":{"type":"integer","minimum":1,"maximum":999999,"description":"Random seed for reproducible generation"}},"required":["prompt"]},"example":{"prompt":"A futuristic cityscape at sunset with flying cars","count":2}}}},"responses":{"200":{"description":"Images generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"string"},"description":"Project upload URLs or failure placeholders"},"count":{"type":"number","description":"Number of returned sources, including failure placeholders"}},"required":["sources","count"]}}}},"400":{"description":"Invalid input - prompt too long or invalid count"},"401":{"description":"Unauthorized"},"402":{"description":"Payment required - not enough credits for the first image","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Project not found"},"500":{"description":"Server error - Image generation failed"},"503":{"description":"Service unavailable - Image generation not configured, or the AI provider spend limit is reached"}}}},"/ai/gateway/billing/finalize":{"post":{"operationId":"finalizeGatewayBillingGroup","tags":["Provider gateway"],"summary":"Finalize gateway billing group","description":"Reconciles direct gateway charges for a user-facing billing group using server-recorded usage.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project UUID or slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-reference","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project ID used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Project slug used to attribute billing finalization."},"required":false,"name":"x-veryfront-project-slug","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayBillingGroupFinalizeRequest"}}}},"responses":{"200":{"description":"Billing group finalized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayBillingGroupFinalizeResponse"}}}},"400":{"description":"Invalid billing group request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGatewayError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGatewayError"}}}},"402":{"description":"Insufficient AI credits for reconciliation","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","enum":["insufficient-credits"],"description":"Error identifier."},"error":{"type":"string","description":"Error message."},"suggestion":{"type":"string","description":"Actionable next step for the user."},"balance":{"type":"number","description":"Current credit balance."},"required":{"type":"number","description":"Credits required for this request."}},"required":["slug","error","suggestion","balance","required"]}}}},"403":{"description":"Project access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGatewayError"}}}},"404":{"description":"Billing group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGatewayError"}}}},"409":{"description":"Billing group usage is not ready to finalize","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGatewayError"}}}}}}},"/projects/{project_reference}/inference-policy":{"get":{"operationId":"getProjectInferencePolicy","tags":["Project inference policy"],"summary":"Get project inference policy","description":"Returns the project’s inference policy. If no policy is configured, returns the defaults with `configured: false`.\n\nThe policy can restrict sovereignty tier, precision, jurisdictions, hosts, and models. It can tighten the environment policy but cannot broaden it. Every project is EU-only by default: a project without a policy, or without a `min_tier`, is served under an `eu-resident` minimum tier. Only standard-tier consent lets a project be served outside the EU; `allow_non_eu_hosting` reports whether the project has opted in.\n\n`enforced` is false only when a stored tier or precision is unsupported by this API version; in that case, the gateway rejects all requests for the project.\n\nRequires a signed-in project administrator. API keys are rejected, including project-scoped keys.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"responses":{"200":{"description":"The project's inference policy, or the defaults it is served under","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InferencePolicy"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"replaceProjectInferencePolicy","tags":["Project inference policy"],"summary":"Replace project inference policy","description":"Replace the project’s inference constraints with the request body. Omitted constraints are removed; this operation does not merge fields with the existing policy.\n\nRecorded standard-tier consent is preserved. Before setting `min_tier` to `standard`, record consent through the [standard-tier opt-in endpoint](https://veryfront.com/docs/cloud/rest/api-reference/project-inference-policy/opt-in-to-standard-tier-serving). After consent is recorded, you can set `standard` as the minimum tier through this endpoint.\n\nThe audit record identifies the caller who made the change. Sign in as a project administrator to use this endpoint. API keys are rejected regardless of their scopes.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceInferencePolicyRequest"}}}},"responses":{"200":{"description":"The policy as it now stands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InferencePolicy"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"clearProjectInferencePolicy","tags":["Project inference policy"],"summary":"Clear project inference policy","description":"Removes the project’s inference policy and any recorded standard-tier consent. The project is then served like a project that never stated a policy: EU-only, under the default `eu-resident` minimum tier. Clearing therefore also ends any non-EU hosting the project had opted in to; opting in again requires new standard-tier consent.\n\nThe API records who removed the policy and retains the policy history. If the project has no policy, the request succeeds without a change.\n\nRequires a signed-in project administrator. API keys are rejected regardless of their scopes.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"responses":{"204":{"description":"The project states no inference policy"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/inference-policy/standard-tier-opt-in":{"post":{"operationId":"optInProjectInferencePolicyStandardTier","tags":["Project inference policy"],"summary":"Opt in to standard tier serving","description":"Records consent to standard-tier serving and sets `min_tier` to `standard`. Other constraints remain unchanged.\n\nThe consent record includes the administrator and timestamp and survives later changes to the minimum tier. If consent is already recorded and the minimum tier is already `standard`, the request leaves both unchanged.\n\nRequires a signed-in project administrator. API keys are rejected regardless of their scopes.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"responses":{"200":{"description":"The policy, with the acceptance recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InferencePolicy"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/rag/documents":{"get":{"operationId":"listRagDocuments","tags":["Project documents"],"summary":"List RAG documents","description":"List the metadata records currently tracked for a project RAG store.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"RAG documents for the project.","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"revision":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Opaque document revision. Pass it as expected_revision to conditionally update or delete this record."},"id":{"type":"string","format":"uuid","description":"RAG document ID."},"title":{"type":"string","description":"Human-readable document title."},"source":{"type":"string","description":"Upstream source location or identifier for the document."},"type":{"type":"string","description":"Document type label stored with the indexed metadata."},"metadata":{"type":"object","additionalProperties":{},"description":"Structured metadata stored with the document."},"created_at":{"type":"string","description":"Document creation timestamp in ISO 8601 format."},"updated_at":{"type":"string","description":"Last document update timestamp in ISO 8601 format."}},"required":["revision","id","title","source","type","metadata","created_at","updated_at"]},"description":"Project RAG documents in storage order."}},"required":["documents"]}}}},"404":{"description":"Project not found"}}},"post":{"operationId":"upsertRagDocument","tags":["Project documents"],"summary":"Upsert a RAG document","description":"Create a project RAG document record or updates an existing record by ID.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":["string","null"],"pattern":"^[a-f0-9]{64}$","description":"Require this existing document revision. Null creates only if absent; omit for the original unconditional upsert behavior. A stale revision returns 412."},"id":{"type":"string","format":"uuid","description":"Existing document ID to update. Omit to create a new document."},"title":{"type":"string","minLength":1,"description":"Document title shown to operators and AI agents."},"source":{"type":"string","description":"Optional upstream source reference such as a file path or URL."},"type":{"type":"string","description":"Optional document type label used for retrieval metadata."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional structured metadata to persist alongside the document."}},"required":["title"]}}}},"responses":{"200":{"description":"Created or updated RAG document.","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"revision":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Opaque document revision. Pass it as expected_revision to conditionally update or delete this record."},"id":{"type":"string","format":"uuid","description":"RAG document ID."},"title":{"type":"string","description":"Human-readable document title."},"source":{"type":"string","description":"Upstream source location or identifier for the document."},"type":{"type":"string","description":"Document type label stored with the indexed metadata."},"metadata":{"type":"object","additionalProperties":{},"description":"Structured metadata stored with the document."},"created_at":{"type":"string","description":"Document creation timestamp in ISO 8601 format."},"updated_at":{"type":"string","description":"Last document update timestamp in ISO 8601 format."}},"required":["revision","id","title","source","type","metadata","created_at","updated_at"],"description":"Created or updated RAG document."}},"required":["document"]}}}},"404":{"description":"Project not found"},"412":{"description":"The document exists or its revision changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/rag/documents/{documentId}":{"delete":{"operationId":"deleteRagDocument","tags":["Project documents"],"summary":"Delete a RAG document","description":"Delete a tracked project RAG document by ID.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"RAG document ID to delete."},"required":true,"name":"documentId","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Delete only this observed document revision. A stale revision returns 412."},"required":false,"name":"expected_revision","in":"query"}],"responses":{"200":{"description":"Deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Whether the document was deleted."}},"required":["deleted"]}}}},"404":{"description":"Project or document not found"},"412":{"description":"The document revision changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/chunks":{"get":{"operationId":"listBranchFileChunks","tags":["File Chunks"],"summary":"List branch file chunks","description":"List chunks for a file on a project branch after verifying project read capability.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name or ID from the route."},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"URL-encoded file path for the chunked file."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100,"description":"Maximum chunks to return, from 1 to 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from `page_info.next`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"boolean","default":false,"description":"Whether to include embedding metadata when available."},"required":false,"name":"include_embeddings","in":"query"},{"schema":{"type":"number","description":"Embedding vector dimension; required when embedding metadata is requested.","example":1536},"required":false,"name":"embedding_dimension","in":"query"},{"schema":{"type":"boolean","description":"Include the stored vector with requested embedding metadata. Use with the embedding inclusion flag.","example":false},"required":false,"name":"include_vector","in":"query"}],"responses":{"200":{"description":"File chunks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileChunkList"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"upsertBranchFileChunks","tags":["File Chunks"],"summary":"Upsert branch file chunks","description":"Create or replaces chunk records for a file on a project branch after verifying project write capability.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name or ID from the route."},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"URL-encoded file path for the chunked file."},"required":true,"name":"filePath","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"chunk_index":{"type":"number","minimum":0,"description":"Zero-based chunk position within the file."},"content":{"type":"string","minLength":1,"description":"Text content for this chunk."},"start_offset":{"type":"number","minimum":0,"description":"Start character offset in the source file."},"end_offset":{"type":"number","minimum":0,"description":"End character offset in the source file."},"token_count":{"type":"number","minimum":1,"description":"Estimated token count for the chunk content."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional client metadata stored with the chunk."}},"required":["chunk_index","content","start_offset","end_offset","token_count"]},"minItems":1,"maxItems":500,"description":"Chunks to replace the current indexed chunks for the file."}},"required":["chunks"]}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"index":{"type":"number"}},"required":["id","index"]},"description":"Stored chunk identifiers and their indexes."},"created":{"type":"number","description":"Number of chunks created by the upsert operation."},"updated":{"type":"number","description":"Number of chunks updated by the upsert operation."}},"required":["chunks","created","updated"]}}}},"404":{"description":"Not found"}}},"delete":{"operationId":"deleteBranchFileChunks","tags":["File Chunks"],"summary":"Delete branch file chunks","description":"Delete chunk records for a file on a project branch after verifying project write capability.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name or ID from the route."},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"URL-encoded file path for the chunked file."},"required":true,"name":"filePath","in":"path"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"number","description":"Number of chunks deleted for the file."}},"required":["deleted"]}}}},"404":{"description":"Not found"}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/chunks/{chunkId}":{"get":{"operationId":"getBranchFileChunk","tags":["File Chunks"],"summary":"Get branch file chunk","description":"Return one chunk for a file on a project branch after verifying project read capability.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name or ID from the route."},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"URL-encoded file path for the chunked file."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","format":"uuid","description":"File chunk UUID."},"required":true,"name":"chunkId","in":"path"},{"schema":{"type":"boolean","default":false,"description":"Whether to include embedding metadata when available."},"required":false,"name":"include_embedding","in":"query"},{"schema":{"type":"number","description":"Embedding vector dimension; required when embedding metadata is requested.","example":1536},"required":false,"name":"embedding_dimension","in":"query"},{"schema":{"type":"boolean","description":"Include the stored vector with requested embedding metadata. Use with the embedding inclusion flag.","example":false},"required":false,"name":"include_vector","in":"query"}],"responses":{"200":{"description":"Chunk","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileChunk"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/environments/{environmentName}/files/{filePath}/chunks":{"get":{"operationId":"listEnvironmentFileChunks","tags":["File Chunks"],"summary":"List environment file chunks","description":"List chunks for a file in a project environment after verifying project read capability.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Environment name from the route."},"required":true,"name":"environmentName","in":"path"},{"schema":{"type":"string","description":"URL-encoded file path for the chunked file."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100,"description":"Maximum chunks to return, from 1 to 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from `page_info.next`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"boolean","default":false,"description":"Whether to include embedding metadata when available."},"required":false,"name":"include_embeddings","in":"query"},{"schema":{"type":"number","description":"Embedding vector dimension; required when embedding metadata is requested.","example":1536},"required":false,"name":"embedding_dimension","in":"query"},{"schema":{"type":"boolean","description":"Include the stored vector with requested embedding metadata. Use with the embedding inclusion flag.","example":false},"required":false,"name":"include_vector","in":"query"}],"responses":{"200":{"description":"File chunks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileChunkList"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/environments/{environmentName}/files/{filePath}/chunks/{chunkId}":{"get":{"operationId":"getEnvironmentFileChunk","tags":["File Chunks"],"summary":"Get environment file chunk","description":"Return one chunk for a file in a project environment after verifying project read capability.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Environment name from the route."},"required":true,"name":"environmentName","in":"path"},{"schema":{"type":"string","description":"URL-encoded file path for the chunked file."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","format":"uuid","description":"File chunk UUID."},"required":true,"name":"chunkId","in":"path"},{"schema":{"type":"boolean","default":false,"description":"Whether to include embedding metadata when available."},"required":false,"name":"include_embedding","in":"query"},{"schema":{"type":"number","description":"Embedding vector dimension; required when embedding metadata is requested.","example":1536},"required":false,"name":"embedding_dimension","in":"query"},{"schema":{"type":"boolean","description":"Include the stored vector with requested embedding metadata. Use with the embedding inclusion flag.","example":false},"required":false,"name":"include_vector","in":"query"}],"responses":{"200":{"description":"Chunk","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileChunk"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases/{version}/files/{filePath}/chunks":{"get":{"operationId":"listReleaseFileChunks","tags":["File Chunks"],"summary":"List release file chunks","description":"List chunks for a file in a published release after verifying project read capability.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version from the route."},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","description":"URL-encoded file path for the chunked file."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100,"description":"Maximum chunks to return, from 1 to 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from `page_info.next`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"boolean","default":false,"description":"Whether to include embedding metadata when available."},"required":false,"name":"include_embeddings","in":"query"},{"schema":{"type":"number","description":"Embedding vector dimension; required when embedding metadata is requested.","example":1536},"required":false,"name":"embedding_dimension","in":"query"},{"schema":{"type":"boolean","description":"Include the stored vector with requested embedding metadata. Use with the embedding inclusion flag.","example":false},"required":false,"name":"include_vector","in":"query"}],"responses":{"200":{"description":"File chunks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileChunkList"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases/{version}/files/{filePath}/chunks/{chunkId}":{"get":{"operationId":"getReleaseFileChunk","tags":["File Chunks"],"summary":"Get release file chunk","description":"Return one chunk for a file in a published release after verifying project read capability.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version from the route."},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","description":"URL-encoded file path for the chunked file."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","format":"uuid","description":"File chunk UUID."},"required":true,"name":"chunkId","in":"path"},{"schema":{"type":"boolean","default":false,"description":"Whether to include embedding metadata when available."},"required":false,"name":"include_embedding","in":"query"},{"schema":{"type":"number","description":"Embedding vector dimension; required when embedding metadata is requested.","example":1536},"required":false,"name":"embedding_dimension","in":"query"},{"schema":{"type":"boolean","description":"Include the stored vector with requested embedding metadata. Use with the embedding inclusion flag.","example":false},"required":false,"name":"include_vector","in":"query"}],"responses":{"200":{"description":"Chunk","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileChunk"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/chunks":{"get":{"operationId":"listProjectChunks","tags":["File Chunks"],"summary":"List project chunks","description":"List indexed chunks for a project for debugging, inspection, and search verification.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Offset cursor returned from `page_info.next` or `page_info.prev`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100,"description":"Maximum number of chunks to return, from 1 to 100."},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of project chunks.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Chunk ID."},"file_path":{"type":"string","description":"Source file path for this chunk."},"file_id":{"type":"string","format":"uuid","description":"Optional source file ID."},"file_version_id":{"type":"string","format":"uuid","description":"File version ID containing this chunk."},"index":{"type":"number","description":"Chunk index within the source file version."},"content":{"type":"string","description":"Indexed chunk text content."},"start_offset":{"type":"number","description":"Start character offset in the source file."},"end_offset":{"type":"number","description":"End character offset in the source file."},"token_count":{"type":"number","description":"Estimated token count for this chunk."}},"required":["id","file_path","file_version_id","index","content","start_offset","end_offset","token_count"]},"description":"Indexed chunks for the project."},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/embeddings":{"get":{"operationId":"listEmbeddings","tags":["Project embeddings"],"summary":"List embeddings","description":"List stored embedding summaries for a project and vector dimension.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","enum":["768","1024","1536","3072","4096"],"description":"Vector dimension: 768, 1024, 1536, 3072, or 4096."},"required":true,"name":"dimension","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":100,"description":"Maximum embeddings to return."},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0,"description":"Result offset."},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["created_at"],"default":"created_at","description":"Sort field. Defaults to \"created_at\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"List of embeddings.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Embedding ID."},"chunk_id":{"type":"string","description":"File chunk ID associated with the embedding."},"file_path":{"type":["string","null"],"description":"Source file path for the chunk, or null when unavailable."},"model_name":{"type":"string","description":"Embedding model name."},"model_provider":{"type":"string","description":"Embedding provider name."},"status":{"type":"string","enum":["ready","stale","missing"],"description":"Embedding lifecycle status."},"created_at":{"type":"string","description":"Embedding creation timestamp in ISO 8601 format."}},"required":["id","chunk_id","file_path","model_name","model_provider","status","created_at"]},"description":"Embedding summaries for the project."},"total":{"type":"number","description":"Total matching embeddings."},"limit":{"type":"number","description":"Page size used for the query."},"offset":{"type":"number","description":"Offset used for the query."}},"required":["data","total","limit","offset"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"operationId":"upsertEmbeddings","tags":["Project embeddings"],"summary":"Upsert embeddings","description":"Stores embeddings generated by clients for project file chunks.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chunk_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"Chunk IDs to upsert embeddings for."},"vectors":{"type":"array","items":{"type":"array","items":{"type":"number"},"maxItems":4096},"minItems":1,"maxItems":100,"description":"Embedding vectors aligned by index with `chunk_ids`."},"model":{"type":"object","properties":{"name":{"type":"string","description":"Model name, for example `text-embedding-3-small`."},"provider":{"type":"string","description":"Provider name, for example `openai`."},"dimension":{"type":["number","null"],"description":"Embedding vector dimension. Must be a supported dimension."}},"required":["name","provider","dimension"]}},"required":["chunk_ids","vectors","model"]}}}},"responses":{"200":{"description":"Upsert results.","content":{"application/json":{"schema":{"type":"object","properties":{"embeddings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Embedding ID."},"model":{"type":"string","description":"Embedding model name."},"status":{"type":"string","enum":["ready","stale","missing"],"description":"Embedding lifecycle status."},"created_at":{"type":"string","description":"Embedding creation timestamp in ISO 8601 format."}},"required":["id","model","status","created_at"]},"description":"Embeddings that were created or updated."},"created":{"type":"number","description":"Number of embeddings created."},"updated":{"type":"number","description":"Number of embeddings updated."}},"required":["embeddings","created","updated"]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable validation error."}},"required":["error"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/embeddings/{chunkId}":{"get":{"operationId":"getChunkEmbedding","tags":["Project embeddings"],"summary":"Get embedding","description":"Return embedding metadata and optionally the vector for a specific chunk.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Chunk ID."},"required":true,"name":"chunkId","in":"path"},{"schema":{"type":"boolean","default":true,"description":"Include raw vector data. Defaults to true."},"required":false,"name":"include_vector","in":"query"},{"schema":{"type":"string","enum":["768","1024","1536","3072","4096"],"description":"Vector dimension to retrieve."},"required":true,"name":"dimension","in":"query"}],"responses":{"200":{"description":"Embedding info with optional vector.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Embedding ID."},"chunk_id":{"type":"string","description":"File chunk ID associated with the embedding."},"model":{"type":"object","properties":{"name":{"type":"string","description":"Embedding model name."},"provider":{"type":"string","description":"Embedding provider name."},"dimension":{"type":"number","description":"Embedding vector dimension."}},"required":["name","provider","dimension"]},"status":{"type":"string","enum":["ready","stale","missing"],"description":"Embedding lifecycle status."},"vector":{"type":"array","items":{"type":"number"},"description":"Raw embedding vector when requested."},"created_at":{"type":"string","description":"Embedding creation timestamp in ISO 8601 format."}},"required":["id","chunk_id","model","status","created_at"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Chunk or embedding not found"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteChunkEmbedding","tags":["Project embeddings"],"summary":"Delete embedding","description":"Delete the embedding for a specific chunk and vector dimension.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Chunk ID."},"required":true,"name":"chunkId","in":"path"},{"schema":{"type":"string","enum":["768","1024","1536","3072","4096"],"description":"Vector dimension to delete."},"required":true,"name":"dimension","in":"query"}],"responses":{"200":{"description":"Delete result.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"number","description":"Number of embeddings deleted."}},"required":["deleted"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchName}/search":{"post":{"operationId":"searchBranchContent","tags":["Vector search"],"summary":"Search branch files with a vector","description":"Searches branch content using a precomputed embedding vector. Generate the vector with an embedding provider before sending the request.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name or ID. Use `main` to search the default project state."},"required":true,"name":"branchName","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentSearchBody"}}}},"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentSearchResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/environments/{environmentName}/search":{"post":{"operationId":"searchEnvironmentContent","tags":["Vector search"],"summary":"Search environment files with a vector","description":"Searches the named environment deployment using a precomputed embedding vector. An environment that does not exist for the project is not found; a deployed environment with no release yields no results.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Exact environment name from the route."},"required":true,"name":"environmentName","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentSearchBody"}}}},"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentSearchResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases/{version}/search":{"post":{"operationId":"searchReleaseContent","tags":["Vector search"],"summary":"Search release files with a vector","description":"Search release content using a precomputed embedding vector.","parameters":[{"schema":{"type":"string","description":"Project ID, slug, or domain from the authenticated context."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version to search."},"required":true,"name":"version","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentSearchBody"}}}},"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentSearchResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/knowledge/lookup":{"post":{"operationId":"lookupProjectKnowledge","tags":["Project knowledge"],"summary":"Look up project knowledge","description":"Search knowledge file paths and frontmatter. Falls back to a browse page when nothing matches. Supports cursor pagination, optional sharding, and explicit branch, environment, or release selection.","parameters":[{"schema":{"type":"string","description":"Project ID or slug."},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500,"description":"Text to match against knowledge file paths and frontmatter. On the first request, provide query without cursor."},"cursor":{"type":"string","minLength":1,"maxLength":13334,"description":"Opaque pagination token. Omit on the first request. To continue REST or MCP pagination, pass page_info.next from the previous response as cursor."},"lookup_target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["preview_branch"],"description":"Provide the kind."},"branch_id":{"type":["string","null"],"format":"uuid","description":"Branch to search. Omit or use null for the main branch (the default)."}},"required":["kind"],"additionalProperties":false,"description":"Search a working branch, the default scope when lookup_target is omitted."},{"type":"object","properties":{"kind":{"type":"string","enum":["environment"],"description":"Provide the kind."},"environment_id":{"type":"string","format":"uuid","description":"ID of the environment whose deployed release to search."},"environment_name":{"type":"string","minLength":1,"maxLength":255,"description":"Name of the environment (for example \"production\") whose deployed release to search."}},"required":["kind"],"additionalProperties":false,"description":"Search the release currently deployed to an environment. Provide environment_id or environment_name."},{"type":"object","properties":{"kind":{"type":"string","enum":["release"],"description":"Provide the kind."},"release_id":{"type":"string","format":"uuid","description":"ID of the release to search."},"release_version":{"type":"string","minLength":1,"maxLength":255,"description":"Version string of the release to search."}},"required":["kind"],"additionalProperties":false,"description":"Search a specific published release. Provide release_id or release_version."}],"description":"Optional. Omit to search the main preview branch (the default). Set this to target another preview branch, a deployed environment, or a published release; unresolved targets are returned as not found."},"limit":{"type":"integer","minimum":1,"maximum":12,"description":"Maximum number of results to return."},"shard_count":{"type":"integer","minimum":1,"maximum":8,"description":"Provide the shard count."},"shard_index":{"type":"integer","minimum":0,"description":"Provide the shard index."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Knowledge lookup results.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Resolved query used for scoring."},"mode":{"type":"string","enum":["search","browse"],"description":"search when results scored positively; browse when no positive matches exist."},"data":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Knowledge Markdown file path."},"matched_fields":{"type":"array","items":{"type":"string","description":"One matched field item associated with this tool result."},"description":"Matched fields. May include path and frontmatter keys, including keys not present in the returned preview."},"frontmatter":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Frontmatter key."},"value":{"type":"string","description":"Frontmatter value. Returned preview values may be truncated."}},"required":["key","value"],"description":"One frontmatter item associated with this tool result."},"description":"Preview of prioritized frontmatter: at most six fields, with values truncated to 160 characters."}},"required":["path","matched_fields","frontmatter"],"description":"One data item associated with this tool result."},"description":"Knowledge Markdown paths with frontmatter previews."},"page_info":{"type":"object","properties":{"self":{"type":["string","null"],"description":"Cursor supplied on this request, if any."},"first":{"type":["object","null"],"enum":[null],"description":"Reserved; first-page cursor is not emitted."},"next":{"type":["string","null"],"description":"Opaque cursor for the next REST or MCP page, if more results are available."},"prev":{"type":["string","null"],"description":"Reserved; previous-page cursor is not emitted."}},"required":["self","first","next","prev"],"description":"Pagination cursor values for traversing the result set."},"returned":{"type":"integer","minimum":0,"description":"The returned associated with this tool result."},"total_matches":{"type":"integer","minimum":0,"description":"Total number of matches found by the tool."},"shard":{"type":"object","properties":{"shard_index":{"type":"integer","minimum":0,"description":"The shard index associated with this tool result."},"shard_count":{"type":"integer","minimum":1,"description":"The shard count associated with this tool result."},"total_items":{"type":"integer","minimum":0,"description":"The total items associated with this tool result."}},"required":["shard_index","shard_count","total_items"],"description":"Structured shard details associated with this tool result."}},"required":["query","mode","data","page_info","returned","total_matches","shard"]}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Project or content target not found"}}}},"/integrations":{"get":{"operationId":"listIntegrations","tags":["Integration catalog"],"summary":"List integrations","description":"List available integrations.","parameters":[{"schema":{"type":"string","description":"Deprecated. The package determines the version."},"required":false,"name":"version","in":"query"},{"schema":{"type":"string","description":"Search query to filter integrations","example":"email"},"required":false,"name":"search","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only integrations with one of these availabilities (default, experimental, host_adapter). Comma-separated and/or repeated; duplicates are ignored; at most 16 values.","example":"default"},"required":false,"name":"availability","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only integrations with one of these authentication types (oauth2, oauth1, api-key, basic). Comma-separated and/or repeated; duplicates are ignored; at most 16 values.","example":"api-key,basic"},"required":false,"name":"auth_type","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only integrations in one of these categories. Comma-separated and/or repeated; duplicates are ignored; at most 16 values. Integrations without a category match no value.","example":"communication"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","description":"Cursor.","example":"gmail"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["name"],"default":"name","description":"Sort by display name, with integration name as the stable tie-breaker."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order. Defaults to \"asc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of integrations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Integration identifier","example":"gmail"},"display_name":{"type":"string","description":"Human-readable name","example":"Gmail"},"icon":{"type":"string","description":"Icon filename","example":"gmail.svg"},"icon_url":{"type":"string","format":"uri"},"description":{"type":"string","description":"Brief description","example":"Read and send emails via Gmail API"},"category":{"type":["string","null"],"description":"Connector category from the veryfront package, such as communication or development. Null when the package declares none.","example":"communication"},"availability":{"type":"string","enum":["default","experimental","host_adapter"],"description":"Why this deployment publishes the integration: default (supported everywhere), experimental (enabled by this deployment's experimental integrations setting; may be absent elsewhere) or host_adapter (an adapter-only connector this API drives with its own client).","example":"default"},"auth_type":{"type":"string","enum":["oauth2","oauth1","api-key","basic"],"description":"Authentication type","example":"oauth2"},"tool_count":{"type":"number","description":"Number of available tools","example":3},"prompt_count":{"type":"number","description":"Number of available prompts","example":2},"project_connections":{"type":"object","properties":{"connected":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0},"disconnected":{"type":"integer","minimum":0}},"required":["connected","expired","disconnected"]},"project_user_connections":{"type":"object","properties":{"connected":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0},"disconnected":{"type":"integer","minimum":0}},"required":["connected","expired","disconnected"]}},"required":["name","display_name","icon","description","category","availability","auth_type","tool_count","prompt_count","project_connections","project_user_connections"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"},"total":{"type":"number"}},"required":["data","page_info","total"]}}}},"400":{"description":"Invalid query parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integrations/{name}":{"get":{"operationId":"getIntegration","tags":["Integration catalog"],"summary":"Get integration","description":"Return an integration by name.","parameters":[{"schema":{"type":"string","description":"Integration name","example":"gmail"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","description":"Deprecated. The package determines the version."},"required":false,"name":"version","in":"query"}],"responses":{"200":{"description":"Integration details","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"icon":{"type":"string"},"icon_url":{"type":"string","format":"uri"},"description":{"type":"string"},"category":{"type":["string","null"],"description":"Connector category from the veryfront package, such as communication or development. Null when the package declares none.","example":"communication"},"availability":{"type":"string","enum":["default","experimental","host_adapter"],"description":"Why this deployment publishes the integration: default (supported everywhere), experimental (enabled by this deployment's experimental integrations setting; may be absent elsewhere) or host_adapter (an adapter-only connector this API drives with its own client).","example":"default"},"auth":{"type":"object","properties":{"type":{"type":"string","enum":["oauth2","oauth1","api-key","basic"],"description":"The auth type associated with this tool result."},"provider":{"type":"string"},"authorization_url":{"type":"string"},"token_url":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"optional_scopes":{"type":"array","items":{"type":"string"}},"callback_path":{"type":"string"},"required_apis":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"enable_url":{"type":"string"}},"required":["name","enable_url"]}}},"required":["type"]},"credential_env_var_names":{"type":"array","items":{"type":"string"},"description":"Environment variable names for the integration’s credentials. Empty if none are configured.","example":["VERCEL_TOKEN"]},"credential_requirement":{"type":"object","properties":{"mode":{"type":"string","enum":["oauth_connection","project_credentials","none"]},"managed_oauth":{"type":"boolean"},"byo_oauth_app_override":{"type":"object","properties":{"supported":{"type":"boolean"},"required":{"type":"boolean"},"client_id_env_var":{"type":["string","null"]},"client_secret_env_var":{"type":["string","null"]}},"required":["supported","required","client_id_env_var","client_secret_env_var"]},"mandatory_env_vars":{"type":"array","items":{"type":"string"}}},"required":["mode","managed_oauth","byo_oauth_app_override","mandatory_env_vars"]},"env_vars":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"sensitive":{"type":"boolean"},"default":{"type":"string"},"docs_url":{"type":"string"}},"required":["name","description","required","sensitive"]}},"tools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"requires_write":{"type":"boolean","description":"Whether write authority is required. Unknown side effects require write authority."}},"required":["id","name","description","requires_write"]}},"prompts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"prompt":{"type":"string"},"category":{"type":"string"},"icon":{"type":"string"}},"required":["id","title","prompt","category","icon"]}},"suggested_with":{"type":"array","items":{"type":"string"}},"config_schema":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string","enum":["select","multiselect","boolean","number"]},"label":{"type":"string"},"description":{"type":"string"},"default":{},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["value","label"]}},"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"}},"required":["key","type","label"]}}},"required":["version","fields"]},"setup_guide":{"type":"object","properties":{"title":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"docs_url":{"type":"string"},"code":{"type":"string"}},"required":["title","description"]}},"notes":{"type":"array","items":{"type":"string"}},"documentation":{"type":"string"}},"required":["steps"]},"project_connections":{"type":"object","properties":{"connected":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0},"disconnected":{"type":"integer","minimum":0}},"required":["connected","expired","disconnected"]},"project_user_connections":{"type":"object","properties":{"connected":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0},"disconnected":{"type":"integer","minimum":0}},"required":["connected","expired","disconnected"]}},"required":["name","display_name","icon","description","category","availability","auth","credential_env_var_names","credential_requirement","env_vars","tools","project_connections","project_user_connections"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integrations/{name}/icon":{"get":{"operationId":"getIntegrationIcon","tags":["Integration catalog"],"summary":"Get integration icon","description":"Return the SVG icon for an integration.","parameters":[{"schema":{"type":"string","description":"Integration name","example":"gmail"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","description":"Deprecated. The package determines the version."},"required":false,"name":"version","in":"query"}],"responses":{"200":{"description":"SVG icon","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/integrations":{"get":{"operationId":"listProjectIntegrations","tags":["Project integrations"],"summary":"List project integrations","description":"List integrations with their project configuration and connection status.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list."},"required":false,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries."},"required":false,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries.","name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["name","status"],"default":"name"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Project integration cards","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"page_info":{"type":"object","properties":{"self":{"type":["string","null"]},"first":{"type":"null"},"next":{"type":["string","null"]},"prev":{"type":["string","null"]}},"required":["self","first","next","prev"]},"data":{"type":"array","items":{"type":"object","properties":{"configured":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"display_name":{"type":"string"},"icon":{"type":"string"},"description":{"type":"string"},"auth_type":{"type":"string","enum":["oauth2","oauth1","api-key","basic"],"description":"The auth type associated with this tool result."},"tool_count":{"type":"integer","minimum":0},"prompt_count":{"type":"integer","minimum":0},"connected_for_project":{"type":"boolean"},"scope":{"type":"string","enum":["project","user"]},"allowed_tools":{"type":["array","null"],"items":{"type":"string"}},"config":{"type":"object","additionalProperties":{}},"execution_mode":{"type":"string","enum":["real","mock"],"description":"The execution mode associated with this tool result."},"project_connections":{"type":"object","properties":{"connected":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0},"disconnected":{"type":"integer","minimum":0}},"required":["connected","expired","disconnected"]},"project_user_connections":{"type":"object","properties":{"connected":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0},"disconnected":{"type":"integer","minimum":0}},"required":["connected","expired","disconnected"],"description":"Private connections belonging to the interactive viewer in this project. Zero for API keys and service credentials."},"resolution":{"type":"object","properties":{"catalog_available":{"type":"boolean"},"catalog_state":{"type":"string","enum":["available","removed"]},"policy":{"type":"object","properties":{"state":{"type":"string","enum":["absent","allowed","restricted"]},"scope":{"type":"string","enum":["project","user"]},"allowed_tools":{"type":["array","null"],"items":{"type":"string"}},"execution_mode":{"type":"string","enum":["real","mock"],"description":"The execution mode associated with this tool result."}},"required":["state","scope","allowed_tools","execution_mode"]},"credential_requirement":{"type":"object","properties":{"mode":{"type":"string","enum":["oauth_connection","project_credentials","none"]},"managed_oauth":{"type":"boolean"},"byo_oauth_app_override":{"type":"object","properties":{"supported":{"type":"boolean"},"required":{"type":"boolean"},"client_id_env_var":{"type":["string","null"]},"client_secret_env_var":{"type":["string","null"]}},"required":["supported","required","client_id_env_var","client_secret_env_var"]},"mandatory_env_vars":{"type":"array","items":{"type":"string"}}},"required":["mode","managed_oauth","byo_oauth_app_override","mandatory_env_vars"]},"connection_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","required","not_applicable","unknown"]},"scope":{"type":["string","null"],"enum":["project","user",null]},"connected_count":{"type":["integer","null"],"minimum":0}},"required":["status","scope","connected_count"]}},"required":["catalog_available","catalog_state","policy","credential_requirement","connection_readiness"]}},"required":["configured","created_at","updated_at","name","display_name","icon","description","auth_type","tool_count","prompt_count","connected_for_project","scope","allowed_tools","config","execution_mode","project_connections","project_user_connections","resolution"]}}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/integrations/{name}":{"get":{"operationId":"getProjectIntegration","tags":["Project integrations"],"summary":"Get project integration","description":"Return an integration with its project configuration and connection status.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Canonical integration__tool_id to inspect using metadata only."},"required":false,"description":"Canonical integration__tool_id to inspect using metadata only.","name":"tool_name","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Explicit visible OAuth connection. Requires tool_name."},"required":false,"description":"Explicit visible OAuth connection. Requires tool_name.","name":"connection_id","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Observed connection generation. Requires tool_name and connection_id."},"required":false,"description":"Observed connection generation. Requires tool_name and connection_id.","name":"expected_connection_generation_id","in":"query"}],"responses":{"200":{"description":"Project integration card","content":{"application/json":{"schema":{"type":"object","properties":{"configured":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"display_name":{"type":"string"},"icon":{"type":"string"},"description":{"type":"string"},"auth_type":{"type":"string","enum":["oauth2","oauth1","api-key","basic"],"description":"The auth type associated with this tool result."},"tool_count":{"type":"integer","minimum":0},"prompt_count":{"type":"integer","minimum":0},"connected_for_project":{"type":"boolean"},"scope":{"type":"string","enum":["project","user"]},"allowed_tools":{"type":["array","null"],"items":{"type":"string"}},"config":{"type":"object","additionalProperties":{}},"execution_mode":{"type":"string","enum":["real","mock"],"description":"The execution mode associated with this tool result."},"project_connections":{"type":"object","properties":{"connected":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0},"disconnected":{"type":"integer","minimum":0}},"required":["connected","expired","disconnected"]},"project_user_connections":{"type":"object","properties":{"connected":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0},"disconnected":{"type":"integer","minimum":0}},"required":["connected","expired","disconnected"],"description":"Private connections belonging to the interactive viewer in this project. Zero for API keys and service credentials."},"resolution":{"type":"object","properties":{"catalog_available":{"type":"boolean"},"catalog_state":{"type":"string","enum":["available","removed"]},"policy":{"type":"object","properties":{"state":{"type":"string","enum":["absent","allowed","restricted"]},"scope":{"type":"string","enum":["project","user"]},"allowed_tools":{"type":["array","null"],"items":{"type":"string"}},"execution_mode":{"type":"string","enum":["real","mock"],"description":"The execution mode associated with this tool result."}},"required":["state","scope","allowed_tools","execution_mode"]},"credential_requirement":{"type":"object","properties":{"mode":{"type":"string","enum":["oauth_connection","project_credentials","none"]},"managed_oauth":{"type":"boolean"},"byo_oauth_app_override":{"type":"object","properties":{"supported":{"type":"boolean"},"required":{"type":"boolean"},"client_id_env_var":{"type":["string","null"]},"client_secret_env_var":{"type":["string","null"]}},"required":["supported","required","client_id_env_var","client_secret_env_var"]},"mandatory_env_vars":{"type":"array","items":{"type":"string"}}},"required":["mode","managed_oauth","byo_oauth_app_override","mandatory_env_vars"]},"connection_readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","required","not_applicable","unknown"]},"scope":{"type":["string","null"],"enum":["project","user",null]},"connected_count":{"type":["integer","null"],"minimum":0}},"required":["status","scope","connected_count"]}},"required":["catalog_available","catalog_state","policy","credential_requirement","connection_readiness"]},"selected_readiness":{"type":"object","properties":{"version":{"type":"number","enum":[1],"description":"The version associated with this tool result."},"selection":{"type":"object","properties":{"integration":{"type":"string","description":"The integration associated with this tool result."},"state":{"type":"string","enum":["selected","missing","ambiguous","unavailable","stale","unknown"],"description":"The state associated with this tool result."},"mode":{"type":"string","enum":["oauth_connection","project_credentials","service_identity","mock","unknown"],"description":"The mode associated with this tool result."},"scope":{"type":["string","null"],"enum":["user","project",null],"description":"The scope associated with this tool result."},"project_id":{"type":"string","format":"uuid","description":"Project identifier associated with this result."},"tool_name":{"type":"string","description":"The tool name associated with this tool result."},"requested_connection_id":{"type":["string","null"],"format":"uuid","description":"The requested connection id associated with this tool result."},"connection_id":{"type":["string","null"],"format":"uuid","description":"The connection id associated with this tool result."},"connection_generation_id":{"type":["string","null"],"format":"uuid","description":"The connection generation id associated with this tool result."}},"required":["integration","state","mode","scope","project_id","tool_name","requested_connection_id","connection_id","connection_generation_id"],"description":"Structured selection details associated with this tool result."},"connection":{"type":"object","properties":{"state":{"type":"string","enum":["connected","expired","disconnected","revoked","missing","unknown","not_applicable"],"description":"The state associated with this tool result."}},"required":["state"],"description":"Structured connection details associated with this tool result."},"account":{"type":"object","properties":{"state":{"type":"string","enum":["recorded","unknown"],"description":"The state associated with this tool result."},"id":{"type":["string","null"],"description":"Unique identifier for the returned record."},"evidence":{"type":"string","enum":["stored_metadata","none"],"description":"The evidence associated with this tool result."},"display_name":{"type":["string","null"],"description":"The display name associated with this tool result."}},"required":["state","id","evidence","display_name"],"description":"Structured account details associated with this tool result."},"credentials":{"type":"object","properties":{"evidence":{"type":"string","enum":["connection_metadata","complete_key_presence","partial_key_presence","absent","not_applicable"],"description":"The evidence associated with this tool result."},"missing_keys":{"type":"array","items":{"type":"string","description":"One missing key item associated with this tool result."},"description":"List of missing keys associated with this tool result."}},"required":["evidence","missing_keys"],"description":"Structured credentials details associated with this tool result."},"local_eligibility":{"type":"object","properties":{"state":{"type":"string","enum":["eligible","blocked","unknown"],"description":"The state associated with this tool result."},"basis":{"type":"string","enum":["metadata_only"],"description":"The basis associated with this tool result."},"blockers":{"type":"array","items":{"type":"string","enum":["tool_unavailable","tool_permission_denied","connection_required","connection_selection_required","connection_unavailable","connection_stale","reconnect_required","credentials_missing","technical_configuration_blocked","selector_incompatible_with_mode"],"description":"One blocker item associated with this tool result."},"description":"List of blockers associated with this tool result."},"required_capability":{"type":"string","enum":["project.integrations.read","project.integrations.connect"],"description":"The required capability associated with this tool result."},"pending_checks":{"type":"array","items":{"type":"string","enum":["argument_validation","credential_value_validation","provider_authorization","credential_mode_resolution","mock_tool_availability","provider_resource_validation"],"description":"One pending check item associated with this tool result."},"description":"List of pending checks associated with this tool result."}},"required":["state","basis","blockers","required_capability","pending_checks"],"description":"Structured local eligibility details associated with this tool result."},"provider_verification":{"type":"object","properties":{"state":{"type":"string","enum":["not_checked"],"description":"The state associated with this tool result."}},"required":["state"],"description":"Structured provider verification details associated with this tool result."}},"required":["version","selection","connection","account","credentials","local_eligibility","provider_verification"],"description":"Structured selected readiness details associated with this tool result."}},"required":["configured","created_at","updated_at","name","display_name","icon","description","auth_type","tool_count","prompt_count","connected_for_project","scope","allowed_tools","config","execution_mode","project_connections","project_user_connections","resolution"]}}}},"400":{"description":"Invalid selected-tool or connection selector","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Project access denied","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or integration not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"putProjectIntegration","tags":["Project integrations"],"summary":"Upsert project integration","description":"Upserts project integration config for a single integration.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["project","user","endUser"]},"allowed_tools":{"type":["array","null"],"items":{"type":"string"}},"config":{"type":"object","additionalProperties":{}},"execution_mode":{"type":"string","enum":["real","mock"],"default":"real","description":"The execution mode associated with this tool result."}},"required":["scope","allowed_tools"]}}}},"responses":{"204":{"description":"Project integration updated"},"400":{"description":"Invalid integration config","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Integration not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteProjectIntegration","tags":["Project integrations"],"summary":"Delete project integration policy","description":"Delete project integration policy without revoking OAuth credentials.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"204":{"description":"Project integration policy deleted"},"404":{"description":"Integration not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/integrations/salesforce/objects":{"get":{"operationId":"listSalesforceObjects","tags":["Project integrations"],"summary":"List Salesforce objects","description":"List Salesforce sObjects visible to the connected Salesforce user for project data access configuration.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list."},"required":false,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries."},"required":false,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Salesforce object metadata","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"page_info":{"$ref":"#/components/schemas/PageInfo"},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"custom":{"type":"boolean"},"queryable":{"type":"boolean"},"createable":{"type":"boolean"},"updateable":{"type":"boolean"},"deletable":{"type":"boolean"},"deprecated_and_hidden":{"type":"boolean"}},"required":["name","label","custom","queryable","createable","updateable","deletable","deprecated_and_hidden"]}}},"required":["data"]}}}},"400":{"description":"Salesforce is not connected or object discovery failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/integrations/salesforce/objects/{object_name}/fields":{"get":{"operationId":"listSalesforceObjectFields","tags":["Project integrations"],"summary":"List Salesforce object fields","description":"List fields for a Salesforce sObject visible to the connected Salesforce user.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":true,"name":"object_name","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list."},"required":false,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries."},"required":false,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Salesforce object field metadata","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"page_info":{"$ref":"#/components/schemas/PageInfo"},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"reference_to":{"type":"array","items":{"type":"string"}},"relationship_name":{"type":["string","null"]},"nillable":{"type":"boolean"},"createable":{"type":"boolean"},"updateable":{"type":"boolean"},"filterable":{"type":"boolean"},"sortable":{"type":"boolean"},"id_lookup":{"type":"boolean"},"external_id":{"type":"boolean"},"calculated":{"type":"boolean"},"name_field":{"type":"boolean"}},"required":["name","label","type","reference_to","relationship_name","nillable","createable","updateable","filterable","sortable","id_lookup","external_id","calculated","name_field"]}}},"required":["data"]}}}},"400":{"description":"Salesforce is not connected or field discovery failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or Salesforce object not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/connect/session":{"post":{"operationId":"oauthCreateConnectSession","tags":["Integration OAuth"],"summary":"Create OAuth connect session","description":"Create a short-lived OAuth connect session for native apps.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"integration":{"type":"string","description":"Integration identifier to connect, for example github or slack."},"project_reference":{"type":"string","description":"Project UUID or slug that owns the connection."},"projectId":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"scope":{"type":"string","enum":["user","project"],"description":"Connection ownership within the project."},"redirect_uri":{"type":"string","maxLength":4096,"description":"Validated native or web redirect URI after OAuth completes."}},"required":["integration","scope","redirect_uri"],"additionalProperties":false}}}},"responses":{"200":{"description":"OAuth connect session created","content":{"application/json":{"schema":{"type":"object","properties":{"session_token":{"type":"string","description":"One-time OAuth connect session token for native app handoff."},"connect_url":{"type":"string","description":"OAuth connect URL that starts the provider consent flow."},"expires_at":{"type":"string","format":"date-time","description":"UTC expiry of this one-time handoff, using the stored session deadline. Open connect_url before this time. Provider consent has a separate lifecycle."}},"required":["session_token","connect_url","expires_at"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/connect/{integration}":{"get":{"operationId":"oauthConnect","tags":["Integration OAuth"],"summary":"Start OAuth connection","description":"Start an OAuth connection for an integration.","parameters":[{"schema":{"type":"string","description":"Integration identifier, for example github or gmail."},"required":true,"description":"Integration identifier, for example github or gmail.","name":"integration","in":"path"},{"schema":{"type":"string","description":"Project UUID or slug that owns the connection."},"required":false,"description":"Project UUID or slug that owns the connection.","name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"description":"Deprecated project ID or slug alias. Use project_reference.","name":"projectId","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"description":"Deprecated project ID or slug alias. Use project_reference.","name":"project_id","in":"query"},{"schema":{"type":"string","enum":["user","project"],"description":"Connection ownership within the project."},"required":false,"description":"Connection ownership within the project.","name":"scope","in":"query"},{"schema":{"type":"string","maxLength":4096,"description":"Dashboard-relative path to redirect to after OAuth completes."},"required":false,"description":"Dashboard-relative path to redirect to after OAuth completes.","name":"redirect","in":"query"},{"schema":{"type":"string","maxLength":4096,"description":"Absolute redirect URI for native or custom app OAuth flows."},"required":false,"description":"Absolute redirect URI for native or custom app OAuth flows.","name":"redirect_uri","in":"query"},{"schema":{"type":"string","description":"One-time native OAuth connect session token."},"required":false,"description":"One-time native OAuth connect session token.","name":"session_token","in":"query"}],"responses":{"302":{"description":"Redirect to provider consent screen"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/callback/{integration}":{"get":{"operationId":"oauthCallback","tags":["Integration OAuth"],"summary":"Handle OAuth callback","description":"Handles the OAuth provider callback.","parameters":[{"schema":{"type":"string","description":"Integration identifier returned from the provider callback path."},"required":true,"description":"Integration identifier returned from the provider callback path.","name":"integration","in":"path"},{"schema":{"type":"string","maxLength":8192,"description":"Authorization code returned by the OAuth provider."},"required":false,"description":"Authorization code returned by the OAuth provider.","name":"code","in":"query"},{"schema":{"type":"string","description":"Opaque OAuth state token created by the connect endpoint."},"required":false,"description":"Opaque OAuth state token created by the connect endpoint.","name":"state","in":"query"},{"schema":{"type":"string","maxLength":8192,"description":"Provider error code when the OAuth consent flow fails."},"required":false,"description":"Provider error code when the OAuth consent flow fails.","name":"error","in":"query"},{"schema":{"type":"string","description":"Human-readable provider error description."},"required":false,"description":"Human-readable provider error description.","name":"error_description","in":"query"}],"responses":{"302":{"description":"Redirect to dashboard"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/status/{integration}":{"get":{"operationId":"oauthStatus","tags":["Integration OAuth"],"summary":"Get OAuth status","description":"Return OAuth connection status for an integration.","parameters":[{"schema":{"type":"string","description":"Integration identifier returned from the provider callback path."},"required":true,"description":"Integration identifier returned from the provider callback path.","name":"integration","in":"path"},{"schema":{"type":"string","description":"Project UUID or slug that owns the connection."},"required":false,"description":"Project UUID or slug that owns the connection.","name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"description":"Deprecated project ID or slug alias. Use project_reference.","name":"projectId","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"description":"Deprecated project ID or slug alias. Use project_reference.","name":"project_id","in":"query"},{"schema":{"type":"string","enum":["user","project"],"description":"Connection ownership within the project."},"required":true,"description":"Connection ownership within the project.","name":"scope","in":"query"}],"responses":{"200":{"description":"Connection status","content":{"application/json":{"schema":{"type":"object","properties":{"connected":{"type":"boolean","description":"Whether the integration currently has a usable OAuth token."},"integration":{"type":"string","description":"Integration identifier checked for OAuth connectivity."},"connectionId":{"type":"string","format":"uuid","description":"Retained legacy alias for connection_id; carries the same value."},"connectionGenerationId":{"type":"string","format":"uuid","description":"Retained legacy alias for connection_generation_id; carries the same value."},"connection_id":{"type":"string","format":"uuid","description":"Exact current connection row; omitted when disconnected."},"connection_generation_id":{"type":"string","format":"uuid","description":"Current destructive generation; omitted when disconnected."}},"required":["connected","integration"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/token/{integration}":{"get":{"operationId":"oauthGetToken","tags":["Integration OAuth"],"summary":"Get access token","description":"Returns a valid access token for a project integration connection.\n\nErrors use the Problem response format:\n\n- Unknown integration: `404`, without `connect_url`.\n- Integration without OAuth support: `400`, without `connect_url`.\n- Missing or unusable OAuth connection: `404`, with a `connect_url` hint.\n- Provider does not respond to token refresh: `503` with `provider-unavailable`.\n\nOther failures retain their status code; unexpected failures return `500`. Do not treat these other failures as retryable provider outages.","parameters":[{"schema":{"type":"string","description":"Integration identifier, for example github or slack."},"required":true,"description":"Integration identifier, for example github or slack.","name":"integration","in":"path"},{"schema":{"type":"string","description":"Project UUID or slug. Optional when the authenticated principal has a bound project; required otherwise."},"required":false,"description":"Project UUID or slug. Optional when the authenticated principal has a bound project; required otherwise.","name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"description":"Deprecated project ID or slug alias. Use project_reference.","name":"projectId","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"description":"Deprecated project ID or slug alias. Use project_reference.","name":"project_id","in":"query"}],"responses":{"200":{"description":"Valid access token for the requested integration","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","description":"Valid OAuth access token for the requested integration."},"accessToken":{"type":"string","description":"Retained legacy alias for access_token; carries the same value."}},"required":["access_token","accessToken"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/OAuthConnectionProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/disconnect/{integration}":{"post":{"operationId":"oauthDisconnect","tags":["Integration OAuth"],"summary":"Disconnect OAuth integration","description":"Disconnects an OAuth integration.","parameters":[{"schema":{"type":"string","description":"Integration identifier returned from the provider callback path."},"required":true,"description":"Integration identifier returned from the provider callback path.","name":"integration","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"project_reference":{"type":"string","description":"Project UUID or slug that owns the connection."},"projectId":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"scope":{"type":"string","enum":["user","project"],"description":"Connection ownership within the project."},"connection_id":{"type":"string","format":"uuid","description":"Exact connection row to disconnect, as returned by status."},"connectionId":{"type":"string","format":"uuid","description":"Retained legacy alias for connection_id. When both are sent they must carry the same value."}},"required":["scope","connection_id"],"additionalProperties":false},{"type":"object","properties":{"project_reference":{"type":"string","description":"Project UUID or slug that owns the connection."},"projectId":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"scope":{"type":"string","enum":["user","project"],"description":"Connection ownership within the project."},"connectionId":{"type":"string","format":"uuid","description":"Retained legacy alias for connection_id. When both are sent they must carry the same value."}},"required":["scope","connectionId"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Disconnected","content":{"application/json":{"schema":{"type":"object","properties":{"disconnected":{"type":"boolean","description":"Whether a stored OAuth token was disconnected."},"revoked":{"type":"boolean","description":"Whether the upstream token was revoked when disconnecting."}},"required":["disconnected","revoked"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/connections":{"get":{"operationId":"listConnections","tags":["Connections"],"summary":"List connections","description":"List the current user's project-user connections and shared connections across accessible projects.","parameters":[{"schema":{"type":"string","description":"Filter by integration identifier","example":"github"},"required":false,"name":"integration","in":"query"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["project","status","created_at"],"default":"project"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Accessible connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionList"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integrations/{name}/connections":{"get":{"operationId":"listIntegrationConnections","tags":["Connections"],"summary":"List integration connections","description":"List the current user's project-user connections and shared connections across accessible projects for one integration.","parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["project","status","created_at"],"default":"project"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Connections for the integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionList"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/connections":{"get":{"operationId":"listProjectConnections","tags":["Connections"],"summary":"List project connections","description":"List shared project connections and the authenticated viewer's private project-user connections.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Filter by integration identifier","example":"github"},"required":false,"name":"integration","in":"query"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["project","status","created_at"],"default":"project"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Shared project connections and the authenticated viewer's private project-user connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionList"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or integration not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/integrations/{name}/connections":{"get":{"operationId":"listProjectIntegrationConnections","tags":["Connections"],"summary":"List project integration connections","description":"List shared project connections and the authenticated viewer's private project-user connections.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["project","status","created_at"],"default":"project"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Shared project connections and the authenticated viewer's private project-user connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionList"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or integration not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integrations/{integration}/tools":{"get":{"operationId":"listToolsForIntegration","tags":["Integration tools"],"summary":"List tools for integration","description":"Lists the tools of a single integration available to the current user and project. Integration-scoped successor of POST /integrations/tools/list.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[^\\s/]+$","description":"Integration name from the catalog","example":"github"},"required":true,"name":"integration","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list."},"required":false,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries."},"required":false,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries.","name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"pattern":"^[^\\s/]+$","description":"Integration name from the catalog","example":"github"},"required":false,"description":"Exact integration filter, applied before pagination. Must match the path on integration-scoped routes.","name":"integration","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Case-sensitive substring filter on canonical tool names, applied before pagination."},"required":false,"description":"Case-sensitive substring filter on canonical tool names, applied before pagination.","name":"name","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Canonical tool-name order. Defaults to asc when paging; omitted on legacy unpaged requests to retain catalog order."},"required":false,"description":"Canonical tool-name order. Defaults to asc when paging; omitted on legacy unpaged requests to retain catalog order.","name":"order","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Optional immutable project UUID precondition, compared case-insensitively after project resolution and authorization. It never selects a project. A mismatch fails with validation-failed before tool discovery or execution, including for project-bound callers. Send exactly one value.","example":"11111111-1111-4111-8111-111111111111"},"required":false,"name":"x-veryfront-expected-project-id","in":"header"},{"schema":{"type":"string","description":"Required for callers without a project-bound context. The slug is resolved and authorized before discovery or execution. A project-bound context takes precedence and ignores this header, including conflicting values.","example":"example-project"},"required":false,"name":"x-veryfront-project-slug","in":"header"}],"responses":{"200":{"description":"Available tools for the integration","headers":{"x-veryfront-tool-preconditions":{"description":"Supported tool-call preconditions. Clients requiring a connection generation must observe connection_generation_id before dispatch and on the call response.","schema":{"type":"string","enum":["project_id,connection_generation_id"]}},"x-veryfront-project-id":{"description":"Effective authorized project ID used for this request, regardless of the supplied slug.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Tool name in integration:tool-id format","example":"github__list-repos"},"description":{"type":"string","description":"Tool description"},"inputSchema":{"type":"object","additionalProperties":{},"description":"JSON Schema for tool input"}},"required":["name","description","inputSchema"]}},"total":{"type":"integer","minimum":0},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["tools"]}}}},"400":{"description":"Invalid integration path parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Project access denied","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integrations/{integration}/tools/{tool}/call":{"post":{"operationId":"callToolForIntegration","tags":["Integration tools"],"summary":"Call tool for integration","description":"Calls one tool of an integration. Tool identity comes from the path; integration-scoped successor of POST /integrations/tools/call.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[^\\s/]+$","description":"Integration name from the catalog","example":"github"},"required":true,"name":"integration","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[^\\s/]+$","description":"Tool ID within the integration.","example":"list-repos"},"required":true,"name":"tool","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Optional immutable project UUID precondition, compared case-insensitively after project resolution and authorization. It never selects a project. A mismatch fails with validation-failed before tool discovery or execution, including for project-bound callers. Send exactly one value.","example":"11111111-1111-4111-8111-111111111111"},"required":false,"name":"x-veryfront-expected-project-id","in":"header"},{"schema":{"type":"string","description":"Required for callers without a project-bound context. The slug is resolved and authorized before discovery or execution. A project-bound context takes precedence and ignores this header, including conflicting values.","example":"example-project"},"required":false,"name":"x-veryfront-project-slug","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"arguments":{"type":"object","additionalProperties":{},"default":{},"description":"Tool arguments. Unknown top-level body fields are rejected, so provider arguments must be sent here."},"run_id":{"type":"string","description":"Agent run ID for validating run-declared integration tools"},"agent_id":{"type":"string","description":"Agent ID for validating run-declared integration tools"},"connection_id":{"type":"string","format":"uuid","description":"Optional exact connected account to use for this call"},"expected_connection_generation_id":{"type":"string","format":"uuid","description":"Require this observed generation of the selected connection. Requires connection_id; stale selections fail before credential or provider effects."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool execution result","headers":{"x-veryfront-tool-preconditions":{"description":"Supported tool-call preconditions. Clients requiring a connection generation must observe connection_generation_id before dispatch and on the call response.","schema":{"type":"string","enum":["project_id,connection_generation_id"]}},"x-veryfront-project-id":{"description":"Effective authorized project ID used for this request, regardless of the supplied slug.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"data":{"type":"string"},"mimeType":{"type":"string"}},"required":["type","data","mimeType"]},{"type":"object","properties":{"type":{"type":"string","enum":["audio"]},"data":{"type":"string"},"mimeType":{"type":"string"}},"required":["type","data","mimeType"]},{"type":"object","properties":{"type":{"type":"string","enum":["resource"]},"resource":{"anyOf":[{"type":"object","properties":{"uri":{"type":"string"},"mimeType":{"type":"string"},"text":{"type":"string"}},"required":["uri","text"]},{"type":"object","properties":{"uri":{"type":"string"},"mimeType":{"type":"string"},"blob":{"type":"string"}},"required":["uri","blob"]}]}},"required":["type","resource"]},{"type":"object","properties":{"type":{"type":"string","enum":["resource_link"]},"uri":{"type":"string"},"name":{"type":"string"}},"required":["type","uri","name"]}]}},"structuredContent":{"type":"object","additionalProperties":{}},"isError":{"type":"boolean"},"_meta":{"type":"object","additionalProperties":{}}}}}}},"400":{"description":"Invalid path parameters or request body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Project access denied","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"integration-connection-stale: the expected connection generation was replaced; read the connection again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integrations/tools/call":{"post":{"operationId":"callIntegrationTool","tags":["Integration tools"],"summary":"Call integration tool","description":"Calls an integration tool.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Optional immutable project UUID precondition, compared case-insensitively after project resolution and authorization. It never selects a project. A mismatch fails with validation-failed before tool discovery or execution, including for project-bound callers. Send exactly one value.","example":"11111111-1111-4111-8111-111111111111"},"required":false,"name":"x-veryfront-expected-project-id","in":"header"},{"schema":{"type":"string","description":"Required for callers without a project-bound context. The slug is resolved and authorized before discovery or execution. A project-bound context takes precedence and ignores this header, including conflicting values.","example":"example-project"},"required":false,"name":"x-veryfront-project-slug","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Tool name","example":"github__list-repos"},"arguments":{"type":"object","additionalProperties":{},"default":{},"description":"Tool arguments. Unknown top-level body fields are rejected, so provider arguments must be sent here."},"run_id":{"type":"string","description":"Agent run ID for validating run-declared integration tools"},"agent_id":{"type":"string","description":"Agent ID for validating run-declared integration tools"},"connection_id":{"type":"string","format":"uuid","description":"Optional exact connected account to use for this call"},"expected_connection_generation_id":{"type":"string","format":"uuid","description":"Require this observed generation of the selected connection. Requires connection_id; stale selections fail before credential or provider effects."}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool execution result","headers":{"x-veryfront-tool-preconditions":{"description":"Supported tool-call preconditions. Clients requiring a connection generation must observe connection_generation_id before dispatch and on the call response.","schema":{"type":"string","enum":["project_id,connection_generation_id"]}},"x-veryfront-project-id":{"description":"Effective authorized project ID used for this request, regardless of the supplied slug.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"data":{"type":"string"},"mimeType":{"type":"string"}},"required":["type","data","mimeType"]},{"type":"object","properties":{"type":{"type":"string","enum":["audio"]},"data":{"type":"string"},"mimeType":{"type":"string"}},"required":["type","data","mimeType"]},{"type":"object","properties":{"type":{"type":"string","enum":["resource"]},"resource":{"anyOf":[{"type":"object","properties":{"uri":{"type":"string"},"mimeType":{"type":"string"},"text":{"type":"string"}},"required":["uri","text"]},{"type":"object","properties":{"uri":{"type":"string"},"mimeType":{"type":"string"},"blob":{"type":"string"}},"required":["uri","blob"]}]}},"required":["type","resource"]},{"type":"object","properties":{"type":{"type":"string","enum":["resource_link"]},"uri":{"type":"string"},"name":{"type":"string"}},"required":["type","uri","name"]}]}},"structuredContent":{"type":"object","additionalProperties":{}},"isError":{"type":"boolean"},"_meta":{"type":"object","additionalProperties":{}}}}}}},"400":{"description":"Invalid project selector or request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Project access denied","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"integration-connection-stale: the expected connection generation was replaced; read the connection again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integrations/tools/list":{"post":{"operationId":"listIntegrationTools","tags":["Integration tools"],"summary":"List integration tools","description":"Lists integration tools available to the current user and project.\n\nWithout query parameters, returns the complete legacy list, including bare mock tool IDs. Any discovery query parameter selects canonical names qualified by integration.\n\n`limit` or `cursor` enables pagination and adds `total` and `page_info`. Filters without pagination return all matching tools.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list."},"required":false,"description":"Opt in to paged results. Omit limit and cursor to retain the complete legacy list.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries."},"required":false,"description":"Opaque continuation from page_info. A cursor without limit uses 20 entries.","name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"pattern":"^[^\\s/]+$","description":"Integration name from the catalog","example":"github"},"required":false,"description":"Exact integration filter, applied before pagination. Must match the path on integration-scoped routes.","name":"integration","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Case-sensitive substring filter on canonical tool names, applied before pagination."},"required":false,"description":"Case-sensitive substring filter on canonical tool names, applied before pagination.","name":"name","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Canonical tool-name order. Defaults to asc when paging; omitted on legacy unpaged requests to retain catalog order."},"required":false,"description":"Canonical tool-name order. Defaults to asc when paging; omitted on legacy unpaged requests to retain catalog order.","name":"order","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Optional immutable project UUID precondition, compared case-insensitively after project resolution and authorization. It never selects a project. A mismatch fails with validation-failed before tool discovery or execution, including for project-bound callers. Send exactly one value.","example":"11111111-1111-4111-8111-111111111111"},"required":false,"name":"x-veryfront-expected-project-id","in":"header"},{"schema":{"type":"string","description":"Required for callers without a project-bound context. The slug is resolved and authorized before discovery or execution. A project-bound context takes precedence and ignores this header, including conflicting values.","example":"example-project"},"required":false,"name":"x-veryfront-project-slug","in":"header"}],"responses":{"200":{"description":"Available integration tools","headers":{"x-veryfront-tool-preconditions":{"description":"Supported tool-call preconditions. Clients requiring a connection generation must observe connection_generation_id before dispatch and on the call response.","schema":{"type":"string","enum":["project_id,connection_generation_id"]}},"x-veryfront-project-id":{"description":"Effective authorized project ID used for this request, regardless of the supplied slug.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Tool name in integration:tool-id format","example":"github__list-repos"},"description":{"type":"string","description":"Tool description"},"inputSchema":{"type":"object","additionalProperties":{},"description":"JSON Schema for tool input"}},"required":["name","description","inputSchema"]}},"total":{"type":"integer","minimum":0},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["tools"]}}}},"400":{"description":"Invalid project selector or request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Project access denied","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/channels":{"get":{"operationId":"listChannelBindings","tags":["Channel Bindings"],"summary":"List channel bindings","description":"List channel bindings for a project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"responses":{"200":{"description":"Project channel bindings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"binding_id":{"type":"string","format":"uuid"},"installation_id":{"type":["string","null"],"format":"uuid"},"platform":{"type":"string","enum":["slack"]},"name":{"type":["string","null"]},"assistant_id":{"type":["string","null"],"minLength":1},"enabled":{"type":"boolean"},"platform_team_id":{"type":["string","null"]},"platform_bot_id":{"type":["string","null"]},"workspace_name":{"type":["string","null"]},"respond_to":{"type":"string","enum":["mentions","direct_messages","all"]},"allowed_channels":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["connected","needs_reauth","error"]},"welcome_message":{"type":["string","null"]},"error_message":{"type":["string","null"]},"max_response_tokens":{"type":["integer","null"],"exclusiveMinimum":0},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"},"resolved_target":{"type":"object","properties":{"runtime_target":{"type":"object","properties":{"kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"resolved_environment":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]}},"required":["id","name"]},"resolved_branch":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"resolved_deployment":{"type":["object","null"],"properties":{"id":{"type":"string"},"runtime_version":{"type":["string","null"]},"deployment_revision":{"type":["string","null"]},"last_deployed_at":{"type":["string","null"]}},"required":["id","runtime_version","deployment_revision","last_deployed_at"]},"resolved_managed_domain":{"type":["object","null"],"properties":{"domain":{"type":"string"},"health_url":{"type":["string","null"]}},"required":["domain","health_url"]},"resolved_invoke_mode":{"type":["string","null"],"enum":["dispatch_override","managed_domain",null]},"last_resolution_error":{"type":["object","null"],"properties":{"code":{"type":"string"},"retryable":{"type":"boolean"},"message":{"type":"string"}},"required":["code","retryable","message"]}},"required":["runtime_target","resolved_environment","resolved_branch","resolved_deployment","resolved_managed_domain","resolved_invoke_mode","last_resolution_error"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","platform","enabled","platform_team_id","platform_bot_id","respond_to","allowed_channels","status","runtime_target_kind","resolved_target","created_at","updated_at"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createChannelBinding","tags":["Channel Bindings"],"summary":"Create channel binding","description":"Create a new channel binding for a project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["slack"]},"name":{"type":"string","minLength":1,"maxLength":255},"assistant_id":{"type":"string","minLength":1},"respond_to":{"type":"string","enum":["mentions","direct_messages","all"]},"allowed_channels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"maxItems":250},"welcome_message":{"type":["string","null"],"maxLength":4000},"error_message":{"type":["string","null"],"maxLength":4000},"max_response_tokens":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":65536},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}},"required":["platform","assistant_id"]}}}},"responses":{"201":{"description":"Created channel binding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelBinding"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/channels/bindings/{binding_id}":{"get":{"operationId":"getChannelBinding","tags":["Channel Bindings"],"summary":"Get channel binding","description":"Return a single channel binding for the project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"binding_id","in":"path"}],"responses":{"200":{"description":"Channel binding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelBinding"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updateChannelBinding","tags":["Channel Bindings"],"summary":"Update channel binding","description":"Update a specific channel binding.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"binding_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"assistant_id":{"type":"string","minLength":1},"respond_to":{"type":"string","enum":["mentions","direct_messages","all"]},"allowed_channels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"maxItems":250},"welcome_message":{"type":["string","null"],"maxLength":4000},"error_message":{"type":["string","null"],"maxLength":4000},"max_response_tokens":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":65536},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}}}}}},"responses":{"200":{"description":"Updated channel binding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelBinding"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deleteChannelBinding","tags":["Channel Bindings"],"summary":"Delete channel binding","description":"Delete a specific channel binding.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"binding_id","in":"path"}],"responses":{"204":{"description":"Channel binding deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/channels/bindings/{binding_id}/test":{"post":{"operationId":"sendBindingTestMessage","tags":["Channel Bindings"],"summary":"Send binding test message","description":"Send a test message through a specific channel binding.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"binding_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channel_id":{"type":"string","minLength":1,"maxLength":255},"text":{"type":"string","minLength":1,"maxLength":4000}},"required":["channel_id"]}}}},"responses":{"200":{"description":"Test message sent","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"channel_id":{"type":"string"},"ts":{"type":["string","null"]}},"required":["ok","channel_id","ts"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/channels/{platform}":{"get":{"operationId":"getPlatformChannelBinding","tags":["Channel Platforms"],"summary":"Get platform channel binding","description":"Return the channel binding for a platform compatibility route.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","enum":["slack"]},"required":true,"name":"platform","in":"path"}],"responses":{"200":{"description":"Channel binding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelBinding"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"operationId":"updatePlatformChannelBinding","tags":["Channel Platforms"],"summary":"Update platform channel binding","description":"Update the channel binding for a platform compatibility route.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","enum":["slack"]},"required":true,"name":"platform","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"assistant_id":{"type":"string","minLength":1},"respond_to":{"type":"string","enum":["mentions","direct_messages","all"]},"allowed_channels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"maxItems":250},"welcome_message":{"type":["string","null"],"maxLength":4000},"error_message":{"type":["string","null"],"maxLength":4000},"max_response_tokens":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":65536},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":["string","null"],"format":"uuid"},"target_branch_id":{"type":["string","null"],"format":"uuid"}}}}}},"responses":{"200":{"description":"Updated channel binding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelBinding"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"deletePlatformChannelBinding","tags":["Channel Platforms"],"summary":"Delete platform channel binding","description":"Delete the channel binding for a platform compatibility route.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","enum":["slack"]},"required":true,"name":"platform","in":"path"}],"responses":{"204":{"description":"Channel binding deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/channels/{platform}/test":{"post":{"operationId":"sendPlatformTestMessage","tags":["Channel Platforms"],"summary":"Send platform test message","description":"Send a test message through the platform compatibility route.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","enum":["slack"]},"required":true,"name":"platform","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channel_id":{"type":"string","minLength":1,"maxLength":255},"text":{"type":"string","minLength":1,"maxLength":4000}},"required":["channel_id"]}}}},"responses":{"200":{"description":"Test message sent","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"channel_id":{"type":"string"},"ts":{"type":["string","null"]}},"required":["ok","channel_id","ts"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/channels/assistants":{"get":{"operationId":"listTargetAssistants","tags":["Channel Assistants"],"summary":"List target assistants","description":"List assistants for the selected channel target.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","enum":["main_branch","environment","preview_branch"],"default":"main_branch"},"required":false,"name":"runtime_target_kind","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_environment_id","in":"query"},{"schema":{"type":["string","null"],"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Runtime assistants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"description":{"type":["string","null"]},"model":{"type":["string","null"]}},"required":["id","name"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/projects/{project_reference}/channels/slack/conversations":{"get":{"operationId":"listSlackChannels","tags":["Slack Channels"],"summary":"List Slack channels","description":"List public and private Slack channels available to the connected Slack app.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","maxLength":255},"required":false,"name":"query","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":200,"default":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Slack channels","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"is_private":{"type":"boolean"},"is_archived":{"type":"boolean"}},"required":["id","name","is_private","is_archived"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/webhooks/channels/{platform}":{"post":{"operationId":"receiveChannelWebhooks","tags":["Channel delivery"],"summary":"Receive channel webhooks","description":"Receives inbound webhooks for channel integrations.","parameters":[{"schema":{"type":"string","enum":["slack"]},"required":true,"name":"platform","in":"path"}],"responses":{"200":{"description":"Webhook accepted or URL verification challenge returned","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OkResponse"},{"type":"object","properties":{"challenge":{"type":"string"}},"required":["challenge"]}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Invalid signature or stale timestamp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-audience":"component-internal"}},"/providers/{provider}/files":{"get":{"operationId":"providerListFiles","tags":["Provider Files"],"summary":"List provider files","description":"List provider files with the caller's user-scoped connection.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Optional project UUID or slug that scopes the caller's provider connection."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"},{"schema":{"type":"string","description":"Optional provider folder path to list."},"required":false,"name":"path","in":"query"},{"schema":{"type":"string","description":"Provider pagination cursor returned from a previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","description":"Maximum number of entries to request from the provider. Capped at 200.","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"File listing","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProviderFile"},"description":"Provider files and folders."},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}},"post":{"operationId":"providerUploadFile","tags":["Provider Files"],"summary":"Upload provider file","description":"Upload base64-encoded file content to an external provider folder.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_reference":{"type":"string","description":"Project UUID or slug that scopes the caller's provider connection."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"projectId":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"parent_id":{"type":"string","description":"Provider folder ID where the file should be created."},"file_name":{"type":"string","description":"File name to create in the provider."},"content":{"type":"string","maxLength":10000000,"description":"Base64-encoded file content. Maximum encoded size is 10 MB."},"mime_type":{"type":"string","description":"MIME type for the uploaded file."}},"required":["parent_id","file_name","content","mime_type"]}}}},"responses":{"201":{"description":"Created file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderFile"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}}},"/providers/{provider}/files/{file_id}":{"get":{"operationId":"providerGetFile","tags":["Provider Files"],"summary":"Get provider file","description":"Return provider file or folder metadata using the caller's own project-bound provider connection.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Provider-specific file or folder identifier."},"required":true,"name":"file_id","in":"path"},{"schema":{"type":"string","description":"Optional project UUID or slug that scopes the caller's provider connection."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"File metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderFile"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}},"put":{"operationId":"providerUpdateFile","tags":["Provider Files"],"summary":"Update provider file","description":"Replaces a provider file with base64-encoded content.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Provider-specific file or folder identifier."},"required":true,"name":"file_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_reference":{"type":"string","description":"Project UUID or slug that scopes the caller's provider connection."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"projectId":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"content":{"type":"string","maxLength":10000000,"description":"Base64-encoded replacement file content. Maximum encoded size is 10 MB."}},"required":["content"]}}}},"responses":{"200":{"description":"Updated file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderFile"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}},"delete":{"operationId":"providerDeleteFile","tags":["Provider Files"],"summary":"Delete provider file","description":"Delete a file or folder from an external storage provider.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Provider-specific file or folder identifier."},"required":true,"name":"file_id","in":"path"},{"schema":{"type":"string","description":"Project UUID or slug that scopes the caller's provider connection."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"}],"responses":{"204":{"description":"File deleted"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}}},"/providers/{provider}/files/{file_id}/move":{"post":{"operationId":"providerMoveFile","tags":["Provider Files"],"summary":"Move provider file","description":"Moves or renames a file in an external storage provider.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Provider-specific file or folder identifier."},"required":true,"name":"file_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_reference":{"type":"string","description":"Project UUID or slug that scopes the caller's provider connection."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"projectId":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"new_parent_id":{"type":"string","description":"Destination provider folder ID."},"new_name":{"type":"string","description":"Optional new provider file name."}},"required":["new_parent_id"]}}}},"responses":{"200":{"description":"Moved file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderFile"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}}},"/providers/{provider}/files/{file_id}/import":{"post":{"operationId":"providerImportFile","tags":["Provider Files"],"summary":"Import provider file","description":"Import a provider file into Veryfront storage after validating provider access and storage quota.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Provider-specific file or folder identifier."},"required":true,"name":"file_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_reference":{"type":"string","description":"Optional project UUID or slug that scopes the caller's provider connection."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"projectId":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"base_path":{"type":"string","description":"Optional destination folder path in Veryfront storage."},"timestamp_prefix":{"type":"boolean","description":"When true, prefixes the imported file name with the current timestamp."}}}}}},"responses":{"200":{"description":"Import result with GCS path reference","content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"string","description":"Veryfront upload ID created for the imported file."},"gcs_path":{"type":"string","description":"Destination object path in Veryfront storage."},"file_name":{"type":"string","description":"Original provider file name."},"content_type":{"type":"string","description":"Imported file content type."},"size":{"type":"number","description":"Imported file size in bytes."}},"required":["upload_id","gcs_path","file_name","content_type","size"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"402":{"description":"Payment required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/QuotaProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderError"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}}},"/providers/{provider}/folders":{"post":{"operationId":"providerCreateFolder","tags":["Provider Folders"],"summary":"Create provider folder","description":"Create a folder in an external storage provider.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_reference":{"type":"string","description":"Project UUID or slug that scopes the caller's provider connection."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"projectId":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"parent_id":{"type":"string","description":"Provider folder ID where the folder should be created."},"name":{"type":"string","description":"Folder name to create in the provider."}},"required":["parent_id","name"]}}}},"responses":{"201":{"description":"Created folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderFile"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}}},"/providers/{provider}/search":{"get":{"operationId":"providerSearchFiles","tags":["Provider Search"],"summary":"Search provider files","description":"Search provider files with the caller's user-scoped connection.","parameters":[{"schema":{"type":"string","enum":["onedrive","sharepoint","drive"],"description":"External storage provider identifier: `onedrive`, `sharepoint`, or `drive` (Google Drive)."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Project UUID or slug that scopes the caller's provider connection."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Search text to find provider files."},"required":true,"name":"query","in":"query"},{"schema":{"type":"string","description":"Optional provider folder ID to scope the search."},"required":false,"name":"folder_id","in":"query"},{"schema":{"type":"string","description":"Provider pagination cursor returned from a previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","description":"Maximum number of entries to request from the provider. Capped at 200.","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProviderFile"},"description":"Provider files and folders."},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderConnectionProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProviderProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/LegacyCompatibleProblem"}}}}}}},"/projects":{"get":{"operationId":"listProjects","tags":["Projects"],"summary":"List projects","description":"Lists projects you can access. Supports search, label filters, sorting, and pagination.","parameters":[{"schema":{"type":"string","description":"Use page_info.next from the previous response. A null next cursor means the final page.","example":"eyJpZCI6IjEyMyJ9"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Integer page size from 1 to 100. Defaults to 20.","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Sort by updated_at, created_at, name, or slug. Defaults to updated_at; unknown fields also use updated_at.","example":"created_at"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Ascending or descending order. Defaults to desc.","example":"desc"},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"string","description":"Search term to filter projects by name or slug","example":"my-project"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by template status (true = only templates, false = exclude templates)","example":"false"},"required":false,"name":"is_template","in":"query"},{"schema":{"type":"string","enum":["regular","default","template"],"description":"Filter by project type","example":"default"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by system managed status","example":"true"},"required":false,"name":"system_managed","in":"query"},{"schema":{"type":"string","enum":["all","owned","invited"],"default":"all","description":"Filter by relationship to the authenticated user: all accessible projects, owned projects, or invited projects","example":"owned"},"required":false,"name":"access","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter projects by a user ID that has access to them. Non-admin user tokens may only use their own user ID.","example":"660e8400-e29b-41d4-a716-446655440001"},"required":false,"name":"user_id","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Label filters as key or key=value, repeated or comma-separated. All filters must match. Example: ?label=team=platform&label=criticality=high"},"required":false,"name":"label","in":"query"}],"responses":{"200":{"description":"Paginated list of projects","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Invalid query or label filter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Access denied to the requested project scope or user filter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createProject","tags":["Projects"],"summary":"Create a project","description":"Creates an owned project. Name is required; slug is generated when omitted. Without a template, the project starts with no source files. Project-scoped API keys cannot create projects; use a user session or account-wide API key.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Project display name. Must not be empty."},"slug":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$","description":"Lowercase identifier starting with a letter. Generated from name when omitted."},"description":{"type":"string","description":"Project description."},"templateSlug":{"type":"string","description":"Starter slug or accessible template project slug. Omit or use blank for an empty project."},"templateProjectId":{"type":"string","format":"uuid","description":"Accessible template project UUID to copy. Overrides templateSlug when supplied."}},"required":["name"],"additionalProperties":false},"example":{"name":"My Project","description":"A sample project description","templateSlug":"minimal"}}}},"responses":{"201":{"description":"Project created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Project-scoped tokens cannot create projects","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Template project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Project slug already exists","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}":{"get":{"operationId":"getProject","tags":["Projects"],"summary":"Get project","description":"Return the authenticated caller’s accessible project with related environments.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Project found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDetail"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Requires project.read","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateProject","tags":["Projects"],"summary":"Update project","description":"Updates the project name, slug, description, or configuration. Requires project.settings.manage. Omitted fields and config members retain their stored values.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$","description":"Lowercase identifier starting with a letter; words may be separated by single hyphens."},"name":{"type":"string","minLength":1},"description":{"type":"string","description":"Project description. An empty string clears it."},"config":{"$ref":"#/components/schemas/ProjectConfigInput"}},"additionalProperties":false},"example":{"name":"Updated Project Name","description":"Updated description","config":{"is_template":true,"coming_soon":false,"category":"saas"}}}}},"responses":{"200":{"description":"Project updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Requires project.settings.manage","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Project slug already exists","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteProject","tags":["Projects"],"summary":"Delete project","description":"Deletes the resolved project and returns no content when the project is removed. Requires project.delete.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"204":{"description":"Project deleted"},"401":{"description":"Authentication required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Requires project.delete","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/labels":{"get":{"operationId":"listProjectLabels","tags":["Project Labels"],"summary":"List project labels","description":"Lists active labels assigned to the project. Requires project.read.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"description":"Project UUID or slug.","name":"project_reference","in":"path"}],"responses":{"200":{"description":"Project labels.","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"$ref":"#/components/schemas/Label"}}},"required":["labels"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createProjectLabel","tags":["Project Labels"],"summary":"Create project label","description":"Adds a label in the user namespace with a required key and optional value and color. Requires project.settings.manage. Normalized duplicates return 409.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"description":"Project UUID or slug.","name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64,"description":"Required label key. Trimmed and lowercased; starts with a letter or number and allows letters, numbers, dot, underscore and dash."},"value":{"type":["string","null"],"maxLength":128,"description":"Label value. Trimmed; a supplied blank value is invalid. Omit or use null for a key-only label, including on replacement."},"color":{"type":["string","null"],"maxLength":32,"description":"Display color. Omit, use null or supply a blank string to clear it, including on replacement."}},"required":["key"]}}}},"responses":{"200":{"description":"Created label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Label"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/labels/{label_id}":{"put":{"operationId":"updateProjectLabel","tags":["Project Labels"],"summary":"Update project label","description":"Replaces a project label. Key is required; omitted value and color are cleared. Requires project.settings.manage. Normalized duplicates return 409.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"description":"Project UUID or slug.","name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Label UUID within the selected resource."},"required":true,"description":"Label UUID within the selected resource.","name":"label_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64,"description":"Required label key. Trimmed and lowercased; starts with a letter or number and allows letters, numbers, dot, underscore and dash."},"value":{"type":["string","null"],"maxLength":128,"description":"Label value. Trimmed; a supplied blank value is invalid. Omit or use null for a key-only label, including on replacement."},"color":{"type":["string","null"],"maxLength":32,"description":"Display color. Omit, use null or supply a blank string to clear it, including on replacement."}},"required":["key"]}}}},"responses":{"200":{"description":"Updated label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Label"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteProjectLabel","tags":["Project Labels"],"summary":"Delete project label","description":"Soft-deletes an active project label. Subsequent lists omit it. Requires project.settings.manage; API keys also require delete scope. Returns 204 without a body.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug.","example":"my-project"},"required":true,"description":"Project UUID or slug.","name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Label UUID within the selected resource."},"required":true,"description":"Label UUID within the selected resource.","name":"label_id","in":"path"}],"responses":{"204":{"description":"Label removed."},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/accounts/{account_id}/projects":{"get":{"operationId":"listAccountProjects","tags":["Account Projects"],"summary":"List account projects","description":"Lists projects assigned to the account by newest creation timestamp, then project UUID descending. Copy page_info.next unchanged to continue. Page size is an integer from 1 to 100; default 20.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"description":"Integer page size from 1 to 100. Defaults to 20.","name":"limit","in":"query"}],"responses":{"200":{"description":"Projects of the account","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountProject"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createAccountProject","tags":["Account Projects"],"summary":"Create account project","description":"Creates a project in the account. The caller remains the project owner for billing and collaboration seats.\n\nReturns `409` if the slug is already in use or `402` if the caller has reached the project limit. Automatically generated slugs include a random suffix. To avoid creating another project on retry, provide the same explicit slug.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Project display name."},"slug":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$","description":"Unique project slug. Omit to generate a slug with a random suffix."},"template_slug":{"type":"string","description":"Optional template slug. A template project UUID takes precedence."},"template_project_id":{"type":"string","format":"uuid","description":"Optional template project UUID. Overrides template_slug."}},"required":["name"]}}}},"responses":{"201":{"description":"Project created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountProject"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Payment required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/templates":{"get":{"operationId":"listTemplates","tags":["Project Templates"],"summary":"List templates","description":"Returns a page of curated project templates. Search, category and blank exclusion apply before slug pagination. Default order is curated configuration order; explicitly requested sorting overrides it. Unknown or out-of-filter cursors are rejected.","security":[],"parameters":[{"schema":{"type":"string","description":"Search term to filter templates by name or slug","example":"landing"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","description":"Filter by use case/category (for example, \"Store\", \"Landing\").","example":"Store"},"required":false,"name":"use_case","in":"query"},{"schema":{"type":"string","pattern":"^(name|slug|createdAt|updatedAt)(:([aA][sS][cC]|[dD][eE][sS][cC]))?$","description":"Deprecated. Use sort_by and sort_order. Sort field and direction in format \"field:ASC\" or \"field:DESC\". Valid fields: name, slug, createdAt, updatedAt.; no removal date is scheduled.","example":"name:ASC"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["name","slug","created_at","updated_at"],"description":"Optional sort field. Omit sorting to retain curated configuration order."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Defaults to asc when sorting. On its own sorts by name."},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"string","description":"Template slug from this filtered list; unknown cursors are rejected"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Exclude the blank template from results","example":"true"},"required":false,"name":"exclude_blank","in":"query"}],"responses":{"200":{"description":"Paginated list of available templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the source template project"},"slug":{"type":"string","description":"Template slug, also used as its pagination cursor"},"name":{"type":"string","description":"Display name of the source template project"},"config":{"type":"object","properties":{"description":{"type":"string","description":"Description stored in the template project configuration"},"category":{"type":"string","description":"Category of the template project"},"preview_url":{"type":"string","description":"HTTPS preview URL derived from the template slug and configured project domain suffix"}}},"coming_soon":{"type":"boolean","description":"Whether the template is marked coming soon; listing includes these entries but AI recommendations exclude them"},"created_at":{"type":"string","description":"Creation time of the source template project as an ISO 8601 timestamp"},"updated_at":{"type":"string","description":"Last update time of the source template project as an ISO 8601 timestamp"}},"required":["id","slug","name"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Invalid query parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/templates/find":{"post":{"operationId":"searchTemplates","tags":["Project Templates"],"summary":"Search templates","description":"Find the best matching template for a project idea.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"user_intent":{"type":"string","minLength":1,"maxLength":500,"description":"The user's description of what they want to build (1 to 500 characters)"}},"required":["user_intent"]},"example":{"user_intent":"A landing page for my SaaS startup with pricing and features sections"}}}},"responses":{"200":{"description":"Best matching template with confidence score","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","description":"Template slug to use"},"name":{"type":"string","description":"Template name"},"description":{"type":"string","description":"Template description"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence score 0-1"},"reasoning":{"type":"string","description":"Why this template was selected"}},"required":["slug","name","description","confidence","reasoning"]}}}},"400":{"description":"Invalid input - user_intent too long or missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error - AI processing failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Service unavailable - AI service not configured","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/files":{"get":{"operationId":"listFiles","tags":["Project Files"],"summary":"List project files","description":"Returns all file fields including content by default. To select response fields, use `?fields=(id,path,size)`.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Content to address: `main`, `branch:<name-or-id>`, `release:<version>` or `env:<name>`. Canonical replacement for `branch` and `branch_id`.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID. Legacy alias for `ref=branch:<value>`.","example":"feature-x"},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch ID. Legacy alias for `ref=branch:<uuid>`."},"required":false,"name":"branch_id","in":"query"},{"schema":{"type":"string","maxLength":1024,"description":"File pattern filter (for example, *.tsx)."},"required":false,"description":"File pattern filter (for example, *.tsx).","name":"pattern","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":20,"description":"Files per page. At most 100 when the listing includes content, and at most 1000 when `fields` excludes content.","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["path","updated_at"],"default":"updated_at","description":"Sort by path or last update time (default updated_at)."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order."},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"Paginated list of files with selectable response fields.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number","description":"Size of the file content encoded as UTF-8, in bytes."},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"},"checksum":{"type":["string","null"]},"_links":{"type":"object","properties":{"self":{"type":"object","properties":{"href":{"type":"string"}},"required":["href"]}},"required":["self"]}},"required":["path","content","size","type","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"},"_links":{"type":"object","additionalProperties":{"type":"object","properties":{"href":{"type":"string","description":"URL of the linked resource"},"method":{"type":"string","description":"HTTP method for this link (default: GET)"},"title":{"type":"string","description":"Human-readable description of the link"}},"required":["href"]},"description":"Hypermedia links for resource navigation"}},"required":["data","page_info","_links"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/files/{file_path}":{"get":{"operationId":"getFile","tags":["Project Files"],"summary":"Get project file","description":"Returns a file by its path (for example, `pages/index.mdx`) or entity UUID. The identifier type is auto-detected. To select response fields, use `?fields=(id,path,size)`. If the file path contains special characters, URL-encode the `file_path` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"schema":{"type":"string","description":"Project slug, UUID, or domain"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"File path or UUID (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Content to address: `main`, `branch:<name-or-id>`, `release:<version>` or `env:<name>`. Canonical replacement for `branch` and `branch_id`.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID. Legacy alias for `ref=branch:<value>`.","example":"feature-x"},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch ID. Legacy alias for `ref=branch:<uuid>`."},"required":false,"name":"branch_id","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"File content with metadata with selectable response fields.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number","description":"Size of the file content encoded as UTF-8, in bytes."},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"},"checksum":{"type":["string","null"]},"_links":{"type":"object","additionalProperties":{"type":"object","properties":{"href":{"type":"string","description":"URL of the linked resource"},"method":{"type":"string","description":"HTTP method for this link (default: GET)"},"title":{"type":"string","description":"Human-readable description of the link"}},"required":["href"]},"description":"Hypermedia links for resource navigation"}},"required":["path","content","size","type","updated_at"]}}}},"400":{"description":"Missing file path or ID","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"File not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"createOrUpdateFile","tags":["Project Files"],"summary":"Upsert project file","description":"Creates or updates textual source content in main or the selected branch. Each successful mutation appends an immutable file version. MIME type is not a writable source-file property. Checksums and version guards apply to updates; expected_absent provides atomic create-only behavior. If the file path contains special characters, URL-encode the `file_path` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"schema":{"type":"string","description":"Project slug, UUID, or domain"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Mutable content to address: main or branch:<name-or-id>. Omit for main. Release and environment selectors return 400. Supplied aliases must name the same content.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID; legacy alias for ref=branch:<value>. Supplied aliases must agree."},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID; legacy alias for ref=branch:<uuid>. Supplied aliases must agree."},"required":false,"name":"branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"File content"},"expected_checksum":{"type":"string","description":"Expected current checksum when updating an existing file; ignored on creation. Omission disables this guard."},"expected_version_id":{"type":"string","description":"Expected current version ID when updating an existing file; ignored on creation. Omission disables this guard."},"expected_absent":{"type":"boolean","description":"True requires absence atomically when creating; an existing file returns 409. False or omission retains upsert behavior."}},"required":["content"],"additionalProperties":false}}}},"responses":{"200":{"description":"File updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Path-derived file identifier."},"path":{"type":"string","description":"Normalized stored file path."},"content":{"type":"string","description":"Text supplied by this write request."},"size":{"type":"number","description":"Size of the file content encoded as UTF-8, in bytes."},"updated_at":{"type":"string","description":"Response timestamp for the successful update."}},"required":["id","path","content","size","updated_at"]}}}},"201":{"description":"File created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Path-derived file identifier."},"path":{"type":"string","description":"Normalized stored file path."},"content":{"type":"string","description":"Text supplied by this write request."},"size":{"type":"number","description":"Size of the file content encoded as UTF-8, in bytes."},"created_at":{"type":"string","description":"Response timestamp for successful creation."}},"required":["id","path","content","size","created_at"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteFile","tags":["Project Files"],"summary":"Delete project file","description":"Deletes the file from main or the selected branch by appending a deletion version. Immutable version history remains. Omission of expected_version_id disables the concurrency guard. If the file path contains special characters, URL-encode the `file_path` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"schema":{"type":"string","description":"Project slug, UUID, or domain"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Mutable content to address: main or branch:<name-or-id>. Omit for main. Release and environment selectors return 400. Supplied aliases must name the same content.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID; legacy alias for ref=branch:<value>. Supplied aliases must agree."},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID; legacy alias for ref=branch:<uuid>. Supplied aliases must agree."},"required":false,"name":"branch_id","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Expected current file version ID for optimistic concurrency"},"required":false,"name":"expected_version_id","in":"query"}],"responses":{"204":{"description":"File deleted successfully; no response body."},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/files/{file_path}/diff":{"get":{"operationId":"getFileDiff","tags":["Project Files"],"summary":"Get project file diff","description":"Returns a unified diff (git-compatible format) comparing the current version to a previous version. Main, release and environment selectors require `source_ref`; a branch selector defaults to a diff against main. If the file path contains special characters, URL-encode the `file_path` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"schema":{"type":"string","description":"Project slug, UUID, or domain"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Content to address: `main`, `branch:<name-or-id>`, `release:<version>` or `env:<name>`. Canonical replacement for `branch` and `branch_id`.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID. Legacy alias for `ref=branch:<value>`.","example":"feature-x"},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch ID. Legacy alias for `ref=branch:<uuid>`."},"required":false,"name":"branch_id","in":"query"},{"schema":{"type":"string","description":"Source version ID to compare from. Required for main, release and environment selectors; a branch selector defaults to a diff against main."},"required":false,"name":"source_ref","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10,"default":3,"description":"Number of context lines around changes (default: 3)"},"required":false,"name":"context_lines","in":"query"}],"responses":{"200":{"description":"Unified diff","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"The path associated with this tool result."},"diff":{"type":"string","description":"The diff associated with this tool result."},"additions":{"type":"number","description":"The additions associated with this tool result."},"deletions":{"type":"number","description":"The deletions associated with this tool result."}},"required":["path","diff","additions","deletions"]}}}},"400":{"description":"Missing file path or source_ref, or an invalid or conflicting content selector","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"File or version not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/files/batch":{"post":{"operationId":"getFilesBatch","tags":["Project Files"],"summary":"Batch get project files","description":"Get multiple files in a single request.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Content to address: `main`, `branch:<name-or-id>`, `release:<version>` or `env:<name>`. Canonical replacement for `branch` and `branch_id`.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID. Legacy alias for `ref=branch:<value>`.","example":"feature-x"},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch ID. Legacy alias for `ref=branch:<uuid>`."},"required":false,"name":"branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"paths":{"type":"array","items":{"type":"string"},"description":"Array of file paths to fetch"}},"required":["paths"]}}}},"responses":{"200":{"description":"Files with content","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"content":{"type":"string"},"size":{"type":"number","description":"Size of the file content encoded as UTF-8, in bytes."},"found":{"type":"boolean"},"checksum":{"type":["string","null"]},"error":{"type":"string"}},"required":["path","type","content","size","found"]}}},"required":["files"]}}}},"400":{"description":"Invalid input, or an invalid or conflicting content selector","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/files/move":{"post":{"operationId":"moveFile","tags":["Project Files"],"summary":"Move project file","description":"Moves a file in main or the selected branch. The source receives a deletion version and the destination a new path-derived file ID; immutable history remains. Omit expected_version_id for an unguarded move.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Mutable content to address: main or branch:<name-or-id>. Omit for main. Release and environment selectors return 400. Supplied aliases must name the same content.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID; legacy alias for ref=branch:<value>. Supplied aliases must agree."},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID; legacy alias for ref=branch:<uuid>. Supplied aliases must agree."},"required":false,"name":"branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_path":{"type":"string","description":"Current file path"},"destination_path":{"type":"string","description":"New file path"},"expected_version_id":{"type":"string","description":"Expected current source file version ID. Omission disables this guard; a stale version returns 409."}},"required":["source_path","destination_path"]}}}},"responses":{"200":{"description":"File moved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"source_path":{"type":"string","description":"Original source path supplied by the caller."},"destination_path":{"type":"string","description":"Destination path supplied by the caller."},"file_id":{"type":"string","description":"Destination file ID when supplied by the store; IDs depend on project and normalized path."},"success":{"type":"boolean","description":"True after completing the move."}},"required":["source_path","destination_path","success"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/files/{file_path}/versions":{"get":{"operationId":"listFileVersions","tags":["Project File Versions"],"summary":"List project file versions","description":"Lists committed versions newest first: main history uses selection time, and branch history uses commit sequence. Other sorting is unsupported. Pagination is forward-only; page_info.prev is always null. If the file path contains special characters, URL-encode the `file_path` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"schema":{"type":"string","description":"Project slug, UUID, or domain"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Content to address: `main`, `branch:<name-or-id>`, `release:<version>` or `env:<name>`. Canonical replacement for `branch` and `branch_id`.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID. Legacy alias for `ref=branch:<value>`.","example":"feature-x"},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch ID. Legacy alias for `ref=branch:<uuid>`."},"required":false,"name":"branch_id","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"name":"cursor","in":"query"},{"$ref":"#/components/parameters/PaginationLimit"}],"responses":{"200":{"description":"Paginated list of file versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Committed version identifier."},"file_id":{"type":"string","description":"Source file identifier when supplied by the content source."},"path":{"type":"string","description":"Canonical path of the versioned file."},"type":{"type":"string","description":"Generic file record kind; this history projection returns file."},"created_at":{"type":"string","description":"Persisted creation or selection timestamp for this version."},"created_by":{"type":["string","null"],"description":"User identifier recorded for the version; null when unavailable."}},"required":["id","path","type","created_at","created_by"],"description":"One data item associated with this tool result."},"description":"Primary result records returned by the tool."},"page_info":{"type":"object","properties":{"self":{"type":["string","null"],"description":"Cursor supplied for this page; null for the first page."},"first":{"type":"null","description":"Always null. Omit the cursor to request the first page."},"next":{"type":["string","null"],"description":"Opaque forward continuation cursor; null when exhausted."},"prev":{"type":"null","description":"Always null. Backward pagination is unsupported."}},"required":["self","first","next","prev"],"description":"Pagination cursor values for traversing the result set."}},"required":["data","page_info"]}}}},"400":{"description":"Missing file path, or an invalid, conflicting or snapshot content selector","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"File not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/files/{file_path}/versions/{version_id}":{"get":{"operationId":"getFileVersion","tags":["Project File Versions"],"summary":"Get project file version","description":"If the file path contains special characters, URL-encode the `file_path` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"schema":{"type":"string","description":"Project slug, UUID, or domain"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Version UUID or numeric index 0..99 (0 = newest committed version)"},"required":true,"description":"Version UUID or numeric index 0..99 (0 = newest committed version)","name":"version_id","in":"path"},{"schema":{"type":"string","description":"Content to address: `main`, `branch:<name-or-id>`, `release:<version>` or `env:<name>`. Canonical replacement for `branch` and `branch_id`.","example":"branch:feature-x"},"required":false,"name":"ref","in":"query"},{"schema":{"type":"string","description":"Branch name or ID. Legacy alias for `ref=branch:<value>`.","example":"feature-x"},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Branch ID. Legacy alias for `ref=branch:<uuid>`."},"required":false,"name":"branch_id","in":"query"}],"responses":{"200":{"description":"File version content with metadata","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Committed version identifier."},"path":{"type":"string","description":"Canonical path of the versioned file."},"content":{"type":"string","description":"Full content stored for this version."},"size":{"type":"number","description":"Size of the version content in UTF-8 bytes."},"type":{"type":"string","enum":["page","function","component","file"],"description":"File kind derived from its path: page, function, component, or file."},"updated_at":{"type":"string","description":"Persisted creation or selection timestamp for this version."}},"required":["id","path","content","size","type","updated_at"]}}}},"400":{"description":"Missing parameters, or an invalid, conflicting or snapshot content selector","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Version not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/files/search":{"post":{"operationId":"searchFiles","tags":["File search"],"summary":"Search project files (text)","description":"Search textual project files with optional regex and path filtering. Matches contain the matching line only; surrounding context is not supported.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Search query (text or regex pattern)"},"pattern":{"type":"string","description":"File path pattern filter (for example, *.tsx)."},"is_regex":{"type":"boolean","description":"Treat query as regex (default: false)"},"case_sensitive":{"type":"boolean","description":"Case sensitive search (default: false)"},"max_results":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum matching files, from 1 to 100 (default: 50). Limits files, not lines."},"maxResults":{"type":"integer","minimum":1,"maximum":100,"description":"Compatibility alias for max_results. Maximum matching files, from 1 to 100 (default: 50). Limits files, not lines."}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"File ID when supplied by the content source."},"path":{"type":"string","description":"Path of the matching project source file."},"content":{"type":"string","description":"Full file content when available from the content source."},"matches":{"type":"array","items":{"type":"object","properties":{"line":{"type":"number","description":"1-based line number of the matching line."},"content":{"type":"string","description":"Matching line text, without surrounding lines."}},"required":["line","content"],"description":"One matching source line."},"description":"Matching lines within this file."}},"required":["path","matches"],"description":"One matching project source file."},"description":"Matching files visible to the caller."},"total_files":{"type":"number","description":"Number of matching files returned, after access filtering and the matching-file limit."}},"required":["results","total_files"]}}}},"400":{"description":"Invalid query, regex, or limit; unsupported input fields; or conflicting limit aliases.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchName}/files/search":{"post":{"operationId":"searchBranchFiles","tags":["File search"],"summary":"Search branch files (text)","description":"Grep-like text search across branch files with regex support.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Search query (text or regex pattern)"},"pattern":{"type":"string","description":"File path pattern filter (for example, *.tsx)."},"is_regex":{"type":"boolean","description":"Treat query as regex (default: false)"},"case_sensitive":{"type":"boolean","description":"Case sensitive search (default: false)"},"max_results":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum matching files, integer 1–100 (default: 50)."}},"required":["query"]}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"matches":{"type":"array","items":{"type":"object","properties":{"line":{"type":"number"},"content":{"type":"string"}},"required":["line","content"]}}},"required":["path","matches"]}},"total_files":{"type":"number"}},"required":["results","total_files"]}}}},"400":{"description":"Invalid search query, regex, or result limit. max_results must be an integer from 1 through 100.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient project permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches":{"get":{"operationId":"listBranches","tags":["Branches"],"summary":"List branches","description":"Lists persisted project branches with optional case-insensitive name and status filters. Omit limit and cursor for the complete list. Paged results use ID ascending order; continuations bind project, principal, filters and page size.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size 1–100. Omit limit and cursor for the complete collection; cursor alone defaults to 20.","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation bound to collection, project, branch, principal, filters and page size."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Search filter for branch name (case-insensitive partial match)","example":"feature"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["active","merged","closed","all"],"default":"all","description":"Filter by branch status","example":"active"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"List of branches","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"base_branch_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":["string","null"],"description":"Persisted branch creation time.","example":"2026-09-14T10:00:00.000Z"},"created_by":{"type":["string","null"],"format":"uuid"},"merged_at":{"type":["string","null"],"description":"Persisted merge time; null before a merge."},"merged_by":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["active","merged","closed"],"description":"Stored lifecycle state; closed is distinct from merged.","example":"active"},"updated_at":{"type":["string","null"]},"version":{"type":"integer","minimum":0,"description":"Persisted optimistic-concurrency version for expected_version on merge.","example":3},"description":{"type":["string","null"]},"auto_delete_on_merge":{"type":"boolean"}},"required":["id","name","project_id"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createBranch","tags":["Branches"],"summary":"Create branch","description":"Create a new branch from an existing branch or the default branch.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9._/][A-Za-z0-9._/-]*$","description":"Branch name. Branch name may only contain letters, numbers, \".\", \"_\", \"/\" and \"-\", and cannot start with \"-\".","example":"feature-new-header"},"base_branch_id":{"type":["string","null"],"format":"uuid","description":"Omit to branch from the project root (created automatically if missing). Use null to create a root branch; rejected if a root already exists. A UUID must identify a base branch in this project."}},"required":["name"]}}}},"responses":{"201":{"description":"Branch created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"base_branch_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":["string","null"],"description":"Persisted branch creation time.","example":"2026-09-14T10:00:00.000Z"},"created_by":{"type":["string","null"],"format":"uuid"},"merged_at":{"type":["string","null"],"description":"Persisted merge time; null before a merge."},"merged_by":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["active","merged","closed"],"description":"Stored lifecycle state; closed is distinct from merged.","example":"active"},"updated_at":{"type":["string","null"]},"version":{"type":"integer","minimum":0,"description":"Persisted optimistic-concurrency version for expected_version on merge.","example":3},"description":{"type":["string","null"]},"auto_delete_on_merge":{"type":"boolean"}},"required":["id","name","project_id"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchId}":{"get":{"operationId":"getBranch","tags":["Branches"],"summary":"Get branch","description":"Return details for a specific branch.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"}],"responses":{"200":{"description":"Branch details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"base_branch_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":["string","null"],"description":"Persisted branch creation time.","example":"2026-09-14T10:00:00.000Z"},"created_by":{"type":["string","null"],"format":"uuid"},"merged_at":{"type":["string","null"],"description":"Persisted merge time; null before a merge."},"merged_by":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["active","merged","closed"],"description":"Stored lifecycle state; closed is distinct from merged.","example":"active"},"updated_at":{"type":["string","null"]},"version":{"type":"integer","minimum":0,"description":"Persisted optimistic-concurrency version for expected_version on merge.","example":3},"description":{"type":["string","null"]},"auto_delete_on_merge":{"type":"boolean"}},"required":["id","name","project_id"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteBranch","tags":["Branches"],"summary":"Delete branch","description":"Deletes a branch with a base branch and its associated content, excluding main. Requires project.files.write; API keys also require delete scope.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"}],"responses":{"200":{"description":"Branch deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deleted_branch_id":{"type":"string","format":"uuid"}},"required":["success","deleted_branch_id"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchId}/merge-preview":{"get":{"operationId":"previewBranchMerge","tags":["Branches"],"summary":"Preview branch merge","description":"Previews the changes from merging a branch.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Merge preview","content":{"application/json":{"schema":{"type":"object","properties":{"source_branch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"base_branch_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":["string","null"],"description":"Persisted branch creation time.","example":"2026-09-14T10:00:00.000Z"},"created_by":{"type":["string","null"],"format":"uuid"},"merged_at":{"type":["string","null"],"description":"Persisted merge time; null before a merge."},"merged_by":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["active","merged","closed"],"description":"Stored lifecycle state; closed is distinct from merged.","example":"active"},"updated_at":{"type":["string","null"]},"version":{"type":"integer","minimum":0,"description":"Persisted optimistic-concurrency version for expected_version on merge.","example":3},"description":{"type":["string","null"]},"auto_delete_on_merge":{"type":"boolean"}},"required":["id","name","project_id"]},"target_branch_id":{"type":["string","null"],"format":"uuid"},"target_branch_name":{"type":"string"},"diffs":{"type":"array","items":{"type":"object","properties":{"file_path":{"type":"string"},"file_type":{"type":"string"},"file_id":{"type":"string"},"has_conflicts":{"type":"boolean"},"conflict_count":{"type":"number"},"conflict_regions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["conflict"]},"baseStart":{"type":"integer","minimum":1},"baseEnd":{"type":"integer","minimum":0},"targetStart":{"type":"integer","minimum":1},"targetEnd":{"type":"integer","minimum":0},"sourceStart":{"type":"integer","minimum":1},"sourceEnd":{"type":"integer","minimum":0},"baseLines":{"type":"string"},"targetLines":{"type":"string"},"sourceLines":{"type":"string"},"base_start":{"type":"integer","minimum":1},"base_end":{"type":"integer","minimum":0},"target_start":{"type":"integer","minimum":1},"target_end":{"type":"integer","minimum":0},"source_start":{"type":"integer","minimum":1},"source_end":{"type":"integer","minimum":0},"base_lines":{"type":"string"},"target_lines":{"type":"string"},"source_lines":{"type":"string"}},"required":["id","type","base_start","base_end","target_start","target_end","source_start","source_end","base_lines","target_lines","source_lines"]}},"is_new":{"type":"boolean"},"is_deleted":{"type":"boolean"},"is_modified":{"type":"boolean"},"base_changed":{"type":"boolean"},"branch_changed":{"type":"boolean"},"base_content":{"type":["string","null"]},"target_content":{"type":["string","null"]},"source_content":{"type":["string","null"]},"original_content":{"type":["string","null"]},"modified_content":{"type":["string","null"]}},"required":["file_path","file_type","has_conflicts","conflict_count","is_new","is_deleted","is_modified","base_changed","branch_changed"]}}},"required":["source_branch","target_branch_id","target_branch_name","diffs"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchId}/eligibility":{"get":{"operationId":"checkBranchEligibility","tags":["Branches"],"summary":"Check branch eligibility","description":"Evaluates branch approvals, status checks, and policy requirements to determine whether the branch can merge.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"}],"responses":{"200":{"description":"Merge eligibility result","content":{"application/json":{"schema":{"type":"object","properties":{"can_merge":{"type":"boolean"},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"approved_by":{"type":"string","format":"uuid"},"approved_at":{"type":"string","description":"Recorded approval time; retained after dismissal."},"comment":{"type":["string","null"]},"dismissed_at":{"type":["string","null"]},"dismissed_by":{"type":["string","null"],"format":"uuid","description":"User who dismissed the approval, or null while active."},"dismissed_reason":{"type":["string","null"]}},"required":["id","branch_id","approved_by","approved_at","comment","dismissed_at","dismissed_by","dismissed_reason"]}},"status_checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"check_name":{"type":"string"},"status":{"type":"string","enum":["pending","success","failure"]},"description":{"type":["string","null"]},"external_url":{"type":["string","null"]},"started_at":{"type":["string","null"],"description":"Recorded check start time, or null when unavailable."},"completed_at":{"type":["string","null"],"description":"Recorded check completion time, or null while pending."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","branch_id","check_name","status","description","external_url","created_at","updated_at"]}},"blockers":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["approval_required","status_check_failed","status_check_pending","self_approval_not_allowed","required_reviewer_missing","approvalRequired","statusCheckFailed","selfApprovalNotAllowed","requiredReviewerMissing"]},"message":{"type":"string"},"details":{"type":["object","null"],"additionalProperties":{}}},"required":["type","message","details"]}}},"required":["can_merge","approvals","status_checks","blockers"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchId}/merge":{"post":{"operationId":"mergeBranch","tags":["Branches"],"summary":"Merge branch","description":"Merges a branch into the target branch (or main if not specified).","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":["integer","null"],"minimum":0,"description":"Optional optimistic-concurrency precondition against the persisted source branch version. A stale value returns 412 before merge writes.","example":3},"target_branch_id":{"type":["string","null"],"format":"uuid","description":"Target branch ID to merge into (null for main branch)"}}}}}},"responses":{"200":{"description":"Branch merged successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"branch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"base_branch_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":["string","null"],"description":"Persisted branch creation time.","example":"2026-09-14T10:00:00.000Z"},"created_by":{"type":["string","null"],"format":"uuid"},"merged_at":{"type":["string","null"],"description":"Persisted merge time; null before a merge."},"merged_by":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["active","merged","closed"],"description":"Stored lifecycle state; closed is distinct from merged.","example":"active"},"updated_at":{"type":["string","null"]},"version":{"type":"integer","minimum":0,"description":"Persisted optimistic-concurrency version for expected_version on merge.","example":3},"description":{"type":["string","null"]},"auto_delete_on_merge":{"type":"boolean"}},"required":["id","name","project_id"]},"merged_documents":{"type":"number"},"added_documents":{"type":"number"},"deleted_documents":{"type":"number"},"auto_merged_documents":{"type":"number"}},"required":["success","branch","merged_documents","added_documents","deleted_documents","auto_merged_documents"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"412":{"description":"Precondition failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchId}/approvals":{"get":{"operationId":"listBranchApprovals","tags":["Branch Approvals"],"summary":"List branch approvals","description":"Lists approvals recorded for a branch in the project. Omit limit and cursor for the complete list. Paged results use ID ascending order; continuations bind branch, project, principal and page size.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size 1–100. Omit limit and cursor for the complete collection; cursor alone defaults to 20.","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation bound to collection, project, branch, principal, filters and page size."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of approvals","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"approved_by":{"type":"string","format":"uuid"},"approved_at":{"type":"string","description":"Recorded approval time; retained after dismissal."},"comment":{"type":["string","null"]},"dismissed_at":{"type":["string","null"]},"dismissed_by":{"type":["string","null"],"format":"uuid","description":"User who dismissed the approval, or null while active."},"dismissed_reason":{"type":["string","null"]}},"required":["id","branch_id","approved_by","approved_at","comment","dismissed_at","dismissed_by","dismissed_reason"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchId}/approvals/{approvalId}":{"delete":{"operationId":"dismissBranchApproval","tags":["Branch Approvals"],"summary":"Dismiss branch approval","description":"Soft-dismisses a branch approval while retaining its audit fields, so merge eligibility uses the remaining active approvals. Requires project.files.write; API keys also require delete scope.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Approval UUID belonging to the path branch. Missing approvals or a different branch return 404."},"required":true,"name":"approvalId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Approval dismissed","content":{"application/json":{"schema":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"approved_by":{"type":"string","format":"uuid"},"approved_at":{"type":"string","description":"Recorded approval time; retained after dismissal."},"comment":{"type":["string","null"]},"dismissed_at":{"type":["string","null"]},"dismissed_by":{"type":["string","null"],"format":"uuid","description":"User who dismissed the approval, or null while active."},"dismissed_reason":{"type":["string","null"]}},"required":["id","branch_id","approved_by","approved_at","comment","dismissed_at","dismissed_by","dismissed_reason"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchId}/approve":{"post":{"operationId":"approveBranch","tags":["Branch Approvals"],"summary":"Approve branch","description":"Create or updates the caller approval for a branch so the branch can satisfy merge policy requirements.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"string"}}}}}},"responses":{"201":{"description":"Approval created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"approved_by":{"type":"string","format":"uuid"},"approved_at":{"type":"string","description":"Recorded approval time; retained after dismissal."},"comment":{"type":["string","null"]},"dismissed_at":{"type":["string","null"]},"dismissed_by":{"type":["string","null"],"format":"uuid","description":"User who dismissed the approval, or null while active."},"dismissed_reason":{"type":["string","null"]}},"required":["id","branch_id","approved_by","approved_at","comment","dismissed_at","dismissed_by","dismissed_reason"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchId}/status-checks":{"get":{"operationId":"listBranchStatusChecks","tags":["Branch Status Checks"],"summary":"List branch status checks","description":"Lists status checks reported for a branch. Omit limit and cursor for the complete list. Paged results use ID ascending order; continuations bind branch, project, principal and page size.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size 1–100. Omit limit and cursor for the complete collection; cursor alone defaults to 20.","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation bound to collection, project, branch, principal, filters and page size."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of status checks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"check_name":{"type":"string"},"status":{"type":"string","enum":["pending","success","failure"]},"description":{"type":["string","null"]},"external_url":{"type":["string","null"]},"started_at":{"type":["string","null"],"description":"Recorded check start time, or null when unavailable."},"completed_at":{"type":["string","null"],"description":"Recorded check completion time, or null while pending."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","branch_id","check_name","status","description","external_url","created_at","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"upsertBranchStatusCheck","tags":["Branch Status Checks"],"summary":"Upsert branch status check","description":"Create or updates a named status check result for a branch.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Branch UUID belonging to the selected project. Missing or foreign branches return 404."},"required":true,"name":"branchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"check_name":{"type":"string"},"status":{"type":"string","enum":["pending","success","failure"]},"description":{"type":"string"},"external_url":{"type":"string"}},"required":["check_name","status"]}}}},"responses":{"200":{"description":"Status check updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"check_name":{"type":"string"},"status":{"type":"string","enum":["pending","success","failure"]},"description":{"type":["string","null"]},"external_url":{"type":["string","null"]},"started_at":{"type":["string","null"],"description":"Recorded check start time, or null when unavailable."},"completed_at":{"type":["string","null"],"description":"Recorded check completion time, or null while pending."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","branch_id","check_name","status","description","external_url","created_at","updated_at"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/policies":{"get":{"operationId":"listBranchPolicies","tags":["Branch Policies"],"summary":"List branch policies","description":"Lists branch protection policies, optionally restricted to enabled policies. Omit limit and cursor for the complete list. Paged results use ID ascending order; continuations bind project, principal, filters and page size.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size 1–100. Omit limit and cursor for the complete collection; cursor alone defaults to 20.","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation bound to collection, project, branch, principal, filters and page size."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Return only enabled branch protection policies when true.","example":"true"},"required":false,"name":"enabled_only","in":"query"}],"responses":{"200":{"description":"List of branch policies","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"is_enabled":{"type":"boolean"},"target_branch_pattern":{"type":["string","null"]},"required_approvals":{"type":"number"},"allow_self_approval":{"type":"boolean"},"required_reviewer_ids":{"type":["array","null"],"items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","is_enabled","target_branch_pattern","required_approvals","allow_self_approval","required_reviewer_ids","created_at","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createBranchPolicy","tags":["Branch Policies"],"summary":"Create branch policy","description":"Create a branch protection policy for a project, including required approvals and status checks.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"is_enabled":{"type":"boolean"},"target_branch_pattern":{"type":"string"},"required_approvals":{"type":"integer","minimum":0,"description":"Required approval count. Defaults to 0; MCP create_branch_policy defaults to 1."},"allow_self_approval":{"type":"boolean","description":"Allow the merger’s approval to count. Defaults to true; MCP create_branch_policy defaults to false."},"required_reviewer_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["name"]}}}},"responses":{"201":{"description":"Policy created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"is_enabled":{"type":"boolean"},"target_branch_pattern":{"type":["string","null"]},"required_approvals":{"type":"number"},"allow_self_approval":{"type":"boolean"},"required_reviewer_ids":{"type":["array","null"],"items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","project_id","name","is_enabled","target_branch_pattern","required_approvals","allow_self_approval","required_reviewer_ids","created_at","updated_at"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/policies/{policyId}":{"delete":{"operationId":"deleteBranchPolicy","tags":["Branch Policies"],"summary":"Delete branch policy","description":"Deletes a branch protection policy from the project. Requires project.settings.manage; API keys also require delete scope.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid","description":"Policy UUID belonging to the selected project. Missing or foreign policies return 404."},"required":true,"name":"policyId","in":"path"}],"responses":{"200":{"description":"Policy deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/commit":{"post":{"operationId":"commit","tags":["Project Commits"],"summary":"Commit project files","description":"Commits pending edits, deletions, and renames on the selected branch. The default branch is `main`.\n\n`file_references` accepts paths or legacy file UUIDs. `file_ids` is an alias; conflicting alias values return `400`.\n\nUse `expected_versions` to check each file’s current persisted version. For a single file, use `expected_version_id`.\n\nFiles commit independently. A stale version returns `409`, but other files in the batch might already have committed. The Problem response lists committed versions and conflicted files. Read the conflicted files again, then retry only those files.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file_ids":{"type":"array","items":{"type":"string"}},"file_references":{"type":"array","items":{"type":"string"}},"branch_reference":{"type":"string"},"expected_version_id":{"type":"string","format":"uuid"},"expected_versions":{"type":"object","description":"Provide the expected versions.","additionalProperties":{"type":"string","format":"uuid"}}}}}}},"responses":{"200":{"description":"Commit successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"versions":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string","format":"uuid"},"version_id":{"type":"string","format":"uuid"},"path":{"type":"string"}},"required":["version_id","path"]}}},"required":["success","versions"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/CommitConflictProblem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchName}/files":{"get":{"operationId":"listBranchFiles","tags":["Branch Files"],"summary":"List branch files","description":"Returns all file fields including content by default. To select response fields, use `?fields=(id,path,size)`.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","maxLength":1024,"description":"Provide the pattern."},"required":false,"description":"Provide the pattern.","name":"pattern","in":"query"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["path","updated_at"],"default":"updated_at"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_server_functions","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"Files from the branch with selectable response fields.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"type":{"type":"string","enum":["page","function","component","file"]},"size":{"type":"number","description":"Size of the file content encoded as UTF-8, in bytes."},"updated_at":{"type":"string"},"_links":{"type":"object","additionalProperties":{}}},"required":["path","content","type","size","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"},"_links":{"type":"object","additionalProperties":{}}},"required":["data","page_info"]}}}},"400":{"description":"Invalid file filter, fields, sort, cursor, or page size.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient project permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}":{"get":{"operationId":"getBranchFile","tags":["Branch Files"],"summary":"Get branch file","description":"Returns all file fields including content by default. To select response fields, use `?fields=(id,path,size)`. If the file path contains special characters, URL-encode the `filePath` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_server_functions","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"File from the branch with selectable response fields.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number","description":"Size of the file content encoded as UTF-8, in bytes."},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"}},"required":["path","content","size","type","updated_at"]}}}},"400":{"description":"Missing file path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Restricted server-function source or insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/diff":{"get":{"operationId":"getBranchFileDiff","tags":["Branch Files"],"summary":"Get branch file diff","description":"Returns a unified diff (git-compatible format) showing changes between main and branch. If the file path contains special characters, URL-encode the `filePath` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","description":"Source version ID to compare from (default: main branch)"},"required":false,"name":"source_ref","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10,"default":3,"description":"Context lines (default: 3)"},"required":false,"name":"context_lines","in":"query"}],"responses":{"200":{"description":"Unified diff","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"diff":{"type":"string","description":"Unified diff format string"},"additions":{"type":"number"},"deletions":{"type":"number"}},"required":["path","diff","additions","deletions"]}}}},"400":{"description":"Invalid request parameters; context_lines must be an integer from 0 to 10.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Restricted server-function source or insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/versions":{"get":{"operationId":"listBranchFileVersions","tags":["Branch File Versions"],"summary":"List branch file versions","description":"Returns branch-aware file history bounded by the branch snapshot. Pagination is forward-only; page_info.prev is always null. If the file path contains special characters, URL-encode the `filePath` parameter.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"name":"cursor","in":"query"},{"$ref":"#/components/parameters/PaginationLimit"}],"responses":{"200":{"description":"Paginated list of branch file versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"file_id":{"type":"string"},"path":{"type":"string"},"type":{"type":"string","enum":["page","function","component","file"]},"created_at":{"type":"string"},"created_by":{"type":["string","null"]}},"required":["id","path","type","created_at","created_by"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Invalid branch file history cursor or page size.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/versions/{version_id}":{"get":{"operationId":"getBranchFileVersion","tags":["Branch File Versions"],"summary":"Get branch file version","description":"Returns content for a specific branch-aware file version. If the file path contains special characters, URL-encode the `filePath` parameter.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","description":"Committed version UUID or newest-first index 0–99; zero is the newest branch-aware version."},"required":true,"description":"Version UUID or index 0..99; zero is the newest committed version.","name":"version_id","in":"path"}],"responses":{"200":{"description":"Branch file version content with metadata","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number","description":"Size of the file content encoded as UTF-8, in bytes."},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"}},"required":["id","path","content","size","type","updated_at"]}}}},"400":{"description":"Invalid version reference; provide a UUID or newest-first index 0–99.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/drafts":{"get":{"operationId":"listProjectFileDrafts","tags":["Branch File Drafts"],"summary":"List pending file drafts","description":"List the latest pending update per canonically visible source file, with its actual type and draft sequence. body_snapshot is null for updates without a full body, including deletions. Restricted server-function drafts are omitted. GraphQL draftFiles and MCP list_project_file_drafts counterparts.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Branch name or UUID; omit for main."},"required":false,"description":"Branch name or UUID; omit for main.","name":"branch_reference","in":"query"},{"schema":{"type":"string","enum":["page","component","function","virtual_file"],"description":"Filter by the actual source-file type."},"required":false,"description":"Filter by the actual source-file type.","name":"entity_type","in":"query"}],"responses":{"200":{"description":"Latest pending updates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string","format":"uuid","description":"Deterministic source-file identity within the project."},"entity_type":{"type":"string","enum":["page","component","function","virtual_file"],"description":"Canonical source-file type."},"body_snapshot":{"type":["string","null"],"description":"Latest full-body snapshot; null for pending updates without a full body, including deletions."},"version":{"type":"integer","minimum":1,"description":"Current pending draft sequence; commit/discard removes the pending sequence."},"updated_at":{"type":"string","description":"Timestamp of the latest pending update."}},"required":["file_id","entity_type","body_snapshot","version","updated_at"]}}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/draft":{"get":{"operationId":"getBranchFileDraft","tags":["Branch File Drafts"],"summary":"Get branch file draft","description":"Read the selected existing source file’s pending full-body draft, including empty bodies. Missing drafts and updates without a readable full snapshot return 404. Restricted server-function source returns 403, including when addressed by UUID. URL-encode filePath. GraphQL draftContent retains its legacy nullable/empty-body envelope; MCP get_project_file_draft uses a not-found condition.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"}],"responses":{"200":{"description":"Draft content with navigation links","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"updated_at":{"type":"string"},"version":{"type":"integer","minimum":1,"description":"Current pending draft sequence; resets after commit/discard. Use as expected_draft_version for a guarded draft write."},"entity_type":{"type":"string","enum":["page","component","function","virtual_file"],"description":"Canonical source-file type."},"_links":{"type":"object","additionalProperties":{}}},"required":["path","content","updated_at"]}}}},"400":{"description":"Missing file path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Restricted server-function source","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"updateBranchFileDraft","tags":["Branch File Drafts"],"summary":"Replace a pending file draft","description":"Save an existing source file’s pending full-body draft and its durable Yjs repair without creating an immutable version. Returns the actual draft sequence; identical bodies retain it. expected_draft_version guards the pending sequence (0 means no prior draft), separately from commit expected-version IDs; omit for unconditional replacement. Stale values return 409. URL-encode filePath, e.g. pages%2Findex.mdx. GraphQL updateDraftContent and MCP update_project_file_draft counterparts.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Full pending source-file body; empty strings are valid."},"expected_draft_version":{"type":["integer","null"],"minimum":0,"maximum":2147483647,"description":"Expected current draft sequence, not a committed version ID. 0 requires no prior draft; a stale value returns 409. Omit/null for an unconditional full-body replacement."}},"required":["content"]}}}},"responses":{"200":{"description":"Persisted pending draft","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"updated_at":{"type":"string"},"version":{"type":"integer","minimum":1,"description":"Current pending draft sequence; resets after commit/discard. Use as expected_draft_version for a guarded draft write."},"entity_type":{"type":"string","enum":["page","component","function","virtual_file"],"description":"Canonical source-file type."},"_links":{"type":"object","additionalProperties":{}}},"required":["path","content","updated_at"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteBranchFileDraft","tags":["Branch File Drafts"],"summary":"Delete branch file draft","description":"Discard pending updates for an existing source file and queue durable restoration of its committed body. Already absent drafts succeed with an empty 204 response; missing files/branches return 404. Requires project.files.write. URL-encode filePath. MCP delete_project_file_draft returns a success object; GraphQL deleteDraftContent preserves idempotent success for unknown file references.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"}],"responses":{"204":{"description":"Draft discarded"},"400":{"description":"Missing file path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Project files write capability required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/environments/{environmentName}/files":{"get":{"operationId":"listEnvironmentFiles","tags":["Environment Files"],"summary":"List environment files","description":"Returns all file fields including content by default. To select response fields, use `?fields=(id,path,size)`.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Environment name (for example, production, preview)."},"required":true,"name":"environmentName","in":"path"},{"schema":{"type":"string","maxLength":1024,"description":"Provide the pattern."},"required":false,"description":"Provide the pattern.","name":"pattern","in":"query"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["path","updated_at"],"default":"updated_at"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_server_functions","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"Files from the environment with selectable response fields.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"type":{"type":"string","enum":["page","function","component","file"]},"size":{"type":"number"},"updated_at":{"type":"string"},"_links":{"type":"object","additionalProperties":{}}},"required":["id","version_id","path","content","type","size","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"},"environment_id":{"type":"string"},"environment_name":{"type":"string"},"release_id":{"type":"string"},"release_version":{"type":["string","null"]},"_links":{"type":"object","additionalProperties":{}}},"required":["data","page_info","environment_id","environment_name","release_id","release_version"]}}}},"400":{"description":"Invalid fields, filter, sort, cursor, or page size; limit must be an integer from 1 to 100.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient project permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/environments/{environmentName}/files/{filePath}":{"get":{"operationId":"getEnvironmentFile","tags":["Environment Files"],"summary":"Get environment file","description":"Returns all file fields including content by default. To select response fields, use `?fields=(id,path,size)`. If the file path contains special characters, URL-encode the `filePath` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Environment name (for example, production, preview)."},"required":true,"name":"environmentName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_server_functions","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"File from the environment with selectable response fields.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number"},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"},"environment_id":{"type":"string"},"environment_name":{"type":"string"},"release_id":{"type":"string"},"release_version":{"type":["string","null"]},"_links":{"type":"object","additionalProperties":{}}},"required":["id","version_id","path","content","size","type","updated_at","environment_id","environment_name","release_id","release_version"]}}}},"400":{"description":"Missing file path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Restricted server-function source or insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/environments/{environmentName}/files/{filePath}/diff":{"get":{"operationId":"getEnvironmentFileDiff","tags":["Environment Files"],"summary":"Get environment file diff","description":"Returns a unified diff (git-compatible format) comparing the environment file version to main branch or a specific version. If the file path contains special characters, URL-encode the `filePath` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Environment name (for example, production, preview)."},"required":true,"name":"environmentName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","description":"Source version ID to compare from (default: main branch current version)"},"required":false,"name":"source_ref","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10,"default":3,"description":"Number of context lines around changes (default: 3)"},"required":false,"name":"context_lines","in":"query"}],"responses":{"200":{"description":"Unified diff","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"diff":{"type":"string","description":"Unified diff format string (git-compatible)"},"additions":{"type":"number","description":"Number of lines added"},"deletions":{"type":"number","description":"Number of lines deleted"}},"required":["path","diff","additions","deletions"]}}}},"400":{"description":"Invalid request parameters; context_lines must be an integer from 0 to 10.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Restricted server-function source or insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases/{version}/files":{"get":{"operationId":"listReleaseFiles","tags":["Release Files"],"summary":"List release files","description":"Returns all file fields including content by default. To select response fields, use `?fields=(id,path,size)`.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Release version (for example, \"1.2.3\" or \"latest\")."},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","maxLength":1024,"description":"Provide the pattern."},"required":false,"description":"Provide the pattern.","name":"pattern","in":"query"},{"$ref":"#/components/parameters/PaginationCursor"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["path","updated_at"],"default":"updated_at"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_server_functions","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"Files from the release with selectable response fields.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"type":{"type":"string","enum":["page","function","component","file"]},"size":{"type":"number"},"updated_at":{"type":"string"},"_links":{"type":"object","additionalProperties":{}}},"required":["id","version_id","path","content","type","size","updated_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"},"release_id":{"type":"string"},"release_version":{"type":["string","null"]},"_links":{"type":"object","additionalProperties":{}}},"required":["data","page_info","release_id","release_version"]}}}},"400":{"description":"Invalid fields, filter, sort, cursor, or page size; limit must be an integer from 1 to 100.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient project permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases/{version}/files/{filePath}":{"get":{"operationId":"getReleaseFile","tags":["Release Files"],"summary":"Get release file","description":"Returns all file fields including content by default. To select response fields, use `?fields=(id,path,size)`. If the file path contains special characters, URL-encode the `filePath` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Release version (for example, \"1.2.3\" or \"latest\")."},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_server_functions","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"File from the release with selectable response fields.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number"},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"},"release_id":{"type":"string"},"release_version":{"type":["string","null"]},"_links":{"type":"object","additionalProperties":{}}},"required":["id","version_id","path","content","size","type","updated_at","release_id","release_version"]}}}},"400":{"description":"Missing file path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Restricted server-function source or insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases/{version}/files/{filePath}/diff":{"get":{"operationId":"getReleaseFileDiff","tags":["Release Files"],"summary":"Get release file diff","description":"Returns a unified diff (git-compatible format) comparing the release file version to main branch or a specific version. If the file path contains special characters, URL-encode the `filePath` parameter (for example, `pages%2Findex.mdx` for `pages/index.mdx`).","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Release version (for example, \"1.2.3\" or \"latest\")."},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, for example, pages%2Findex.mdx)."},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","description":"Source version ID to compare from (default: main branch current version)"},"required":false,"name":"source_ref","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10,"default":3,"description":"Number of context lines around changes (default: 3)"},"required":false,"name":"context_lines","in":"query"}],"responses":{"200":{"description":"Unified diff","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"diff":{"type":"string","description":"Unified diff format string (git-compatible)"},"additions":{"type":"number","description":"Number of lines added"},"deletions":{"type":"number","description":"Number of lines deleted"}},"required":["path","diff","additions","deletions"]}}}},"400":{"description":"Invalid request parameters; context_lines must be an integer from 0 to 10.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Restricted server-function source or insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads":{"get":{"operationId":"listUploads","tags":["Project Uploads"],"summary":"List uploads","description":"Visible folders and files. File limit applies before visibility filtering; follow non-null continuation even if no files are visible. Folders are separate from file pagination and unpaginated. Use path to select direct-child files; omit to list all project files.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Folder path prefix to list (for example, \"assets/\"). Omit for root."},"required":false,"name":"path","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation; copy unchanged with the same project/path/sort. A removed anchor requires restarting; live changes affect traversal. Legacy ISO timestamps retain the creation cutoff and cannot recover ties."},"required":false,"name":"cursor","in":"query"},{"$ref":"#/components/parameters/PaginationLimit"},{"schema":{"type":"string","enum":["created_at","name","size"],"default":"created_at","description":"Sort field. Defaults to \"created_at\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"boolean","default":true,"description":"When true, returns all nested folders under the given path (or all folders if no path). Default: true."},"required":false,"name":"recursive","in":"query"}],"responses":{"200":{"description":"Paginated list of folders and files. Each item has `type: \"folder\"` or `type: \"file\"`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/UploadFolder"},{"$ref":"#/components/schemas/UploadFile"}],"discriminator":{"propertyName":"type","mapping":{"folder":"#/components/schemas/UploadFolder","file":"#/components/schemas/UploadFile"}},"description":"Upload item — either a folder (type: \"folder\") or a file (type: \"file\")"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Invalid request parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or upload path not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"uploadFile","tags":["Project Uploads"],"summary":"Upload file","description":"Creates a signed URL that allows direct upload to cloud storage. Client must declare the file size upfront for quota tracking.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file_path":{"type":"string","description":"Path where the file will be stored"},"content_type":{"type":"string","description":"MIME type of the file"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"exclusiveMinimum":0,"description":"File size in bytes (required for quota tracking)"}},"required":["file_path","size"]}}}},"responses":{"201":{"description":"Signed upload URL created","content":{"application/json":{"schema":{"type":"object","properties":{"file_upload_url":{"type":"string","description":"Temporary cloud-storage URL for the upload PUT request."},"file_path":{"type":"string","description":"Project-relative path assigned to the upload."},"upload_id":{"type":"string","description":"UUID of the pending upload record."},"required_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers that must be included in the PUT request to the upload URL","example":{"Content-Type":"image/png","x-goog-content-length-range":"0,1048576"}}},"required":["file_upload_url","file_path","upload_id","required_headers"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Payment required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/QuotaProblem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/{upload_reference}":{"get":{"operationId":"getUpload","tags":["Project Uploads"],"summary":"Get upload","description":"Returns an uploaded file by ID or path. Public uploads allow anonymous access; private uploads require authentication.\n\nWith `Accept: application/json`, returns metadata. With `Accept: application/octet-stream`, streams file bytes through the API. Otherwise, returns a `302` redirect to a signed download URL, suitable for an image’s `src` attribute.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Upload ID (UUID) or URL-encoded file path"},"required":true,"name":"upload_reference","in":"path"}],"responses":{"200":{"description":"File metadata or binary content, selected by the Accept header","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Upload UUID."},"path":{"type":"string","description":"Project-relative storage path, without a leading slash."},"file_name":{"type":"string","description":"File name from the upload record."},"content_type":{"type":["string","null"],"description":"Stored MIME type, or null when unspecified."},"size":{"type":"number","description":"Declared file size in bytes."},"url":{"type":["string","null"],"description":"API URL for downloading the upload; access depends on its visibility."},"status":{"type":"string","enum":["pending","active","failed"],"description":"Upload lifecycle state: pending until finalized, active when available, or failed."},"visibility":{"type":"string","enum":["project","public","private"],"description":"Effective access policy for the upload or folder."},"created_at":{"type":"string","description":"Creation timestamp in ISO 8601 format."},"updated_at":{"type":"string","description":"Last update timestamp in ISO 8601 format."},"deleted_at":{"type":["string","null"],"description":"Soft deletion timestamp in ISO 8601 format, or null for an undeleted upload."}},"required":["id","path","file_name","content_type","size","url","status","visibility","created_at","updated_at","deleted_at"]}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"302":{"description":"Redirect to signed URL (default behavior for browsers/img tags)"},"400":{"description":"Invalid request parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The caller lacks access to the upload or path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"File not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteUpload","tags":["Project Uploads"],"summary":"Delete upload","description":"Soft deletes a user-uploaded file record. Restoration requires that the deleted record still exists; no deletion-age cutoff is enforced by restore.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Upload ID (UUID) or URL-encoded file path"},"required":true,"name":"upload_reference","in":"path"}],"responses":{"204":{"description":"File deleted successfully"},"400":{"description":"Missing file path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The caller lacks access to the upload or path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"File not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/{upload_reference}/url":{"get":{"operationId":"getUploadDownloadUrl","tags":["Project Uploads"],"summary":"Get upload download URL","description":"Returns a signed download URL. URLs expire after 30 minutes for private files or 24 hours for public files. Use `ttl` to request a shorter lifetime; it cannot exceed the limit for the file’s visibility.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Upload ID (UUID) or URL-encoded file path"},"required":true,"name":"upload_reference","in":"path"},{"schema":{"type":"number","minimum":60,"maximum":86400,"description":"Requested signed URL lifetime in seconds, from 60 to 86400. Private uploads are capped at 1800 seconds; public uploads at 86400 seconds."},"required":false,"name":"ttl","in":"query"}],"responses":{"200":{"description":"Signed download URL","content":{"application/json":{"schema":{"type":"object","properties":{"signed_url":{"type":"string","description":"Temporary cloud-storage download URL."},"expires_at":{"type":"string","description":"Signed URL expiration timestamp in ISO 8601 format."}},"required":["signed_url","expires_at"]}}}},"400":{"description":"Invalid request parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The caller lacks access to the upload or path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"File not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/{upload_reference}/move":{"post":{"operationId":"moveUpload","tags":["Project Uploads"],"summary":"Move upload","description":"Moves a user-uploaded file from one path to another within the project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Upload ID (UUID) or URL-encoded file path"},"required":true,"name":"upload_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_path":{"type":"string","description":"Destination file path"}},"required":["new_path"]}}}},"responses":{"200":{"description":"File moved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the upload was moved successfully."},"error":{"type":"string","description":"Move failure details, when supplied."},"file":{"type":"object","properties":{"id":{"type":"string","description":"Upload UUID."},"path":{"type":"string","description":"Project-relative storage path, without a leading slash."},"file_name":{"type":"string","description":"File name from the upload record."},"content_type":{"type":["string","null"],"description":"Stored MIME type, or null when unspecified."},"size":{"type":"number","description":"Declared file size in bytes."},"url":{"type":["string","null"],"description":"API URL for downloading the upload; access depends on its visibility."},"status":{"type":"string","enum":["pending","active","failed"],"description":"Upload lifecycle state: pending until finalized, active when available, or failed."},"visibility":{"type":"string","enum":["project","public","private"],"description":"Effective access policy for the upload or folder."},"created_at":{"type":"string","description":"Creation timestamp in ISO 8601 format."},"updated_at":{"type":"string","description":"Last update timestamp in ISO 8601 format."},"deleted_at":{"type":["string","null"],"description":"Soft deletion timestamp in ISO 8601 format, or null for an undeleted upload."}},"required":["id","path","file_name","content_type","size","url","status","visibility","created_at","updated_at","deleted_at"],"description":"Upload metadata after the move, when available."}},"required":["success"]}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The caller lacks access to the upload or path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Source file not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/{upload_reference}/restore":{"post":{"operationId":"restoreUpload","tags":["Project Uploads"],"summary":"Restore upload","description":"Restores an existing soft-deleted upload record by UUID or project-relative path. No deletion-age cutoff is enforced; stored content availability is not checked. An active path is rejected; otherwise a path selects the latest deletion, then descending UUID.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Upload UUID selects that exact row; URL-encoded project-relative path selects an active row first, otherwise latest deletion then descending UUID."},"required":true,"name":"upload_reference","in":"path"}],"responses":{"200":{"description":"File restored successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Upload UUID."},"path":{"type":"string","description":"Project-relative storage path, without a leading slash."},"file_name":{"type":"string","description":"File name from the upload record."},"content_type":{"type":["string","null"],"description":"Stored MIME type, or null when unspecified."},"size":{"type":"number","description":"Declared file size in bytes."},"url":{"type":["string","null"],"description":"API URL for downloading the upload; access depends on its visibility."},"status":{"type":"string","enum":["pending","active","failed"],"description":"Upload lifecycle state: pending until finalized, active when available, or failed."},"visibility":{"type":"string","enum":["project","public","private"],"description":"Effective access policy for the upload or folder."},"created_at":{"type":"string","description":"Creation timestamp in ISO 8601 format."},"updated_at":{"type":"string","description":"Last update timestamp in ISO 8601 format."},"deleted_at":{"type":["string","null"],"description":"Soft deletion timestamp in ISO 8601 format, or null for an undeleted upload."}},"required":["id","path","file_name","content_type","size","url","status","visibility","created_at","updated_at","deleted_at"]}}}},"400":{"description":"Invalid request, or the upload is not soft-deleted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The caller lacks access to the upload or path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or upload not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Upload is being collected, or its path is occupied by an active upload","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/folders":{"post":{"operationId":"createFolder","tags":["Upload Folders"],"summary":"Create folder","description":"Create a folder with optional visibility (default: internal).","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"Folder path (for example, \"assets/images/\"). Trailing slash is added automatically."},"visibility":{"type":"string","enum":["project","public","private"],"default":"project"}},"required":["path"]}}}},"responses":{"201":{"description":"Folder created","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"Project-relative storage path, without a leading slash."},"visibility":{"type":"string","enum":["project","public","private"],"description":"Effective access policy for the upload or folder."}},"required":["path","visibility"]}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or upload path not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/folders/{path}":{"delete":{"operationId":"deleteFolder","tags":["Upload Folders"],"summary":"Delete folder","description":"Delete a folder, its visibility setting, all child folder visibility settings, and soft-deletes all files under the folder prefix.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"URL-encoded folder path (for example, \"assets%2Fimages%2F\")."},"required":true,"name":"path","in":"path"}],"responses":{"204":{"description":"Folder deleted"},"400":{"description":"Invalid URL encoding in path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Folder not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/folders/{path}/rename":{"post":{"operationId":"renameFolder","tags":["Upload Folders"],"summary":"Rename folder","description":"Renames/moves a folder and all its contents (subfolders, files, shares) to a new path.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"URL-encoded source folder path (for example, \"assets%2Fimages%2F\")."},"required":true,"name":"path","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"string","description":"Destination folder path (for example, \"assets/photos/\")."}},"required":["destination"]}}}},"responses":{"200":{"description":"Folder renamed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"old_path":{"type":"string","description":"Folder path before the rename."},"new_path":{"type":"string","description":"Folder path after the rename."},"folders_moved":{"type":"number","description":"Number of folder records moved."},"files_moved":{"type":"number","description":"Number of upload records moved."}},"required":["old_path","new_path","folders_moved","files_moved"]}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Source folder not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Destination folder already exists","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/grants/{path}":{"get":{"operationId":"listGrants","tags":["Upload Grants"],"summary":"List grants","description":"Lists recipient grants for the resolved path; requires path administration.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Upload UUID or double-URL-encoded project-relative file path or applicable folder prefix."},"required":true,"name":"path","in":"path"}],"responses":{"200":{"description":"Grants list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","description":"UUID of the user receiving the grant."},"permission":{"type":"string","enum":["read","write","admin"],"description":"Access granted to this user: read, write, or admin."},"created_at":{"type":"string","description":"Creation timestamp in ISO 8601 format."}},"required":["user_id","permission","created_at"]}},"resolved_path":{"type":"string","description":"Path whose effective grants were resolved."},"resolved_type":{"type":"string","enum":["folder","upload"],"description":"Whether the resolved grant target is a folder or upload."},"resolved_id":{"type":"string","description":"UUID of the resolved grant target, when available."}},"required":["data","resolved_path"]}}}},"400":{"description":"Invalid URL encoding in path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication is required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Admin access required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or upload path not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"setGrants","tags":["Upload Grants"],"summary":"Set grants","description":"Replaces all recipient grants for the resolved path. An empty list revokes every grant; requires path administration.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Upload UUID or double-URL-encoded project-relative file path or applicable folder prefix."},"required":true,"name":"path","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"permission":{"type":"string","enum":["read","write","admin"],"default":"read"}},"required":["user_id"]}}},"required":["grants"]}}}},"responses":{"200":{"description":"Grants set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","description":"UUID of the user receiving the grant."},"permission":{"type":"string","enum":["read","write","admin"],"description":"Access granted to this user: read, write, or admin."},"created_at":{"type":"string","description":"Creation timestamp in ISO 8601 format."}},"required":["user_id","permission","created_at"]}},"resolved_path":{"type":"string","description":"Path whose effective grants were resolved."},"resolved_type":{"type":"string","enum":["folder","upload"],"description":"Whether the resolved grant target is a folder or upload."},"resolved_id":{"type":"string","description":"UUID of the resolved grant target, when available."}},"required":["data","resolved_path"]}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication is required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Admin access required to manage grants","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or upload path not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/grants/{path}/{user_id}":{"delete":{"operationId":"revokeGrant","tags":["Upload Grants"],"summary":"Revoke grant","description":"Remove a grant from a private path.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Upload UUID or double-URL-encoded project-relative file path or applicable folder prefix."},"required":true,"name":"path","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Recipient user UUID whose grant is revoked"},"required":true,"name":"user_id","in":"path"}],"responses":{"204":{"description":"Grant removed"},"400":{"description":"Invalid recipient UUID or path encoding, or no applicable visibility target","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication is required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Admin access required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or grant not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/uploads/visibility/{path}":{"put":{"operationId":"setPathVisibility","tags":["Upload Visibility"],"summary":"Set path visibility","description":"Sets visibility for a file or folder prefix, creating the setting when absent. Requires path administration; public visibility follows the paid-project policy.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Double-URL-encoded project-relative file path or folder prefix. An existing folder also accepts its path without the trailing slash."},"required":true,"name":"path","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"visibility":{"type":"string","enum":["project","public","private"]}},"required":["visibility"]}}}},"responses":{"200":{"description":"Visibility set","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"Project-relative storage path, without a leading slash."},"visibility":{"type":"string","enum":["project","public","private"],"description":"Effective access policy for the upload or folder."}},"required":["path","visibility"]}}}},"400":{"description":"Invalid URL encoding in path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication is required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The caller lacks access to the upload or path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or upload path not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"removePathVisibility","tags":["Upload Visibility"],"summary":"Remove path visibility","description":"Removes the visibility setting for a path. Files revert to the nearest parent setting or default project visibility.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Double-URL-encoded project-relative file path or folder prefix. An existing folder also accepts its path without the trailing slash."},"required":true,"name":"path","in":"path"}],"responses":{"204":{"description":"Visibility removed"},"400":{"description":"Invalid URL encoding in path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication is required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The caller lacks access to the upload or path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or visibility setting not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/dependencies/history":{"get":{"operationId":"getProjectDependencyHistory","tags":["Dependencies"],"summary":"Get recent project dependency metadata","description":"Returns bounded, unexpired raw dependency declarations captured by the API around guarded package.json mutations.","parameters":[{"schema":{"type":"string","description":"Project slug, UUID, or domain"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Branch name or UUID, 1–255 characters without surrounding whitespace. Omit for main."},"required":false,"description":"Branch name or UUID, 1–255 characters without surrounding whitespace. Omit for main.","name":"branch","in":"query"}],"responses":{"200":{"description":"Recent raw dependency metadata for the resolved project and branch scope","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"project_id":{"type":"string","format":"uuid"},"branch":{"type":["string","null"]},"entries":{"type":"array","items":{"type":"object","properties":{"dependencies":{"type":"object","additionalProperties":{"type":"string"}},"expires_at":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Expiry in Unix epoch milliseconds. Unexpired snapshots are retained for at most 23 hours 59 minutes from capture."}},"required":["dependencies","expires_at"]},"maxItems":16}},"required":["version","project_id","branch","entries"]}}}},"400":{"description":"Invalid branch reference","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden — project.files.read capability required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or branch not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/dependencies/resolve":{"post":{"operationId":"resolveProjectDependencies","tags":["Dependencies"],"summary":"Resolve and pin project dependencies","description":"Resolves npm package specifiers to exact version strings and persists them into the project's package.json. Inline exact versions are used as-is; ranges and bare names are resolved against the npm registry (cached in Redis). Pre-existing exact pins are never overwritten. Unknown packages and registry failures produce partial success — the affected specifiers are omitted from the response rather than failing the entire batch.","parameters":[{"schema":{"type":"string","description":"Project slug, UUID, or domain"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"specifiers":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":1,"maxItems":100,"description":"npm package specifiers to resolve. Each entry may be a bare name, a name with an inline exact version, or a name with a semver range (for example, \"react\", \"got@12.6.1\", \"zod@^3\", \"@radix-ui/react-dialog\").","example":["styled-components","@radix-ui/react-dialog","got@12.6.1","zod@^3"]},"branch":{"type":"string","minLength":1,"maxLength":255,"description":"Branch name or UUID, 1–255 characters without surrounding whitespace. Omit for main; selected package.json receives the resolved pins.","example":"feature-a"},"expected_declarations":{"type":"object","additionalProperties":{"type":["string","null"],"maxLength":200},"description":"Package declarations observed by the caller, at most 100 entries with string values up to 200 characters. A null value means the package was absent. When supplied, every requested package must be present and stale declarations are not overwritten.","example":{"styled-components":"^6","got":null}}},"required":["specifiers"]}}}},"responses":{"200":{"description":"Resolved pins (may be a partial set if some specifiers failed)","content":{"application/json":{"schema":{"type":"object","properties":{"pins":{"type":"object","additionalProperties":{"type":"string"},"description":"Resolved exact version pins keyed by package name. Includes both newly-written pins and pre-existing exact pins for all requested specifiers that were successfully resolved.","example":{"styled-components":"6.3.5","got":"12.6.1","zod":"3.23.8"}},"persisted":{"type":"boolean","description":"True when eligible pins were persisted to package.json or no eligible write was needed. False means persistence failed; pins retain intended values and the caller may retry."},"skipped":{"type":"object","additionalProperties":{"type":"string","enum":["declaration_changed"]},"description":"Requested packages not written because the current declaration no longer matched the caller snapshot.","example":{"zod":"declaration_changed"}}},"required":["pins","persisted","skipped"]}}}},"400":{"description":"Invalid specifier syntax or batch size exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden — project.files.write capability required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or branch not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/dependency-artifacts/lookup":{"post":{"operationId":"lookupDependencyArtifacts","tags":["Dependency artifacts"],"summary":"Look up dependency artifacts","description":"Returns durable artifact states for exact public npm identities. Requires a project-scoped veryfront-server service-account token with files:read.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"artifacts":{"type":"array","items":{"type":"object","properties":{"origin_key":{"type":"string","enum":["npm:public"],"description":"Public npm registry identity; other origins are not accepted."},"package_name":{"type":"string","minLength":1,"maxLength":214,"pattern":"^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$","description":"Exact npm package name, including scope when present."},"exact_version":{"type":"string","minLength":1,"maxLength":128,"description":"Exact semantic version; ranges and tags are not accepted."},"subpath":{"type":"string","maxLength":512,"default":"","description":"Package-relative export subpath. Empty string selects the package root."},"target":{"type":"string","enum":["es2022"],"description":"JavaScript compilation target; currently es2022."},"profile":{"type":"string","enum":["standard-v1","react-v1","react-dom-v1"],"description":"react-v1 for react, react-dom-v1 for react-dom, standard-v1 otherwise. Selects externals and ingest revision."}},"required":["origin_key","package_name","exact_version","target","profile"],"additionalProperties":false},"minItems":1,"maxItems":100,"description":"One to 100 unique canonical package identities."}},"required":["artifacts"],"additionalProperties":false}}}},"responses":{"200":{"description":"Dependency artifact states","content":{"application/json":{"schema":{"type":"object","properties":{"artifacts":{"type":"array","items":{"type":"object","properties":{"identity":{"type":"object","properties":{"origin_key":{"type":"string","enum":["npm:public"],"description":"Public npm registry identity; other origins are not accepted."},"package_name":{"type":"string","minLength":1,"maxLength":214,"pattern":"^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$","description":"Exact npm package name, including scope when present."},"exact_version":{"type":"string","minLength":1,"maxLength":128,"description":"Exact semantic version; ranges and tags are not accepted."},"subpath":{"type":"string","maxLength":512,"default":"","description":"Package-relative export subpath. Empty string selects the package root."},"target":{"type":"string","enum":["es2022"],"description":"JavaScript compilation target; currently es2022."},"profile":{"type":"string","enum":["standard-v1","react-v1","react-dom-v1"],"description":"react-v1 for react, react-dom-v1 for react-dom, standard-v1 otherwise. Selects externals and ingest revision."}},"required":["origin_key","package_name","exact_version","target","profile"],"additionalProperties":false,"description":"Requested identity with defaults applied."},"key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lowercase SHA-256 of the canonical artifact identity."},"status":{"type":"string","enum":["ready","missing","building","failed","denied"],"description":"Durable registry state; denied overrides build state when policy rejects the artifact."},"root_content_hash":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"Stored root JavaScript asset SHA-256, or null when unavailable."},"graph_schema_version":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Graph publication format version; null when unavailable in lookup results."},"attempt_count":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Claimed build attempt number; stale publication attempts return 412. Null when no registry record exists."},"retry_after":{"type":["string","null"],"format":"date-time","description":"Retry eligibility timestamp; null or absent when no retry time is recorded."},"failure_code":{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"Sanitized build failure or policy denial code; null for other lookup states."}},"required":["identity","key_hash","status","root_content_hash","graph_schema_version","attempt_count","retry_after","failure_code"]},"description":"One result for each requested identity, in request order."}},"required":["artifacts"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-audience":"component-internal"}},"/dependency-artifacts/ensure":{"post":{"operationId":"ensureDependencyArtifacts","tags":["Dependency artifacts"],"summary":"Ensure dependency artifacts","description":"Returns durable artifact states for exact public npm identities. Requires a project-scoped veryfront-server service-account token with files:read. Does not enqueue builds; missing artifacts remain missing.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"artifacts":{"type":"array","items":{"type":"object","properties":{"origin_key":{"type":"string","enum":["npm:public"],"description":"Public npm registry identity; other origins are not accepted."},"package_name":{"type":"string","minLength":1,"maxLength":214,"pattern":"^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$","description":"Exact npm package name, including scope when present."},"exact_version":{"type":"string","minLength":1,"maxLength":128,"description":"Exact semantic version; ranges and tags are not accepted."},"subpath":{"type":"string","maxLength":512,"default":"","description":"Package-relative export subpath. Empty string selects the package root."},"target":{"type":"string","enum":["es2022"],"description":"JavaScript compilation target; currently es2022."},"profile":{"type":"string","enum":["standard-v1","react-v1","react-dom-v1"],"description":"react-v1 for react, react-dom-v1 for react-dom, standard-v1 otherwise. Selects externals and ingest revision."}},"required":["origin_key","package_name","exact_version","target","profile"],"additionalProperties":false},"minItems":1,"maxItems":100,"description":"One to 100 unique canonical package identities."}},"required":["artifacts"],"additionalProperties":false}}}},"responses":{"200":{"description":"Dependency artifact states","content":{"application/json":{"schema":{"type":"object","properties":{"artifacts":{"type":"array","items":{"type":"object","properties":{"identity":{"type":"object","properties":{"origin_key":{"type":"string","enum":["npm:public"],"description":"Public npm registry identity; other origins are not accepted."},"package_name":{"type":"string","minLength":1,"maxLength":214,"pattern":"^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$","description":"Exact npm package name, including scope when present."},"exact_version":{"type":"string","minLength":1,"maxLength":128,"description":"Exact semantic version; ranges and tags are not accepted."},"subpath":{"type":"string","maxLength":512,"default":"","description":"Package-relative export subpath. Empty string selects the package root."},"target":{"type":"string","enum":["es2022"],"description":"JavaScript compilation target; currently es2022."},"profile":{"type":"string","enum":["standard-v1","react-v1","react-dom-v1"],"description":"react-v1 for react, react-dom-v1 for react-dom, standard-v1 otherwise. Selects externals and ingest revision."}},"required":["origin_key","package_name","exact_version","target","profile"],"additionalProperties":false,"description":"Requested identity with defaults applied."},"key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lowercase SHA-256 of the canonical artifact identity."},"status":{"type":"string","enum":["ready","missing","building","failed","denied"],"description":"Durable registry state; denied overrides build state when policy rejects the artifact."},"root_content_hash":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"Stored root JavaScript asset SHA-256, or null when unavailable."},"graph_schema_version":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Graph publication format version; null when unavailable in lookup results."},"attempt_count":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Claimed build attempt number; stale publication attempts return 412. Null when no registry record exists."},"retry_after":{"type":["string","null"],"format":"date-time","description":"Retry eligibility timestamp; null or absent when no retry time is recorded."},"failure_code":{"type":["string","null"],"minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"Sanitized build failure or policy denial code; null for other lookup states."}},"required":["identity","key_hash","status","root_content_hash","graph_schema_version","attempt_count","retry_after","failure_code"]},"description":"One result for each requested identity, in request order."}},"required":["artifacts"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-audience":"component-internal"}},"/dependency-artifacts/{artifact_id}/attempts/{attempt_count}/assets/{content_hash}":{"put":{"operationId":"uploadDependencyArtifactAsset","tags":["Dependency artifacts"],"summary":"Upload a dependency artifact asset","description":"Uploads immutable binary asset bytes, up to 10 MiB (10485760 bytes), after verifying the signed runtime owns the current artifact build attempt. Requires files:write and a signed run ID. Content-Type must be text/javascript or text/css; parameters are ignored. The URL hash must match the SHA-256 of the bytes.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Registry artifact UUID assigned to the claimed build."},"required":true,"description":"Registry artifact UUID assigned to the claimed build.","name":"artifact_id","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"description":"Current claimed build attempt number; stale attempts return 412."},"required":true,"description":"Current claimed build attempt number; stale attempts return 412.","name":"attempt_count","in":"path"},{"schema":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lowercase SHA-256 of the immutable asset bytes."},"required":true,"description":"Lowercase SHA-256 of the immutable asset bytes.","name":"content_hash","in":"path"}],"requestBody":{"required":true,"content":{"*/*":{"schema":{"type":"string","format":"binary","maxLength":10485760,"description":"Immutable asset bytes. Maximum 10 MiB (10485760 bytes)."}}}},"responses":{"200":{"description":"Asset stored","content":{"application/json":{"schema":{"type":"object","properties":{"stored":{"type":"boolean","enum":[true],"description":"The immutable asset is available in storage."},"existed":{"type":"boolean","description":"True when the same content-addressed asset already existed."}},"required":["stored","existed"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"412":{"description":"Precondition failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-audience":"component-internal"}},"/dependency-artifacts/{artifact_id}/attempts/{attempt_count}/result":{"post":{"operationId":"reportDependencyArtifactBuildResult","tags":["Dependency artifacts"],"summary":"Report a dependency artifact build result","description":"Publishes a complete verified graph or records a sanitized failure for the build attempt owned by the signed runtime run. Requires a project-scoped veryfront-server service-account token with files:write and a signed run ID. Ready graphs must reference uploaded assets with matching media types and byte sizes; stale attempts return 412.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Registry artifact UUID assigned to the claimed build."},"required":true,"description":"Registry artifact UUID assigned to the claimed build.","name":"artifact_id","in":"path"},{"schema":{"type":"integer","exclusiveMinimum":0,"description":"Current claimed build attempt number; stale attempts return 412."},"required":true,"description":"Current claimed build attempt number; stale attempts return 412.","name":"attempt_count","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"outcome":{"type":"string","enum":["ready"],"description":"Build result discriminant: ready publishes a verified graph; failed records a sanitized failure."},"graph":{"type":"object","properties":{"graph_schema_version":{"type":"integer","exclusiveMinimum":0,"description":"Graph publication format version."},"root_content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Root JavaScript asset SHA-256; must appear in assets."},"assets":{"type":"array","items":{"type":"object","properties":{"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lowercase SHA-256 of the immutable asset bytes."},"content_type":{"type":"string","enum":["text/javascript","text/css"],"description":"Uploaded asset media type; must match stored metadata."},"size":{"type":"integer","minimum":0,"description":"Asset byte length; must match stored metadata."}},"required":["content_hash","content_type","size"],"additionalProperties":false},"minItems":1,"maxItems":1024,"description":"One to 1024 unique uploaded assets forming the complete graph."}},"required":["graph_schema_version","root_content_hash","assets"],"additionalProperties":false,"description":"Complete graph whose uploaded asset metadata is verified before publication."}},"required":["outcome","graph"],"additionalProperties":false},{"type":"object","properties":{"outcome":{"type":"string","enum":["failed"],"description":"Build result discriminant: ready publishes a verified graph; failed records a sanitized failure."},"failure_code":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"Sanitized machine-readable build failure code."},"failure_message":{"type":"string","minLength":1,"maxLength":500,"description":"Optional sanitized failure message stored with the attempt; absent becomes null."},"retry_after":{"type":"string","format":"date-time","description":"Optional retry eligibility timestamp; absent becomes null."}},"required":["outcome","failure_code"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Build result accepted","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true],"description":"The current build attempt accepted the result."},"state":{"type":"string","enum":["ready","failed"],"description":"Persisted build state after accepting the result."}},"required":["accepted","state"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"412":{"description":"Precondition failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-audience":"component-internal"}},"/projects/{project_reference}/style-artifacts/current":{"get":{"operationId":"resolveProjectStyleArtifact","tags":["Style artifacts"],"summary":"Resolve current project style artifact","description":"Read current CSS artifact metadata for exactly one selector and a style profile. Returns ready, building, failed, or missing state; this operation does not build or upload assets.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1,"description":"Style profile identifier used with the selector to find current metadata."},"required":true,"description":"Style profile identifier used with the selector to find current metadata.","name":"style_profile_hash","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Branch name. Exactly one of branch, environment_name, or release_id is required."},"required":false,"description":"Branch name. Exactly one of branch, environment_name, or release_id is required.","name":"branch","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Environment name. Exactly one selector is required."},"required":false,"description":"Environment name. Exactly one selector is required.","name":"environment_name","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Release UUID. Exactly one selector is required."},"required":false,"description":"Release UUID. Exactly one selector is required.","name":"release_id","in":"query"}],"responses":{"200":{"description":"Current style artifact metadata","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ready","missing","building","failed"],"description":"Current metadata state. Missing means no record exists; building does not confirm completion."},"artifact_hash":{"type":"string","description":"Registered CSS artifact hash, omitted when not available."},"asset_path":{"type":"string","description":"Registered CSS asset path, omitted when not available."},"etag":{"type":"string","description":"Registered CSS asset entity tag, omitted when not available."},"content_type":{"type":"string","description":"Registered CSS asset MIME type, omitted when not available."},"build_run_id":{"type":"string","minLength":1,"description":"Style build run identifier, when available."},"failure_reason":{"type":"string","description":"Persisted failure detail, omitted when not available."},"updated_at":{"type":"string","description":"Latest metadata update timestamp; omitted for missing metadata."}},"required":["status"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"upsertProjectStyleArtifact","tags":["Style artifacts"],"summary":"Register current project style artifact","description":"Stores building, ready, or failed CSS artifact metadata for a project selector and style profile. Requires project.files.write.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"style_profile_hash":{"type":"string","minLength":1,"description":"Style profile identifier used with the selector to find current metadata."},"branch":{"type":"string","minLength":1,"description":"Branch name. Exactly one of branch, environment_name, or release_id is required."},"environment_name":{"type":"string","minLength":1,"description":"Environment name. Exactly one selector is required."},"release_id":{"type":"string","format":"uuid","description":"Release UUID. Exactly one selector is required."},"status":{"type":"string","enum":["building","ready","failed"],"default":"ready","description":"Metadata state. Ready requires artifact_hash; other states forbid it. Failed requires failure_reason."},"artifact_hash":{"type":"string","minLength":1,"description":"CSS artifact hash; required only for ready status and forbidden for other states."},"asset_path":{"type":"string","minLength":1,"description":"Registered CSS asset path. This operation does not upload the asset."},"content_type":{"type":"string","minLength":1,"description":"Registered MIME type of the CSS asset."},"etag":{"type":"string","minLength":1,"description":"Registered entity tag for the CSS asset."},"build_run_id":{"type":"string","minLength":1,"description":"Style build run identifier, when available."},"failure_reason":{"type":"string","minLength":1,"description":"Failure detail; required when registering failed status."}},"required":["style_profile_hash"]}}}},"responses":{"200":{"description":"Registered style artifact metadata","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ready","missing","building","failed"],"description":"Current metadata state. Missing means no record exists; building does not confirm completion."},"artifact_hash":{"type":"string","description":"Registered CSS artifact hash, omitted when not available."},"asset_path":{"type":"string","description":"Registered CSS asset path, omitted when not available."},"etag":{"type":"string","description":"Registered CSS asset entity tag, omitted when not available."},"content_type":{"type":"string","description":"Registered CSS asset MIME type, omitted when not available."},"build_run_id":{"type":"string","minLength":1,"description":"Style build run identifier, when available."},"failure_reason":{"type":"string","description":"Persisted failure detail, omitted when not available."},"updated_at":{"type":"string","description":"Latest metadata update timestamp; omitted for missing metadata."}},"required":["status"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/style-artifacts/current/builds":{"post":{"operationId":"ensureProjectStyleArtifactBuild","tags":["Style artifacts"],"summary":"Ensure current project style artifact build","description":"Ensure a background build for the selected style artifact and profile. Requires project.files.write. Main may be implicit before its branch row exists. Other branch and environment names must exist in this project; unknown selectors return 404 before a build is dispatched.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"style_profile_hash":{"type":"string","minLength":1,"description":"Style profile identifier used with the selector to find current metadata."},"branch":{"type":"string","minLength":1,"description":"Branch name. Exactly one of branch, environment_name, or release_id is required."},"environment_name":{"type":"string","minLength":1,"description":"Environment name. Exactly one selector is required."},"release_id":{"type":"string","format":"uuid","description":"Release UUID. Exactly one selector is required."},"force":{"type":"boolean","default":false,"description":"Queue a new build even when current metadata is ready or building."}},"required":["style_profile_hash"]}}}},"responses":{"200":{"description":"Current style artifact build state","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ready","missing","building","failed"],"description":"Current metadata state. Missing means no record exists; building does not confirm completion."},"artifact_hash":{"type":"string","description":"Registered CSS artifact hash, omitted when not available."},"asset_path":{"type":"string","description":"Registered CSS asset path, omitted when not available."},"etag":{"type":"string","description":"Registered CSS asset entity tag, omitted when not available."},"content_type":{"type":"string","description":"Registered CSS asset MIME type, omitted when not available."},"build_run_id":{"type":"string","minLength":1,"description":"Style build run identifier, when available."},"failure_reason":{"type":"string","description":"Persisted failure detail, omitted when not available."},"updated_at":{"type":"string","description":"Latest metadata update timestamp; omitted for missing metadata."}},"required":["status"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/favorites":{"get":{"operationId":"listFavorites","tags":["Favorites"],"summary":"List favorites","description":"Lists your favorite project summaries, ordered by favorite creation descending. Favorites do not grant project access.","responses":{"200":{"description":"List of favorite projects","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"updated_at":{"type":"string"},"created_at":{"type":"string"},"is_favorite":{"type":"boolean"}},"required":["id","name","slug","updated_at","created_at","is_favorite"]}},"favorite_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Project IDs in the same order as the complete favorite list."}},"required":["data","favorite_ids"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/favorites/{project_reference}":{"get":{"operationId":"checkFavorite","tags":["Favorites"],"summary":"Check favorite","description":"Check if a specific project is in the user's favorites.","parameters":[{"schema":{"type":"string","description":"Project UUID, slug, or domain","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Favorite status","content":{"application/json":{"schema":{"type":"object","properties":{"is_favorite":{"type":"boolean"},"project_id":{"type":"string","format":"uuid"}},"required":["is_favorite","project_id"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createFavorite","tags":["Favorites"],"summary":"Create favorite","description":"Add your favorite association, returning the existing record when already present.","parameters":[{"schema":{"type":"string","description":"Project UUID, slug, or domain","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"201":{"description":"Project added to favorites","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"favorite":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier of the favorite association."},"user_id":{"type":"string","format":"uuid","description":"User who owns the favorite association."},"project_id":{"type":"string","format":"uuid","description":"Identifier of the favorited project; this association does not grant access."},"created_at":{"type":"string","description":"Timestamp when the favorite association was created."}},"required":["id","user_id","project_id","created_at"]}},"required":["success","favorite"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteFavorite","tags":["Favorites"],"summary":"Delete favorite","description":"Removes your favorite association. Returns 404 if the project or association is missing; the project is unchanged.","parameters":[{"schema":{"type":"string","description":"Project UUID, slug, or domain","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Project removed from favorites","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"project_id":{"type":"string","format":"uuid"}},"required":["success","project_id"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases":{"get":{"operationId":"listReleases","tags":["Releases"],"summary":"List releases","description":"List releases for the resolved project with cursor pagination.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination (release ID)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20,"description":"Maximum number of releases to return. Defaults to 20 and is capped at 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["created_at","version","status"],"default":"created_at","description":"Sort field. Defaults to \"created_at\". The \"status\" field sorts by deploy_status."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of releases","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Release"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"operationId":"createRelease","tags":["Releases"],"summary":"Create release","description":"Create a release for the resolved project.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the release. Auto-generated when omitted."},"branch_reference":{"type":"string","description":"Branch ID or branch name. When omitted, creates the release from the main branch."}}},"example":{"name":"v1.0.0"}}}},"responses":{"201":{"description":"Release created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{release_id}":{"get":{"operationId":"getRelease","tags":["Releases"],"summary":"Get release","description":"Return a release by ID.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Release ID."},"required":true,"name":"release_id","in":"path"}],"responses":{"200":{"description":"Release found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Release not found"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteRelease","tags":["Releases"],"summary":"Delete release","description":"Delete a release from the resolved project.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Release ID."},"required":true,"name":"release_id","in":"path"}],"responses":{"204":{"description":"Release deleted successfully"},"401":{"description":"Unauthorized"},"404":{"description":"Release not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/latest":{"get":{"operationId":"getLatestRelease","tags":["Releases"],"summary":"Get latest release","description":"Return the latest release for the resolved project.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Latest release found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"401":{"description":"Unauthorized"},"404":{"description":"No releases found for this project"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/version/{version_spec}":{"get":{"operationId":"getReleaseByVersion","tags":["Releases"],"summary":"Get release by version","description":"Finds a release by version. Supports exact version (1.2.3), minor range (1.2), or major range (1).","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Version specifier: \"1.2.3\" for exact, \"1.2\" for latest 1.2.x, or \"1\" for latest 1.x.x.","example":"1.2.3"},"required":true,"name":"version_spec","in":"path"}],"responses":{"200":{"description":"Release found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"401":{"description":"Unauthorized"},"404":{"description":"No release found matching the version specifier"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{release_id}/versions":{"get":{"operationId":"listReleaseVersions","tags":["Release Versions"],"summary":"List release versions","description":"Returns paginated file version data associated with a release. Versions whose path is a server function (an `api/` directory) are restricted to project editors; other callers receive 403.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Release ID."},"required":true,"name":"release_id","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination (version ID)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20,"description":"Maximum number of versions to return. Defaults to 20 and is capped at 100."},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated list of versions for the release","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseVersion"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Release not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{release_id}/source-manifest":{"get":{"operationId":"getReleaseSourceManifest","tags":["Release Source Manifests"],"summary":"Export exact release source","description":"Returns complete source only to callers allowed to read server-function source. Requires an exact release UUID, never a mutable alias. Limits: 10000 files, 64 MiB UTF-8 total, 8 MiB per file, 1024 UTF-8 bytes and 64 components per path, 10000 distinct directories and 96 MiB encoded JSON. Paths must be NFC relative paths without traversal, reserved characters, trailing dots/spaces, device names or case-insensitive file/directory collisions. Source identity excludes mutable metadata; it is not execution authority or a compiled artifact.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"release_id","in":"path"}],"responses":{"200":{"description":"Complete bounded release source manifest","content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"},"manifest_version":{"type":"number","enum":[1]},"manifest_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"file_count":{"type":"integer","minimum":0,"maximum":10000},"total_bytes":{"type":"integer","minimum":0,"maximum":67108864},"files":{"type":"array","items":{"type":"object","properties":{"version_id":{"type":"string","format":"uuid"},"path":{"type":"string","minLength":1,"maxLength":1024},"entity_type":{"type":"string","enum":["page","component","function","virtual_file"]},"content_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"byte_size":{"type":"integer","minimum":0,"maximum":8388608},"content":{"type":"string"}},"required":["version_id","path","entity_type","content_hash","byte_size","content"],"additionalProperties":false},"maxItems":10000}},"required":["project_id","release_id","manifest_version","manifest_hash","file_count","total_bytes","files"],"additionalProperties":false}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases/{version}/asset-manifest":{"get":{"operationId":"getReleaseAssetManifest","tags":["Release Asset Manifests"],"summary":"Get release asset manifest","description":"Return the manifest state, version, and (when ready) the manifest body.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version specifier (for example, \"1.2.3\").","example":"1.2.3"},"required":true,"name":"version","in":"path"}],"responses":{"200":{"description":"Manifest summary and body when ready","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["queued","building","partial","ready","failed","superseded"]},"manifest_version":{"type":"integer"},"manifest":{"type":["object","null"],"additionalProperties":{}}},"required":["state","manifest_version","manifest"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project, release, or manifest not found"},"500":{"description":"Server error"}}},"put":{"operationId":"putReleaseAssetManifest","tags":["Release Asset Manifests"],"summary":"Put release asset manifest","description":"Validate and stores the full manifest body, transitioning the manifest to ready.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version specifier (for example, \"1.2.3\").","example":"1.2.3"},"required":true,"name":"version","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[2]},"projectId":{"type":"string","format":"uuid"},"releaseId":{"type":"string","format":"uuid"},"releaseVersion":{"type":"integer"},"manifestVersion":{"type":"integer"},"builderVersion":{"type":"string"},"sourceContentHash":{"type":"string"},"createdAt":{"type":"string"},"assetBasePath":{"type":"string"},"modules":{"type":"object","additionalProperties":{"type":"object","properties":{"contentHash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"size":{"type":"integer","minimum":0},"contentType":{"type":"string"}},"required":["contentHash","size","contentType"]}},"css":{"type":"array","items":{"type":"object","properties":{"contentHash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"size":{"type":"integer","minimum":0},"contentType":{"type":"string"},"styleProfileHash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"cssPipelineIdentity":{"type":"string","minLength":1,"maxLength":2048}},"required":["contentHash","size","contentType","styleProfileHash","cssPipelineIdentity"]}},"routes":{"type":"object","additionalProperties":{"type":"object","properties":{"modules":{"type":"array","items":{"type":"string"}},"css":{"type":"array","items":{"type":"string"}}},"required":["modules","css"]}},"dependencyMode":{"type":"string","enum":["source","immutable"]},"dependencies":{"type":"object","additionalProperties":{"type":"object","properties":{"contentHash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"size":{"type":"integer","minimum":0},"contentType":{"type":"string"}},"required":["contentHash","size","contentType"]}}},"required":["schemaVersion","projectId","releaseId","releaseVersion","manifestVersion","builderVersion","sourceContentHash","createdAt","assetBasePath","modules","css","routes","dependencyMode","dependencies"]}}}},"responses":{"200":{"description":"Manifest stored and marked ready","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"manifest_version":{"type":"integer"},"state":{"type":"string","enum":["queued","building","partial","ready","failed","superseded"]}},"required":["id","manifest_version","state"]}}}},"400":{"description":"Invalid manifest body"},"401":{"description":"Unauthorized"},"404":{"description":"Project or release not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{version}/asset-manifest/assets":{"post":{"operationId":"uploadReleaseAsset","tags":["Release Asset Manifests"],"summary":"Upload release asset","description":"Uploads one transformed asset (raw bytes). The API re-hashes and verifies the content hash.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version specifier (for example, \"1.2.3\").","example":"1.2.3"},"required":true,"name":"version","in":"path"}],"responses":{"200":{"description":"Asset stored","content":{"application/json":{"schema":{"type":"object","properties":{"stored":{"type":"boolean","enum":[true]},"existed":{"type":"boolean"}},"required":["stored","existed"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Payload too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/releases/{version}/asset-manifest/builds":{"post":{"operationId":"beginReleaseAssetManifestBuild","tags":["Release Asset Manifests"],"summary":"Begin release asset manifest build","description":"Begins (or idempotently re-claims) a release asset manifest build.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version specifier (for example, \"1.2.3\").","example":"1.2.3"},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Set to true to enqueue the release asset build task. Runtime executors leave this unset.","example":"true"},"required":false,"name":"queue_task","in":"query"}],"responses":{"200":{"description":"Build begun or re-claimed","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"manifest_version":{"type":"integer"},"state":{"type":"string","enum":["queued","building","partial","ready","failed","superseded"]}},"required":["id","manifest_version","state"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project or release not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{version}/asset-manifest/state":{"post":{"operationId":"reportReleaseAssetManifestState","tags":["Release Asset Manifests"],"summary":"Report release asset manifest state","description":"Reports partial progress or failure for a release asset manifest build.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version specifier (for example, \"1.2.3\").","example":"1.2.3"},"required":true,"name":"version","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["partial","failed"]},"error":{"type":"string"}},"required":["state"]}}}},"responses":{"200":{"description":"State updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"manifest_version":{"type":"integer"},"state":{"type":"string","enum":["queued","building","partial","ready","failed","superseded"]}},"required":["id","manifest_version","state"]}}}},"400":{"description":"Invalid state transition"},"401":{"description":"Unauthorized"},"404":{"description":"Project or release not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environments":{"get":{"operationId":"listEnvironments","tags":["Environments"],"summary":"List environments","description":"List environments with domains, masked variables, and latest deployments.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Cursor for pagination (environment ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["name","updated_at"],"default":"name","description":"Sort field. Defaults to \"name\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order. Defaults to \"asc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of environments for the project","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Environment"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"operationId":"createEnvironment","tags":["Environments"],"summary":"Create environment","description":"Create a new private environment in the project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"]}}}},"responses":{"201":{"description":"Environment created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Environment"}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environments/{environment_id}":{"get":{"operationId":"getEnvironment","tags":["Environments"],"summary":"Get environment","description":"Return a specific environment by its ID.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"environment_id","in":"path"}],"responses":{"200":{"description":"Environment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Environment"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Environment or project not found"},"500":{"description":"Server error"}}},"patch":{"operationId":"updateEnvironment","tags":["Environments"],"summary":"Update environment","description":"Updates environment fields and optionally upserts variables atomically. Requires project.environments.manage; variable writes also require project.env_vars.write. Each variable targets the environment in the path. Existing keys retain IDs, omitted keys remain unchanged, and returned values are masked.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"environment_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"variables":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$","description":"Provide the key."},"value":{"type":"string","description":"Provide the value."}},"required":["key","value"]},"description":"Atomic variable upserts in this environment. Existing keys retain IDs; omitted keys remain unchanged. Requires project.env_vars.write."},"name":{"type":"string"},"protected":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Environment updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Environment"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Environment or project not found"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteEnvironment","tags":["Environments"],"summary":"Delete environment","description":"Delete an environment from the project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"environment_id","in":"path"}],"responses":{"204":{"description":"Environment deleted successfully"},"401":{"description":"Unauthorized"},"404":{"description":"Environment or project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/deployments":{"get":{"operationId":"listDeployments","tags":["Project deployments"],"summary":"List deployments","description":"List deployments for a project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"environment_id","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (deployment ID)"},"required":false,"name":"cursor","in":"query"},{"$ref":"#/components/parameters/PaginationLimit"},{"schema":{"type":"string","enum":["created_at"],"default":"created_at","description":"Sort field. Defaults to \"created_at\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of deployments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"},"environment_id":{"type":"string","format":"uuid"},"user_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","release_id","environment_id"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - User does not have access to this project"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"operationId":"createDeployment","tags":["Project deployments"],"summary":"Create deployment","description":"Create a deployment for a release and environment.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"release_id":{"type":"string","format":"uuid","description":"UUID of the release to deploy"},"environment_id":{"type":"string","format":"uuid","description":"UUID of the target environment"}},"required":["release_id","environment_id"]},"example":{"release_id":"550e8400-e29b-41d4-a716-446655440000","environment_id":"660e8400-e29b-41d4-a716-446655440000"}}}},"responses":{"201":{"description":"Deployment created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"},"environment_id":{"type":"string","format":"uuid"},"user_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","release_id","environment_id"]}}}},"400":{"description":"Invalid input - Release and environment must belong to the same project"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - User does not have permission to create deployments in this project"},"404":{"description":"Release or environment not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/deployments/{deployment_id}":{"get":{"operationId":"getDeployment","tags":["Project deployments"],"summary":"Get deployment","description":"Return a deployment by ID.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"deployment_id","in":"path"}],"responses":{"200":{"description":"Deployment found","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"},"environment_id":{"type":"string","format":"uuid"},"user_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","release_id","environment_id"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - User does not have access to this deployment"},"404":{"description":"Deployment not found"},"500":{"description":"Server error"}}},"patch":{"operationId":"updateDeployment","tags":["Project deployments"],"summary":"Update deployment","description":"Return the deployment unchanged if the body is empty or repeats the stored values.\n\nA deployment’s release, environment, and project cannot change after creation. Requests to change them return a `state-conflict` error without writing changes. To serve a different release, create a new deployment.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"deployment_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"release_id":{"type":"string","format":"uuid","description":"Must equal the stored release ID; a different value is refused with a state conflict"},"environment_id":{"type":"string","format":"uuid","description":"Must equal the stored environment ID; a different value is refused with a state conflict"}}}}}},"responses":{"200":{"description":"Deployment returned unchanged","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"release_id":{"type":"string","format":"uuid"},"environment_id":{"type":"string","format":"uuid"},"user_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","release_id","environment_id"]}}}},"400":{"description":"Invalid input - release_id and environment_id must be UUIDs"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Deployment not found"},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteDeployment","tags":["Project deployments"],"summary":"Delete deployment","description":"Delete a deployment.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"deployment_id","in":"path"}],"responses":{"204":{"description":"Deployment deleted successfully"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Deployment not found"},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error"}}}},"/projects/{project_reference}/domains":{"get":{"operationId":"listProjectDomains","tags":["Project Domains"],"summary":"List project domains","description":"Returns all custom domains across all environments for a project. Includes environment information for each domain.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Cursor for pagination (domain ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["name","updated_at"],"default":"name","description":"Sort field. Defaults to \"name\" (the domain name). \"updated_at\" uses the domain update timestamp. Equal values use the domain ID as a tie breaker."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order. Defaults to \"asc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of all domains for the project","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"environment_id":{"type":"string","format":"uuid"},"environment_name":{"type":"string"}},"required":["id","domain","environment_id","environment_name"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environments/{environment_id}/domains":{"get":{"operationId":"listDomains","tags":["Environment Domains"],"summary":"List domains","description":"Return all custom domains configured for the specified environment.","parameters":[{"schema":{"type":"string","description":"UUID of the project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the environment"},"required":true,"name":"environment_id","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination (domain ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["name","updated_at"],"default":"name","description":"Sort field. Defaults to \"name\". The \"name\" field sorts by domain."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order. Defaults to \"asc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of domains","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"environment_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","domain"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Environment not found"},"500":{"description":"Server error"}}},"post":{"operationId":"createDomain","tags":["Environment Domains"],"summary":"Create domain","description":"Adds a custom domain to the specified environment. Requires `custom_domains` feature to be enabled for the project.","parameters":[{"schema":{"type":"string","description":"UUID of the project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the environment"},"required":true,"name":"environment_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"description":"Custom domain name to add to the environment"}},"required":["domain"]},"example":{"domain":"app.example.com"}}}},"responses":{"201":{"description":"Domain added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"protected":{"type":"boolean"},"domains":{"type":"array","items":{"type":"string"}},"environment_variables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"value":{"type":"string","enum":["********"]},"has_value":{"type":"boolean"}},"required":["id","key","value","has_value"]}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","protected","domains","environment_variables"]}}}},"400":{"description":"Invalid input - Domain format is invalid"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - User does not have permission to add domains or custom_domains feature not enabled"},"404":{"description":"Environment not found"},"429":{"description":"Resource limit exceeded - Custom domain quota reached"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environments/{environment_id}/domains/{domain_reference}":{"get":{"operationId":"getDomain","tags":["Environment Domains"],"summary":"Get domain","description":"Return a specific custom domain by its ID or domain name.","parameters":[{"schema":{"type":"string","description":"Project ID (UUID) or slug"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the environment"},"required":true,"name":"environment_id","in":"path"},{"schema":{"type":"string","description":"Domain ID (UUID) or domain name (for example, app.example.com)."},"required":true,"name":"domain_reference","in":"path"}],"responses":{"200":{"description":"Domain details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"environment_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","domain"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Domain not found"},"500":{"description":"Server error"}}},"patch":{"operationId":"updateDomain","tags":["Environment Domains"],"summary":"Update domain","description":"Update a custom domain name.","parameters":[{"schema":{"type":"string","description":"Project ID (UUID) or slug"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the environment"},"required":true,"name":"environment_id","in":"path"},{"schema":{"type":"string","description":"Domain ID (UUID) or domain name (for example, app.example.com)."},"required":true,"name":"domain_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"description":"New domain name"}},"required":["domain"]}}}},"responses":{"200":{"description":"Domain updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"environment_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","domain"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Domain not found"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteDomain","tags":["Environment Domains"],"summary":"Delete domain","description":"Remove a custom domain from the specified environment.","parameters":[{"schema":{"type":"string","description":"Project ID (UUID) or slug"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"UUID of the environment"},"required":true,"name":"environment_id","in":"path"},{"schema":{"type":"string","description":"Domain ID (UUID) or domain name (for example, app.example.com)."},"required":true,"name":"domain_reference","in":"path"}],"responses":{"204":{"description":"Domain deleted successfully"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - User does not have permission to delete domains"},"404":{"description":"Environment or domain not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environment-variable-keys":{"get":{"operationId":"listEnvironmentVariableKeys","tags":["Environment Variable Keys"],"summary":"List environment variable keys","description":"List environment variable keys without returning secret values.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Environment ID containing the variable."},"required":true,"name":"environment_id","in":"query"},{"schema":{"type":"string","description":"Optional comma-separated keys to check for existence."},"required":false,"name":"keys","in":"query"}],"responses":{"200":{"description":"Environment variable keys and optional missing-key checks","content":{"application/json":{"schema":{"type":"object","properties":{"environment_id":{"type":"string"},"environment_name":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"}},"required":["id","key"]}},"missing":{"type":"array","items":{"type":"string"}}},"required":["environment_id","environment_name","data","missing"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Environment not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environment-variables":{"get":{"operationId":"listEnvironmentVariables","tags":["Environment variables"],"summary":"List environment variables","description":"List environment variables for a specific environment in the resolved project.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Environment ID containing the variable."},"required":true,"name":"environment_id","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (environment variable ID)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of environment variables to return. Defaults to 20 and is capped at 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["key","updated_at"],"default":"key","description":"Sort field. Defaults to \"key\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order. Defaults to \"asc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of environment variables","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"value":{"type":"string","enum":["********"]},"has_value":{"type":"boolean"}},"required":["id","key","value","has_value"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Environment not found"},"500":{"description":"Server error"}}},"post":{"operationId":"createEnvironmentVariable","tags":["Environment variables"],"summary":"Create environment variable","description":"Create an environment variable for a specific environment in the resolved project.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Environment ID containing the variable."},"required":true,"name":"environment_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$","description":"Environment variable key. Must start with a letter or underscore and contain only letters, numbers, and underscores."},"value":{"type":"string","description":"Environment variable value."}},"required":["key","value"]},"example":{"key":"DATABASE_URL","value":"postgresql://localhost:5432/mydb"}}}},"responses":{"201":{"description":"Environment variable created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"value":{"type":"string","enum":["********"]},"has_value":{"type":"boolean"}},"required":["id","key","value","has_value"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project or environment not found"},"409":{"description":"Environment variable with this key already exists"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environment-variables/{key}":{"get":{"operationId":"getEnvironmentVariable","tags":["Environment variables"],"summary":"Get environment variable","description":"Return one environment variable by key for a specific environment in the resolved project.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Environment variable key."},"required":true,"name":"key","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Environment ID containing the variable."},"required":true,"name":"environment_id","in":"query"}],"responses":{"200":{"description":"Environment variable","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"value":{"type":"string","enum":["********"]},"has_value":{"type":"boolean"}},"required":["id","key","value","has_value"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Environment variable not found"},"500":{"description":"Server error"}}},"patch":{"operationId":"updateEnvironmentVariable","tags":["Environment variables"],"summary":"Update environment variable","description":"Update an environment variable by key for a specific environment in the resolved project.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Environment variable key."},"required":true,"name":"key","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Environment ID containing the variable."},"required":true,"name":"environment_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$","description":"Environment variable key. Must start with a letter or underscore and contain only letters, numbers, and underscores."},"value":{"type":"string","description":"Replacement environment variable value."}}},"example":{"value":"postgresql://localhost:5432/newdb"}}}},"responses":{"200":{"description":"Environment variable updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"value":{"type":"string","enum":["********"]},"has_value":{"type":"boolean"}},"required":["id","key","value","has_value"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Environment variable not found"},"409":{"description":"Environment variable with new key already exists"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteEnvironmentVariable","tags":["Environment variables"],"summary":"Delete environment variable","description":"Delete an environment variable by key for a specific environment in the resolved project.","parameters":[{"schema":{"type":"string","description":"Project slug, ID, or other supported project reference."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Environment variable key."},"required":true,"name":"key","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Environment ID containing the variable."},"required":true,"name":"environment_id","in":"query"}],"responses":{"204":{"description":"Environment variable deleted"},"401":{"description":"Unauthorized"},"404":{"description":"Environment variable not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/servers":{"get":{"operationId":"listProjectServers","tags":["Project servers"],"summary":"List project servers","description":"List servers for a project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Server ID from this project’s preceding page. Unknown cursors are rejected."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["name","status","created_at"],"default":"created_at","description":"Sort field. Defaults to \"created_at\". The \"name\" field sorts by hostname."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of servers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Server"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Invalid pagination or sorting options, or a cursor outside this project’s current server list.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/servers/{server_id}":{"get":{"operationId":"getServer","tags":["Project servers"],"summary":"Get project server","description":"Return a project server by ID.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"server_id","in":"path"}],"responses":{"200":{"description":"Server details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteServer","tags":["Project servers"],"summary":"Delete project server","description":"Marks a project server for deletion.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"server_id","in":"path"}],"responses":{"200":{"description":"Server marked for deletion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/environments/{environment_id}/servers":{"post":{"operationId":"createServer","tags":["Environment Servers"],"summary":"Create project server","description":"Create a server for an environment.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"environment_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"Server created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Payment required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/servers":{"get":{"operationId":"listUserServers","tags":["Account servers"],"summary":"List my servers","description":"List account servers for the authenticated user.","parameters":[{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Items per page"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["name","status","created_at"],"default":"created_at","description":"Sort field. Defaults to \"created_at\". The \"name\" field sorts by hostname."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of servers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Server"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"}},"x-audience":"company-internal"},"post":{"operationId":"createRootServer","tags":["Account servers"],"summary":"Create server","description":"Create a server linked to an environment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"environment_id":{"type":"string","format":"uuid","description":"Environment UUID to link the server to"}},"required":["environment_id"]}}}},"responses":{"201":{"description":"Server created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Environment not found"}},"x-audience":"company-internal"}},"/servers/{server_id}":{"get":{"operationId":"getRootServer","tags":["Account servers"],"summary":"Get my server","description":"Return a server owned by the current user.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"server_id","in":"path"}],"responses":{"200":{"description":"Server details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Server not found"}},"x-audience":"company-internal"},"delete":{"operationId":"deleteRootServer","tags":["Account servers"],"summary":"Delete my server","description":"Marks a server owned by the current user for deletion.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"server_id","in":"path"}],"responses":{"200":{"description":"Server marked for deletion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Server not found"}},"x-audience":"company-internal"}},"/servers/{server_id}/environments/{environment_id}":{"post":{"operationId":"addServerEnvironment","tags":["Server Environments"],"summary":"Link environment to server","description":"Links an environment to a server.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"server_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"environment_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Environment linked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Server or environment not found"}},"x-audience":"company-internal"},"delete":{"operationId":"removeServerEnvironment","tags":["Server Environments"],"summary":"Unlink environment from server","description":"Unlinks an environment from a server.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"server_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"environment_id","in":"path"}],"responses":{"200":{"description":"Environment unlinked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Server not found"}},"x-audience":"company-internal"}},"/projects/-/proxy-access/{lookup_key}":{"get":{"operationId":"getProjectProxyAccess","tags":["Proxy metadata"],"summary":"Get proxy access metadata","description":"Return fresh protection and membership metadata for proxy authorization checks.","parameters":[{"schema":{"type":"string","minLength":1,"example":"my-project"},"required":true,"name":"lookup_key","in":"path"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_users","in":"query"}],"responses":{"200":{"description":"Project proxy access metadata","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"environments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domains":{"type":"array","items":{"type":"string"}},"protected":{"type":"boolean"}},"required":["id","name","domains","protected"]}},"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}},"required":["id","slug","environments"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/-/proxy-routing/{lookup_key}":{"get":{"operationId":"getProjectProxyRouting","tags":["Proxy metadata"],"summary":"Get proxy routing metadata","description":"Returns cacheable project routing metadata for proxy requests. The response excludes protection state and users.","parameters":[{"schema":{"type":"string","minLength":1,"example":"my-project"},"required":true,"name":"lookup_key","in":"path"}],"responses":{"200":{"description":"Project proxy routing metadata","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"environments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domains":{"type":"array","items":{"type":"string"}},"active_release_id":{"type":["string","null"]}},"required":["id","name","domains","active_release_id"]}}},"required":["id","slug","name","environments"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/sandbox-sessions":{"get":{"operationId":"listSandboxSessions","tags":["Sandbox Sessions"],"summary":"List sandbox sessions","description":"List sandbox execution sessions billable to the given project.","parameters":[{"schema":{"type":"string","description":"Project UUID or slug whose billed sandbox sessions are listed."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination. Uses the sandbox session ID."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum sandbox sessions to return."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["created_at","status"],"default":"created_at","description":"Sort field. Defaults to \"created_at\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of sandbox sessions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SandboxSession"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Validation failed."},"401":{"description":"Unauthorized."}}},"post":{"operationId":"createSandboxSession","tags":["Sandbox Sessions"],"summary":"Create sandbox session","description":"Creates a sandbox session or assigns an available prewarmed session. Provide `project_reference` or `environment_id` to identify the project to bill.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"project_reference":{"type":"string","description":"Optional project UUID or slug. When set, the project owner is billed."},"projectId":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"environment_id":{"type":"string","format":"uuid","description":"Optional environment ID. When set, its variables are copied once into the sandbox session."},"ttl_mode":{"type":"string","enum":["default","duration","always_on"],"description":"Sandbox lifetime policy. `default` uses the platform’s idle and maximum lifetime limits."},"ttl_hours":{"type":"integer","exclusiveMinimum":0,"maximum":24,"description":"Required when ttl_mode is duration. Number of hours before cleanup, up to 24."}}}}}},"responses":{"201":{"description":"Sandbox session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxSession"}}}},"401":{"description":"Unauthorized."},"402":{"description":"Insufficient credits."}}}},"/sandbox-sessions/{session_id}":{"get":{"operationId":"getSandboxSession","tags":["Sandbox Sessions"],"summary":"Get sandbox session","description":"Return status, endpoint, and billing project information for a sandbox session.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"responses":{"200":{"description":"Sandbox session details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxSession"}}}},"404":{"description":"Session not found."}}},"patch":{"operationId":"updateSandboxSessionLifetime","tags":["Sandbox Sessions"],"summary":"Update sandbox session lifetime","description":"Update the lifetime policy for a sandbox session.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ttl_mode":{"type":"string","enum":["default","duration","always_on"],"description":"Sandbox lifetime policy. `default` uses the platform’s idle and maximum lifetime limits."},"ttl_hours":{"type":"integer","exclusiveMinimum":0,"maximum":24,"description":"Required when ttl_mode is duration. Number of hours before cleanup, up to 24."}},"required":["ttl_mode"]}}}},"responses":{"200":{"description":"Sandbox session updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxSession"}}}},"404":{"description":"Session not found."}}},"delete":{"operationId":"deleteSandboxSession","tags":["Sandbox Sessions"],"summary":"Delete sandbox session","description":"Mark a sandbox session for deletion.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"responses":{"200":{"description":"Session marked for deletion.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["deleting"]}},"required":["id","status"]}}}},"404":{"description":"Session not found."}}}},"/sandbox-sessions/{session_id}/environment":{"get":{"operationId":"getSandboxSessionEnvironment","tags":["Sandbox Sessions"],"summary":"Get sandbox environment snapshot","description":"Return the environment variable snapshot copied into this sandbox session.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"responses":{"200":{"description":"Environment snapshot.","content":{"application/json":{"schema":{"type":"object","properties":{"env":{"type":"object","additionalProperties":{"type":"string"}}},"required":["env"]}}}},"404":{"description":"Session not found."}}}},"/sandbox-sessions/{session_id}/commands":{"get":{"operationId":"listSandboxSessionBackgroundCommands","tags":["Sandbox Commands"],"summary":"List sandbox background commands","description":"List background commands for a sandbox session through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"responses":{"200":{"description":"Background commands.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}},"post":{"operationId":"startSandboxSessionBackgroundCommand","tags":["Sandbox Commands"],"summary":"Start sandbox background command","description":"Start a background command in a sandbox session through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"command":{"type":"string","minLength":1},"cwd":{"type":"string"},"timeout_seconds":{"type":"number"},"env":{"type":"object","additionalProperties":{"type":"string"}}},"required":["command"]}}}},"responses":{"200":{"description":"Background command.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/commands/{command_id}":{"get":{"operationId":"getSandboxSessionBackgroundCommand","tags":["Sandbox Commands"],"summary":"Get sandbox background command","description":"Return background command status for a sandbox session through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Sandbox background command ID."},"required":true,"name":"command_id","in":"path"}],"responses":{"200":{"description":"Background command.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/commands/{command_id}/output":{"get":{"operationId":"getSandboxSessionBackgroundCommandOutput","tags":["Sandbox Commands"],"summary":"Get sandbox background command output","description":"Return background command output for a sandbox session through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Sandbox background command ID."},"required":true,"name":"command_id","in":"path"}],"responses":{"200":{"description":"Background command output.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/commands/{command_id}/cancel":{"post":{"operationId":"cancelSandboxSessionBackgroundCommand","tags":["Sandbox Commands"],"summary":"Cancel sandbox background command","description":"Cancel a background command in a sandbox session through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Sandbox background command ID."},"required":true,"name":"command_id","in":"path"}],"responses":{"200":{"description":"Background command.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/commands/run":{"post":{"operationId":"runSandboxSessionCommand","tags":["Sandbox Commands"],"summary":"Run sandbox command","description":"Run a short-lived command in a sandbox session through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"command":{"type":"string","minLength":1},"cwd":{"type":"string"},"timeout_seconds":{"type":"number"},"env":{"type":"object","additionalProperties":{"type":"string"}}},"required":["command"]}}}},"responses":{"200":{"description":"Command result.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/commands/stream":{"post":{"operationId":"streamSandboxSessionCommand","tags":["Sandbox Commands"],"summary":"Stream sandbox command","description":"Run a command in a sandbox session and preserves the upstream NDJSON stream through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"command":{"type":"string","minLength":1},"cwd":{"type":"string"},"timeout_seconds":{"type":"number"},"env":{"type":"object","additionalProperties":{"type":"string"}}},"required":["command"]}}}},"responses":{"200":{"description":"Command stream.","content":{"application/x-ndjson":{"schema":{"type":"string"}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/files":{"get":{"operationId":"listSandboxSessionFiles","tags":["Sandbox Files"],"summary":"List sandbox files","description":"List files in a sandbox session directory through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"path","in":"query"}],"responses":{"200":{"description":"Directory listing.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}},"post":{"operationId":"writeSandboxSessionFiles","tags":["Sandbox Files"],"summary":"Write sandbox files","description":"Write one or more files into a sandbox session through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1},"content":{"type":"string"}},"required":["path","content"]}}},"required":["files"]}}}},"responses":{"200":{"description":"Write result.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/file":{"get":{"operationId":"readSandboxSessionFile","tags":["Sandbox Files"],"summary":"Read sandbox file","description":"Return a file from a sandbox session through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"path","in":"query"}],"responses":{"200":{"description":"File content.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/terminal":{"get":{"operationId":"openSandboxSessionTerminal","tags":["Sandbox Terminal"],"summary":"Open sandbox terminal","description":"Returns the authenticated terminal page. The browser opens a WebSocket connection on the same path, and the API forwards the connection to the sandbox runtime.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"responses":{"200":{"description":"Terminal shell page.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/healthz":{"get":{"operationId":"checkSandboxSessionHealth","tags":["Sandbox Health"],"summary":"Check sandbox health","description":"Return sandbox health through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"responses":{"200":{"description":"Health probe.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/readyz":{"get":{"operationId":"checkSandboxSessionReadiness","tags":["Sandbox Health"],"summary":"Check sandbox readiness","description":"Return sandbox readiness through the authenticated API.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"responses":{"200":{"description":"Readiness probe.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"404":{"description":"Session not found."},"502":{"description":"Sandbox data plane request failed."}}}},"/sandbox-sessions/{session_id}/heartbeat":{"post":{"operationId":"sandboxSessionHeartbeat","tags":["Sandbox Health"],"summary":"Update sandbox activity","description":"Update the session’s last-activity timestamp to prevent an idle timeout.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Sandbox session UUID."},"required":true,"name":"session_id","in":"path"}],"responses":{"200":{"description":"Heartbeat acknowledged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"404":{"description":"Session not found."}}}},"/projects/{project_reference}/cache/get":{"get":{"operationId":"cacheGet","tags":["Project Cache"],"summary":"Get cache entry","description":"Retrieves a value from the project-scoped cache. Requires project.cache.read.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.\\-/]+$","description":"Cache key."},"required":true,"name":"key","in":"query"}],"responses":{"200":{"description":"Cache value or null when not found.","content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":["string","null"]}},"required":["value"]}}}},"400":{"description":"Invalid cache key."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/cache/get-batch":{"post":{"operationId":"cacheGetBatch","tags":["Project Cache"],"summary":"Get multiple cache entries","description":"Get multiple values from the project-scoped cache in a single request.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.\\-/]+$"},"minItems":1,"maxItems":100,"description":"Cache keys to fetch in a single request. Maximum 100."}},"required":["keys"]}}}},"responses":{"200":{"description":"Cache values keyed by cache key.","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"type":["string","null"]}},"hits":{"type":"number"},"misses":{"type":"number"}},"required":["values","hits","misses"]}}}},"400":{"description":"Invalid cache keys."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/cache/keys":{"get":{"operationId":"cacheKeys","tags":["Project Cache"],"summary":"List cache keys","description":"Lists cache keys for a project in Redis scan order with optional pattern filtering and pagination. Concurrent cache changes can cause duplicates or omissions. Requires project.cache.read.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.*\\-/]+$","description":"Optional key pattern filter such as \"transform:*\"."},"required":false,"description":"Cache pattern, 1 to 512 characters; * matches any sequence of characters.","name":"pattern","in":"query"},{"schema":{"type":"string","description":"Opaque continuation from a previous response. Reuse with the same project and pattern within five minutes; expired cursors require a new listing."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Maximum keys to return (default 100, min 1, max 1000)."},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of cache keys.","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"Matching key names without the project cache prefix, in Redis scan order."},"count":{"type":"number","description":"Number of keys returned in this response."},"cursor":{"type":["string","null"],"description":"Continuation bound to this project and pattern; expires five minutes after creation. Null after all scan results and buffered keys are consumed."},"has_more":{"type":"boolean","description":"Whether buffered keys or an unfinished Redis scan remain. A continuation can return no matching keys."}},"required":["keys","count","cursor","has_more"]}}}},"400":{"description":"Invalid pattern or limit, or an invalid or expired cursor."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/cache/stats":{"get":{"operationId":"cacheStats","tags":["Project Cache"],"summary":"Get cache stats","description":"Requires project.cache.read. Returns statistics from collected project-cache keys: counts by prefix and the first 10 sample keys. Scanning stops after a batch reaches 10000 collected keys or the scan completes; the final batch can exceed that threshold. total_keys is the collected count rather than an exact whole-cache total.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"responses":{"200":{"description":"Cache statistics.","content":{"application/json":{"schema":{"type":"object","properties":{"total_keys":{"type":"number"},"keys_by_prefix":{"type":"object","additionalProperties":{"type":"number"}},"sample_keys":{"type":"array","items":{"type":"string"}}},"required":["total_keys","keys_by_prefix","sample_keys"]}}}},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/cache/set":{"post":{"operationId":"cacheSet","tags":["Project Cache"],"summary":"Set cache entry","description":"Stores a value in the project-scoped cache with optional TTL.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.\\-/]+$","description":"Cache key."},"value":{"type":"string","description":"String value to cache."},"ttl":{"type":"number","minimum":0,"maximum":86400,"description":"TTL in seconds. 0 disables expiry. Defaults to 300. Max 86400."}},"required":["key","value"]}}}},"responses":{"200":{"description":"Cache set successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid cache key or TTL."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/cache/set-batch":{"post":{"operationId":"cacheSetBatch","tags":["Project Cache"],"summary":"Set multiple cache entries","description":"Stores multiple values in the project-scoped cache in a single request.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.\\-/]+$","description":"Cache key."},"value":{"type":"string","description":"String value to cache."},"ttl":{"type":"number","minimum":0,"maximum":86400,"description":"TTL in seconds. 0 disables expiry. Defaults to 300. Max 86400."}},"required":["key","value"]},"minItems":1,"maxItems":100,"description":"Cache entries to store in a single request. Maximum 100."}},"required":["entries"]}}}},"responses":{"200":{"description":"Cache entries set successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"number"}},"required":["success","count"]}}}},"400":{"description":"Invalid cache entries."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/cache/del":{"post":{"operationId":"cacheDel","tags":["Project Cache"],"summary":"Delete cache entry","description":"Remove a value from the project-scoped cache.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.\\-/]+$","description":"Cache key to delete."}},"required":["key"]}}}},"responses":{"200":{"description":"Cache key deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid cache key."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/cache/del-pattern":{"post":{"operationId":"cacheDelPattern","tags":["Project Cache"],"summary":"Delete cache by pattern","description":"Remove all values matching a pattern from the project-scoped cache.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pattern":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.*\\-/]+$","description":"Pattern to delete, such as \"transform:*\"."}},"required":["pattern"]}}}},"responses":{"200":{"description":"Number of keys deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer","minimum":0,"description":"Number of keys actually deleted by Redis."}},"required":["deleted"]}}}},"400":{"description":"Invalid pattern."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/cache/clear":{"post":{"operationId":"cacheClear","tags":["Project Cache"],"summary":"Clear cache","description":"Delete all cached values for a project.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"responses":{"200":{"description":"Number of keys deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer","minimum":0,"description":"Number of keys actually deleted by Redis."}},"required":["deleted"]}}}},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/cache/get":{"get":{"operationId":"userCacheGet","tags":["User Cache"],"summary":"Get user cache entry","description":"Get a user-scoped cache value for the authenticated caller.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.\\-/]+$","description":"User-scoped cache key to read."},"required":true,"name":"key","in":"query"}],"responses":{"200":{"description":"User-scoped cache value or null when the key is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":["string","null"]}},"required":["value"]}}}},"400":{"description":"Invalid cache key."},"401":{"description":"Unauthorized."},"500":{"description":"Server error."}}}},"/cache/set":{"post":{"operationId":"userCacheSet","tags":["User Cache"],"summary":"Set user cache entry","description":"Stores a user-scoped cache value for the authenticated caller.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.\\-/]+$","description":"User-scoped cache key to write."},"value":{"type":"string","description":"String value to cache. JSON should be serialized before sending."},"ttl":{"type":"number","minimum":0,"maximum":86400,"description":"TTL in seconds. Use 0 for no expiry. Defaults to 300. Maximum 86400."}},"required":["key","value"]}}}},"responses":{"200":{"description":"User-scoped cache value stored successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid cache key, value, or TTL."},"401":{"description":"Unauthorized."},"500":{"description":"Server error."}}}},"/cache/del":{"post":{"operationId":"userCacheDel","tags":["User Cache"],"summary":"Delete user cache entry","description":"Delete a user-scoped cache value for the authenticated caller.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.\\-/]+$","description":"User-scoped cache key to delete."}},"required":["key"]}}}},"responses":{"200":{"description":"User-scoped cache value deleted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid cache key."},"401":{"description":"Unauthorized."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/logs":{"get":{"operationId":"getProjectLogs","tags":["Project logs"],"summary":"Query project logs","description":"Query recent logs for a project from the runtime (veryfront-server), the API (veryfront-api) and the proxy (veryfront-proxy). Only lines stamped with the project's id are returned, and API and proxy lines carry only request fields. Each entry carries run_id when the line belongs to a run. Supports filtering by level, service, trace_id, request_id, run_id, and free-text search. Use next_cursor from the response to paginate.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"date-time","description":"Start time (ISO 8601). Defaults to 1 hour ago. Logs are kept for 31 days and one query spans at most 30 days; an older start or a wider range returns 400."},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End time (ISO 8601). Defaults to now."},"required":false,"name":"end","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from a previous response (next_cursor)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":1000,"default":100,"description":"Max entries to return (default: 100, max: 1000)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["forward","backward"],"default":"backward","description":"Sort order (default: backward, with newest first)"},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string","enum":["timestamp"],"description":"Sort field. Defaults to \"timestamp\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort order. Defaults to \"desc\". When provided, overrides the legacy direction parameter."},"required":false,"name":"sort_order","in":"query"},{"schema":{"type":"string","enum":["error","warn","info","debug"],"description":"Filter by log level"},"required":false,"name":"level","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Free-text search over the fields each entry shows"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["veryfront-server","veryfront-api","veryfront-proxy"],"description":"Filter by service: veryfront-server, veryfront-api or veryfront-proxy."},"required":false,"description":"Filter by service: veryfront-server, veryfront-api or veryfront-proxy.","name":"service","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9._-]+$","description":"Filter by exact trace ID to correlate logs with a distributed trace."},"required":false,"description":"Filter by exact trace ID to correlate logs with a distributed trace.","name":"trace_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._-]+$","description":"Filter by exact request ID."},"required":false,"description":"Filter by exact request ID.","name":"request_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._-]+$","description":"Filter by exact run ID to see every service line that belongs to one run."},"required":false,"description":"Filter by exact run ID to see every service line that belongs to one run.","name":"run_id","in":"query"}],"responses":{"200":{"description":"Log query results","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","description":"The timestamp associated with this tool result."},"level":{"type":"string","description":"The level associated with this tool result."},"message":{"type":"string","description":"The message associated with this tool result."},"service":{"type":"string","description":"The service associated with this tool result."},"trace_id":{"type":"string","description":"The trace id associated with this tool result."},"request_id":{"type":"string","description":"The request id associated with this tool result."},"run_id":{"type":"string","description":"Run identifier associated with this result."},"metadata":{"type":"object","additionalProperties":{"type":"string","description":"Additional structured values associated with this result."},"description":"Additional structured metadata returned by the tool."}},"required":["timestamp","level","message","service"],"description":"One entry item associated with this tool result."},"description":"List of entries associated with this tool result."},"next_cursor":{"type":["string","null"],"description":"The next cursor associated with this tool result."},"stats":{"type":"object","properties":{"bytes_processed":{"type":"number","description":"The bytes processed associated with this tool result."},"lines_processed":{"type":"number","description":"The lines processed associated with this tool result."},"query_time_ms":{"type":"number","description":"The query time ms associated with this tool result."}},"required":["bytes_processed","lines_processed","query_time_ms"],"description":"Structured stats details associated with this tool result."}},"required":["entries","next_cursor","stats"]}}}},"400":{"description":"Invalid log query parameters, including a time range beyond retention","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — project.logs.read capability required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Service unavailable — log service not configured or unreachable"}}}},"/projects/{project_reference}/metrics/query":{"post":{"operationId":"queryProjectMetrics","tags":["Project metrics"],"summary":"Query project metrics","description":"Queries recent Prometheus-compatible metrics for a project. Results are project-scoped server-side. Raw PromQL is not accepted.","parameters":[{"schema":{"type":"string","description":"Project slug or UUID. The resolved project is used to scope all metric reads server-side."},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string","minLength":1,"maxLength":200,"description":"Prometheus metric name. Raw PromQL is not accepted."},"start":{"type":"string","description":"Start time (ISO 8601). Defaults to 1 hour ago. Metrics are kept for 395 days and one query spans at most 31 days; an older start or a wider range returns 400."},"end":{"type":"string","description":"End time (ISO 8601). Defaults to now."},"step":{"type":"string","minLength":1,"maxLength":20,"default":"60s","description":"Prometheus query step, for example 60s."},"aggregation":{"type":"string","enum":["none","sum","avg","min","max","count"],"default":"none","description":"Aggregation to apply to the project-scoped metric selector."},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional allowlisted label filters such as environment, service_name or status_code. environment is the project environment on every metric: its name, matched case-insensitively, or preview for a branch. ai_gateway_* metrics carry it for calls made by a project run. Unknown, platform (deployment_environment) and project-scope labels are rejected."}},"required":["metric"]}}}},"responses":{"200":{"description":"Metric query results","content":{"application/json":{"schema":{"type":"object","properties":{"series":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","description":"The metric associated with this tool result."},"labels":{"type":"object","additionalProperties":{"type":"string","description":"Additional structured values associated with this result."},"description":"Structured labels details associated with this tool result."},"points":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","description":"The timestamp associated with this tool result."},"value":{"type":"number","description":"The value associated with this tool result."}},"required":["timestamp","value"],"description":"One point item associated with this tool result."},"description":"List of points associated with this tool result."}},"required":["metric","labels","points"],"description":"One sery item associated with this tool result."},"description":"List of series associated with this tool result."},"stats":{"type":"object","properties":{"query_time_ms":{"type":"number","description":"The query time ms associated with this tool result."}},"required":["query_time_ms"],"description":"Structured stats details associated with this tool result."}},"required":["series","stats"]}}}},"400":{"description":"Invalid metric query parameters, including a time range beyond retention"},"401":{"description":"Unauthorized"},"403":{"description":"Missing project.metrics.read capability","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found"},"429":{"description":"Rate limit exceeded"},"502":{"description":"External metric provider error from the Prometheus-compatible read path"},"503":{"description":"Metric service unavailable or Prometheus-compatible read path is not configured"}}}},"/projects/{project_reference}/traces":{"get":{"operationId":"getProjectTraces","tags":["Project traces"],"summary":"Query project traces","description":"Queries recent Grafana Cloud Tempo traces for a project. Results are project-scoped server-side and returned as compact trace summaries.","parameters":[{"schema":{"type":"string","description":"Project slug or UUID. The resolved project is used to scope all trace reads server-side."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"date-time","description":"Start time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400."},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400."},"required":false,"name":"end","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20,"description":"Max traces to return (default: 20, max: 100)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Optional OpenTelemetry service.name filter, for example veryfront-api, veryfront-studio, or veryfront-server."},"required":false,"name":"service","in":"query"},{"schema":{"type":"string","enum":["ok","error","unset"],"description":"Optional Tempo status filter. Use ok, error, or unset. error matches traces with an error span of the project or without project context anywhere in the trace, as trace detail reports."},"required":false,"name":"status","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"description":"Optional minimum trace duration in milliseconds."},"required":false,"name":"min_duration_ms","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Optional run ID. Returns traces with a span whose run.id, parent.run.id, or agent.run.id is this run, or that contain its runtime control-plane request."},"required":false,"name":"run_id","in":"query"},{"schema":{"type":"string","enum":["timestamp","duration","status","service"],"default":"timestamp","description":"Sort field. Defaults to \"timestamp\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Trace query results","content":{"application/json":{"schema":{"type":"object","properties":{"traces":{"type":"array","items":{"type":"object","properties":{"trace_id":{"type":"string","description":"The trace id associated with this tool result."},"root_span_name":{"type":"string","description":"The root span name associated with this tool result."},"root_service":{"type":"string","description":"The root service associated with this tool result."},"started_at":{"type":"string","description":"The started at associated with this tool result."},"duration_ms":{"type":"number","description":"The duration ms associated with this tool result."},"status":{"type":"string","enum":["ok","error","unset","unknown"],"description":"Lifecycle status for the returned record."},"span_count":{"type":"number","description":"The span count associated with this tool result."},"services":{"type":"array","items":{"type":"string","description":"One service item associated with this tool result."},"description":"List of services associated with this tool result."},"project_id":{"type":"string","description":"Project identifier associated with this result."},"project_slug":{"type":"string","description":"The project slug associated with this tool result."}},"required":["trace_id","root_span_name","root_service","started_at","duration_ms","status","span_count","services","project_id"],"description":"One trace item associated with this tool result."},"description":"List of traces associated with this tool result."},"stats":{"type":"object","properties":{"query_time_ms":{"type":"number","description":"The query time ms associated with this tool result."}},"required":["query_time_ms"],"description":"Structured stats details associated with this tool result."}},"required":["traces","stats"]}}}},"400":{"description":"Invalid trace query parameters, including a time range beyond retention"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — project.logs.read capability required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found"},"429":{"description":"Rate limit exceeded"},"502":{"description":"External trace provider error from Grafana Cloud Tempo."},"503":{"description":"Trace service unavailable or Grafana Cloud Tempo read path is not configured."}}}},"/projects/{project_reference}/traces/{trace_id}":{"get":{"operationId":"getProjectTrace","tags":["Project traces"],"summary":"Get project trace","description":"Returns trace details from Grafana Cloud Tempo, scoped to the project.\n\n`spans` contains at most 200 entries, prioritized as follows: the root span, error spans and their ancestors, then remaining spans.\n\nIf `span_count` exceeds the number returned, use [`GET /projects/{project_reference}/traces/{trace_id}/spans`](https://veryfront.com/docs/cloud/rest/api-reference/project-traces/list-project-trace-spans) to retrieve the remaining spans. Set `status=error` to retrieve all error spans.","parameters":[{"schema":{"type":"string","description":"Project slug or UUID. The resolved project is used to scope all trace reads server-side."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Trace ID from Grafana Cloud Tempo."},"required":true,"name":"trace_id","in":"path"}],"responses":{"200":{"description":"Trace detail","content":{"application/json":{"schema":{"type":"object","properties":{"trace_id":{"type":"string","description":"The trace id associated with this tool result."},"root_span_name":{"type":"string","description":"The root span name associated with this tool result."},"root_service":{"type":"string","description":"The root service associated with this tool result."},"started_at":{"type":"string","description":"The started at associated with this tool result."},"duration_ms":{"type":"number","description":"The duration ms associated with this tool result."},"status":{"type":"string","enum":["ok","error","unset","unknown"],"description":"Lifecycle status for the returned record."},"span_count":{"type":"number","description":"The span count associated with this tool result."},"services":{"type":"array","items":{"type":"string","description":"One service item associated with this tool result."},"description":"List of services associated with this tool result."},"project_id":{"type":"string","description":"Project identifier associated with this result."},"project_slug":{"type":"string","description":"The project slug associated with this tool result."},"root_span_id":{"type":["string","null"],"description":"The root span id associated with this tool result."},"spans":{"type":"array","items":{"type":"object","properties":{"span_id":{"type":"string","description":"The span id associated with this tool result."},"parent_span_id":{"type":["string","null"],"description":"The parent span id associated with this tool result."},"name":{"type":"string","description":"Human-readable name for the returned record."},"service":{"type":"string","description":"The service associated with this tool result."},"started_at":{"type":"string","description":"The started at associated with this tool result."},"ended_at":{"type":["string","null"],"description":"The ended at associated with this tool result."},"duration_ms":{"type":"number","description":"The duration ms associated with this tool result."},"status":{"type":"string","enum":["ok","error","unset","unknown"],"description":"Lifecycle status for the returned record."},"status_message":{"type":["string","null"],"description":"The status message associated with this tool result."},"attributes":{"type":"object","additionalProperties":{"type":"string","description":"Additional structured values associated with this result."},"description":"Structured attributes details associated with this tool result."},"events":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name for the returned record."},"timestamp":{"type":"string","description":"The timestamp associated with this tool result."},"attributes":{"type":"object","additionalProperties":{"type":"string","description":"Additional structured values associated with this result."},"description":"Structured attributes details associated with this tool result."}},"required":["name","timestamp","attributes"],"description":"One event item associated with this tool result."},"description":"List of events associated with this tool result."}},"required":["span_id","parent_span_id","name","service","started_at","ended_at","duration_ms","status","status_message","attributes","events"],"description":"One span item associated with this tool result."},"description":"List of spans associated with this tool result."}},"required":["trace_id","root_span_name","root_service","started_at","duration_ms","status","span_count","services","project_id","root_span_id","spans"]}}}},"400":{"description":"Invalid trace identifier"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — project.logs.read capability required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or trace not found"},"429":{"description":"Rate limit exceeded"},"502":{"description":"External trace provider error from Grafana Cloud Tempo."},"503":{"description":"Trace service unavailable or Grafana Cloud Tempo read path is not configured."}}}},"/projects/{project_reference}/traces/{trace_id}/spans":{"get":{"operationId":"listProjectTraceSpans","tags":["Project traces"],"summary":"List project trace spans","description":"Lists trace spans visible within the project, ordered by start time. Use the pagination cursor to retrieve additional spans. Set `status=error` to retrieve all error spans.","parameters":[{"schema":{"type":"string","description":"Project slug or UUID. The resolved project is used to scope all trace reads server-side."},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Trace ID from Grafana Cloud Tempo."},"required":true,"name":"trace_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque continuation from page_info.next or page_info.prev."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":200,"description":"Max spans to return (default: 200, max: 1000)."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["ok","error","unset","unknown"],"description":"Optional span status filter. Use ok, error, unset, or unknown."},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Order by span start time. Defaults to \"asc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Trace spans","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"span_id":{"type":"string","description":"The span id associated with this tool result."},"parent_span_id":{"type":["string","null"],"description":"The parent span id associated with this tool result."},"name":{"type":"string","description":"Human-readable name for the returned record."},"service":{"type":"string","description":"The service associated with this tool result."},"started_at":{"type":"string","description":"The started at associated with this tool result."},"ended_at":{"type":["string","null"],"description":"The ended at associated with this tool result."},"duration_ms":{"type":"number","description":"The duration ms associated with this tool result."},"status":{"type":"string","enum":["ok","error","unset","unknown"],"description":"Lifecycle status for the returned record."},"status_message":{"type":["string","null"],"description":"The status message associated with this tool result."},"attributes":{"type":"object","additionalProperties":{"type":"string","description":"Additional structured values associated with this result."},"description":"Structured attributes details associated with this tool result."},"events":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name for the returned record."},"timestamp":{"type":"string","description":"The timestamp associated with this tool result."},"attributes":{"type":"object","additionalProperties":{"type":"string","description":"Additional structured values associated with this result."},"description":"Structured attributes details associated with this tool result."}},"required":["name","timestamp","attributes"],"description":"One event item associated with this tool result."},"description":"List of events associated with this tool result."}},"required":["span_id","parent_span_id","name","service","started_at","ended_at","duration_ms","status","status_message","attributes","events"],"description":"One span item associated with this tool result."},"description":"Primary result records returned by the tool."},"page_info":{"type":"object","properties":{"self":{"type":["string","null"],"description":"Cursor that refers to the current page."},"first":{"type":"null","description":"The first associated with this tool result."},"next":{"type":["string","null"],"description":"Cursor for the next page when pagination is available."},"prev":{"type":["string","null"],"description":"Cursor for the previous page when pagination is available."}},"required":["self","first","next","prev"],"description":"Pagination cursor values for traversing the result set."}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/alerts":{"get":{"operationId":"listProjectAlerts","tags":["Project alerts"],"summary":"List project alerts","description":"Lists the alert episodes represented in the last 30 days of retained state history for this project, including episodes already firing when that history begins, firing and resolved, newest first. An alert is one firing of a Veryfront alert rule for this project, such as failing agent or task runs, with the run's error code and links to the project's error logs and traces for the time it covers. Only alerts labelled with this project are returned.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only alerts in one of these statuses (firing, resolved). Comma-separated and/or repeated."},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sort_order","in":"query"},{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"}],"responses":{"200":{"description":"Project alerts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Identifies this firing of the alert."},"rule_id":{"type":"string","description":"UID of the Grafana alert rule, for example project-agent-run-failures."},"title":{"type":"string","description":"Short human-readable title returned by the tool."},"status":{"type":"string","enum":["firing","resolved"],"description":"Lifecycle status for the returned record."},"error_code":{"type":["string","null"],"description":"Terminal error code of the failed runs; null for rules without one."},"run_kind":{"type":["string","null"],"description":"Kind of the runs the alert is about, when the rule tells them apart."},"run_status":{"type":["string","null"],"description":"Status of the unfinished runs the alert is about."},"started_at":{"type":["string","null"],"description":"When the alert fired; null when it fired before the 30 days of retained history."},"resolved_at":{"type":["string","null"],"description":"The resolved at associated with this tool result."},"_links":{"type":"object","properties":{"logs":{"type":"object","properties":{"href":{"type":"string","description":"The href associated with this tool result."}},"required":["href"],"description":"The logs associated with this tool result."},"traces":{"type":"object","properties":{"href":{"type":"string","description":"The href associated with this tool result."}},"required":["href"],"description":"The traces associated with this tool result."}},"description":"Investigation links clipped to retained telemetry; omitted when the episode is outside the available window."}},"required":["id","rule_id","title","status","error_code","run_kind","run_status","started_at","resolved_at","_links"],"description":"One data item associated with this tool result."}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Bad gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/account/analytics/conversations":{"get":{"operationId":"getAccountConversationAnalytics","tags":["Account conversation analytics"],"summary":"Get account conversation analytics","description":"Returns activity for conversations created by the authenticated user or containing them as an active participant. Model counts are independent inference usage records for that user. Supports project and label filters; the tools breakdown is empty.","parameters":[{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Relative timeframe preset."},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA timezone for daily bucket boundaries."},"required":false,"name":"timezone","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Label filters as key or key=value, repeated or comma-separated. Example: ?label=team=platform&label=criticality=high"},"required":false,"name":"label","in":"query"},{"schema":{"type":"string","description":"Optional project UUID or slug to scope analytics to a single project."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"Account conversation analytics statistics.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_conversations":{"type":"number","description":"Total conversations in the timeframe."},"active_conversations":{"type":"number","description":"Conversations currently active in the timeframe."},"total_messages":{"type":"number","description":"Total messages in matching conversations."},"last_conversation_at":{"type":["string","null"],"description":"Most recent conversation activity timestamp."}},"required":["total_conversations","active_conversations","total_messages","last_conversation_at"]},"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Analytics aggregation granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of buckets returned."}},"required":["from","to","granularity","timezone","bucket_count"]},"series":{"type":"array","items":{"type":"object","properties":{"bucket_start":{"type":"string","description":"Bucket start timestamp."},"conversations":{"type":"number","description":"Conversations created in the bucket."},"messages":{"type":"number","description":"Messages in conversations created in the bucket."}},"required":["bucket_start","conversations","messages"]}},"statuses":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","description":"Status or outcome label."},"count":{"type":"number","description":"Number of matching records."}},"required":["status","count"]}},"models":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","description":"AI provider."},"model":{"type":"string","description":"AI model identifier."},"count":{"type":"number","description":"Number of uses."}},"required":["provider","model","count"]}},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Tool name."},"count":{"type":"number","description":"Number of uses."}},"required":["name","count"]}},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"count":{"type":"number","description":"Number of matching records."}},"required":["project_id","project_name","project_slug","count"]}},"recent_conversations":{"type":"array","items":{"type":"object","properties":{"conversation_id":{"type":"string","format":"uuid","description":"Conversation ID that can be opened in Studio."},"title":{"type":["string","null"],"description":"Conversation title, if available."},"status":{"type":"string","description":"Conversation status."},"project_id":{"type":["string","null"],"format":"uuid","description":"Owning project ID, if scoped."},"project_name":{"type":"string","description":"Owning project display name."},"project_slug":{"type":["string","null"],"description":"Owning project slug for Studio deep links, if available."},"last_activity_at":{"type":"string","description":"Most recent conversation activity timestamp."}},"required":["conversation_id","title","status","project_id","project_name","project_slug","last_activity_at"]}}},"required":["summary","timeframe","series","statuses","models","tools","projects","recent_conversations"]}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."},"403":{"description":"Access denied to the requested project."},"404":{"description":"Project not found."},"500":{"description":"Server error."}}}},"/auth/token":{"post":{"operationId":"oauthToken","tags":["Authentication"],"summary":"Create token","description":"Exchanges client credentials for an access token.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenRequest"}}}},"responses":{"200":{"description":"Token successfully generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenResponse"}}}},"400":{"description":"Invalid request or credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}}}}},"/auth/environment-token":{"post":{"operationId":"createEnvironmentToken","tags":["Authentication"],"summary":"Create environment access token","description":"Exchanges an API key for a five-minute token for one protected environment.\n\nAn account-wide key acts as its owner. A project-scoped key acts as a token principal within its own project.\n\nThe issued token is restricted to the selected project and environment. It cannot authenticate requests to this API. Revoking the API key does not revoke an issued token; the token remains valid until it expires.","security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentAccessTokenRequest"}}}},"responses":{"200":{"description":"Environment access token issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentAccessTokenResponse"}}}},"401":{"description":"A valid API key is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"403":{"description":"The key has no access to the target project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"404":{"description":"The project or environment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}}}}},"/auth/github":{"get":{"operationId":"githubOAuth","tags":["Authentication"],"summary":"GitHub OAuth","description":"Start or completes GitHub OAuth.","parameters":[{"schema":{"type":"string","maxLength":4096,"description":"URL to redirect after authentication (OAuth 2.0 standard)"},"required":false,"name":"redirect_uri","in":"query"},{"schema":{"type":"string","maxLength":8192,"description":"OAuth authorization code"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string","maxLength":4096,"description":"CSRF state token (maximum 4096 characters)"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","maxLength":8192,"description":"OAuth error code (for example, access_denied when user cancels)."},"required":false,"name":"error","in":"query"},{"schema":{"type":"string","description":"Human-readable error description"},"required":false,"name":"error_description","in":"query"}],"responses":{"302":{"description":"Redirect to GitHub or application"},"400":{"description":"OAuth error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"503":{"description":"OAuth state or consumption outcome could not be confirmed. Retry after recovery or start a new authorization flow.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/google":{"get":{"operationId":"googleOAuth","tags":["Authentication"],"summary":"Google OAuth","description":"Start or completes Google OAuth.","parameters":[{"schema":{"type":"string","maxLength":4096,"description":"URL to redirect after authentication (OAuth 2.0 standard)"},"required":false,"name":"redirect_uri","in":"query"},{"schema":{"type":"string","maxLength":8192,"description":"OAuth authorization code"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string","maxLength":4096,"description":"CSRF state token (maximum 4096 characters)"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","maxLength":8192,"description":"OAuth error code (for example, access_denied when user cancels)."},"required":false,"name":"error","in":"query"},{"schema":{"type":"string","description":"Human-readable error description"},"required":false,"name":"error_description","in":"query"},{"schema":{"type":"string","description":"Google issuer metadata returned on OAuth callbacks"},"required":false,"name":"iss","in":"query"},{"schema":{"type":"string","description":"Google granted scopes metadata returned on OAuth callbacks"},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","description":"Google account index metadata returned on OAuth callbacks"},"required":false,"name":"authuser","in":"query"},{"schema":{"type":"string","description":"Google Workspace hosted-domain metadata returned on OAuth callbacks"},"required":false,"name":"hd","in":"query"},{"schema":{"type":"string","description":"Google prompt metadata returned on OAuth callbacks"},"required":false,"name":"prompt","in":"query"}],"responses":{"302":{"description":"Redirect to Google or application"},"400":{"description":"OAuth error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"503":{"description":"OAuth state or consumption outcome could not be confirmed. Retry after recovery or start a new authorization flow.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/microsoft":{"get":{"operationId":"microsoftOAuth","tags":["Authentication"],"summary":"Microsoft OAuth","description":"Start or completes Microsoft OAuth.","parameters":[{"schema":{"type":"string","maxLength":4096,"description":"URL to redirect after authentication (OAuth 2.0 standard)"},"required":false,"name":"redirect_uri","in":"query"},{"schema":{"type":"string","maxLength":8192,"description":"OAuth authorization code"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string","maxLength":4096,"description":"CSRF state token (maximum 4096 characters)"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","maxLength":8192,"description":"OAuth error code (for example, access_denied when user cancels)."},"required":false,"name":"error","in":"query"},{"schema":{"type":"string","description":"Human-readable error description"},"required":false,"name":"error_description","in":"query"}],"responses":{"302":{"description":"Redirect to Microsoft or application"},"400":{"description":"OAuth error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"503":{"description":"OAuth state or consumption outcome could not be confirmed. Retry after recovery or start a new authorization flow.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/magiclink/create":{"post":{"operationId":"createMagicLink","tags":["Authentication"],"summary":"Create magic link","description":"Send a magic link for passwordless sign-in.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicLinkCreateRequest"}}}},"responses":{"201":{"description":"Magic link created and sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicLinkCreateResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}}}}},"/auth/magiclink":{"get":{"operationId":"verifyMagicLink","tags":["Authentication"],"summary":"Verify magic link","description":"Verifies a magic link token and signs in the user.","parameters":[{"schema":{"type":"string","description":"JWT token from magic link email"},"required":true,"name":"token","in":"query"},{"schema":{"type":"string","maxLength":4096,"format":"uri","description":"URL to redirect after verification"},"required":false,"name":"redirect_url","in":"query"},{"schema":{"type":"string","maxLength":4096,"format":"uri","description":"URL to redirect after verification (camelCase alias)"},"required":false,"name":"redirectUrl","in":"query"}],"responses":{"302":{"description":"Redirect to the application with an auth cookie set, or to the sign-in page with a typed magic_link_* failure reason"},"400":{"description":"Malformed request rejected by query validation before the handler runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"429":{"description":"Too many verification attempts","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Token consumption could not be confirmed; retry the request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/logout":{"get":{"operationId":"oauthLogoutGetMethodNotAllowed","tags":["Authentication"],"summary":"Log out (POST required)","description":"Rejects GET requests with `405 Method Not Allowed`. To end a session, use [`POST /auth/logout`](https://veryfront.com/docs/cloud/rest/api-reference/authentication/log-out). GET requests cannot revoke sessions.","responses":{"405":{"description":"Logout must use POST","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"post":{"operationId":"oauthLogout","tags":["Authentication"],"summary":"Log out","description":"Revokes the current session and clears the authentication cookie.\n\nSend the session JWT in the `authToken` cookie or the `Authorization: Bearer` header. Cookie authentication requires a trusted browser origin; bearer authentication does not.\n\nOnly a user session token with a verified signature is revoked. Other tokens are ignored, and the endpoint returns `200` to keep logout idempotent. If the API cannot confirm revocation, it returns `503`.","responses":{"200":{"description":"Successfully logged out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthLogoutResponse"}}}},"403":{"description":"Logout requires a trusted browser origin","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Session revocation could not be confirmed; retry logout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}}}}},"/.well-known/jwks.json":{"get":{"security":[],"operationId":"getJwks","tags":["Authentication"],"summary":"Get JWKS","description":"Return the JSON Web Key Set for API-issued JWTs.","responses":{"200":{"description":"Public JSON Web Key Set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JwksResponse"}}}},"500":{"description":"Server error while building JWKS","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me":{"get":{"operationId":"getProfile","tags":["Current user"],"summary":"Get profile","description":"Return the authenticated user profile and active paid subscription when present.","responses":{"200":{"description":"Current user profile","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Authenticated user ID"},"email":{"type":"string","format":"email","description":"User email address"},"name":{"type":"string","description":"User display name"},"avatar_src":{"type":"string","description":"User avatar image URL"},"role":{"type":"array","items":{"type":"string"},"description":"User roles"},"approved":{"type":"boolean","description":"Whether the user is approved"},"subscription":{"anyOf":[{"type":"object","properties":{"billing_mode":{"type":"string","enum":["stripe"]},"plan_type":{"type":"string","enum":["free","pro","enterprise"],"description":"Canonical plan resolved from the configured plan price ID"},"id":{"type":"string","format":"uuid","description":"Subscription ID"},"user_id":{"type":"string","format":"uuid","description":"User that owns the subscription"},"line_items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["plan","seat","server","sandbox"],"description":"Subscription line item kind"},"quantity":{"type":"number","description":"Line item quantity"}},"required":["kind","quantity"]},"description":"Subscription line items"},"expires_at":{"type":["string","null"],"description":"Current billing period end, or null for a non-expiring grant"},"created_at":{"type":"string","description":"Subscription creation timestamp"},"canceled_at":{"type":["string","null"],"description":"Subscription cancellation timestamp"}},"required":["plan_type","id","user_id","line_items","expires_at"]},{"type":"object","properties":{"billing_mode":{"type":"string","enum":["external"]},"plan_type":{"type":"string","enum":["free","pro","enterprise"],"description":"Canonical tier configured by the installation administrator"},"id":{"type":"string","format":"uuid","description":"Subscription ID"},"user_id":{"type":"string","format":"uuid","description":"User that owns the subscription"},"line_items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["plan","seat","server","sandbox"],"description":"Subscription line item kind"},"quantity":{"type":"number","description":"Line item quantity"}},"required":["kind","quantity"]},"description":"Subscription line items"},"expires_at":{"type":["string","null"],"description":"Current billing period end, or null for a non-expiring grant"},"created_at":{"type":"string","description":"Subscription creation timestamp"},"canceled_at":{"type":["string","null"],"description":"Subscription cancellation timestamp"},"entitlements":{"type":"object","properties":{"server_limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"seat_limit":{"type":"integer","exclusiveMinimum":0,"minimum":-9007199254740991,"maximum":9007199254740991}},"required":["server_limit","seat_limit"],"additionalProperties":false},"status":{"type":"string"},"current_period_start":{"type":["string","null"]},"current_period_end":{"type":["string","null"]}},"required":["billing_mode","plan_type","user_id","line_items","expires_at","entitlements"]}]}},"required":["id"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/accounts":{"get":{"operationId":"listAccounts","tags":["Accounts"],"summary":"List accounts","description":"List the accounts the caller belongs to, oldest first, with the caller’s role in each.","parameters":[{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/PaginationLimit"},{"schema":{"type":"string","maxLength":63,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"required":false,"name":"slug","in":"query"}],"responses":{"200":{"description":"Accounts the caller belongs to","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountWithMembership"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createAccount","tags":["Accounts"],"summary":"Create account","description":"Creates a team account owned by the caller. Account slugs are unique. If omitted, the slug is derived deterministically from the name.\n\nA repeated request with the same slug returns `409`. Use the account-list endpoint with the `slug` filter to find the existing account. To create a different account when the default slug is in use, provide an explicit slug.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"slug":{"type":"string","maxLength":63,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}},"required":["name"]}}}},"responses":{"201":{"description":"Account created; the caller is its owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWithMembership"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/accounts/{account_id}":{"get":{"operationId":"getAccount","tags":["Accounts"],"summary":"Get account","description":"Return the account and the caller’s membership in it.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"}],"responses":{"200":{"description":"The account and the caller’s membership","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWithMembership"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/accounts/{account_id}/members":{"get":{"operationId":"listAccountMembers","tags":["Account Members"],"summary":"List account members","description":"List the members of the account, oldest first.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"},{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/PaginationLimit"}],"responses":{"200":{"description":"Members of the account","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountMember"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/accounts/{account_id}/members/{user_id}":{"patch":{"operationId":"updateAccountMember","tags":["Account Members"],"summary":"Update account member","description":"Changes a member’s role. Promoting to or demoting from owner requires account ownership authority, and the account always keeps at least one owner. Setting the current role answers 200 without a change.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin"]}},"required":["role"]}}}},"responses":{"200":{"description":"The updated member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountMember"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"revokeAccountMember","tags":["Account Members"],"summary":"Revoke account member","description":"Removes a member from the account. Any member may remove themselves. Removing an owner requires account ownership authority, and the last owner cannot be removed. Projects and financial history are not touched.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"responses":{"204":{"description":"Membership removed"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/accounts/{account_id}/invitations":{"get":{"operationId":"listAccountInvitations","tags":["Account Invitations"],"summary":"List account invitations","description":"Lists the account’s invitations, newest first, filtered by status (pending by default). Tokens are never returned.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"},{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/PaginationLimit"},{"schema":{"type":"string","enum":["pending","accepted","revoked","expired","all"],"default":"pending"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Invitations of the account","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountInvitation"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createAccountInvitation","tags":["Account Invitations"],"summary":"Create account invitation","description":"Creates an invitation to join the account as an administrator. The response returns the acceptance token once. This endpoint does not send an email or reserve a seat.\n\nOnly one pending invitation is allowed per email address. Another request returns `409` until the invitation is revoked or expires.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email"},"role":{"type":"string","enum":["admin"],"default":"admin"}},"required":["email"]}}}},"responses":{"201":{"description":"Invitation created; the token is returned only here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountInvitationCreated"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/accounts/{account_id}/invitations/{invitation_id}":{"delete":{"operationId":"revokeAccountInvitation","tags":["Account Invitations"],"summary":"Revoke account invitation","description":"Revokes a pending invitation. Returns `204` if the invitation is already expired or revoked. For an accepted invitation, returns `409`; remove the account membership instead.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"account_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"invitation_id","in":"path"}],"responses":{"204":{"description":"Invitation revoked"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/accounts/-/invitations/accept":{"post":{"operationId":"acceptAccountInvitation","tags":["Account Invitations"],"summary":"Accept account invitation","description":"Accepts an invitation using its token. Requires a user session whose email address matches the invitation. API keys are not accepted.\n\nReturns `201` when a membership is created or `200` if the caller already accepted the invitation. Unknown or revoked tokens return `404`; expired tokens return `409`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":20,"maxLength":200}},"required":["token"]}}}},"responses":{"200":{"description":"Already a member; the existing membership","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWithMembership"}}}},"201":{"description":"Membership created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWithMembership"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/account/invites":{"get":{"operationId":"listAccountInvites","tags":["Account directory"],"summary":"List account invites","description":"Aggregates pending invites across all projects owned by the authenticated user.","parameters":[{"schema":{"type":"string","description":"Cursor for pagination (account invite row ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["created_at","email"],"default":"created_at","description":"Sort field. Defaults to \"created_at\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Aggregated pending account invites","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","pending"]},"user_id":{"type":["string","null"],"format":"uuid"},"invite_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]},"avatar_src":{"type":["string","null"]},"role":{"type":"string"},"seat_status":{"type":"string","enum":["active","reserved"]},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","editor","viewer"]}},"required":["id","slug","name","role"]}},"created_at":{"type":["string","null"]}},"required":["id","status","user_id","invite_ids","email","name","avatar_src","role","seat_status","projects"]}},"page_info":{"type":"object","properties":{"start_cursor":{"type":["string","null"]},"end_cursor":{"type":["string","null"]},"next_cursor":{"type":["string","null"]},"prev_cursor":{"type":["string","null"]},"total":{"type":"integer","minimum":0}},"required":["start_cursor","end_cursor","next_cursor","prev_cursor","total"]}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/account/users":{"get":{"operationId":"listAccountUsers","tags":["Account directory"],"summary":"List account users","description":"Aggregates active members across all projects owned by the authenticated user.","parameters":[{"schema":{"type":"string","description":"Cursor for pagination (account user row ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["name","type","project_count"],"default":"name","description":"Sort field. Defaults to \"name\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order. Defaults to \"asc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Aggregated active account users across owned projects","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","pending"]},"user_id":{"type":["string","null"],"format":"uuid"},"invite_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]},"avatar_src":{"type":["string","null"]},"role":{"type":"string"},"seat_status":{"type":"string","enum":["active","reserved"]},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","editor","viewer"]}},"required":["id","slug","name","role"]}},"created_at":{"type":["string","null"]}},"required":["id","status","user_id","invite_ids","email","name","avatar_src","role","seat_status","projects"]}},"page_info":{"type":"object","properties":{"start_cursor":{"type":["string","null"]},"end_cursor":{"type":["string","null"]},"next_cursor":{"type":["string","null"]},"prev_cursor":{"type":["string","null"]},"total":{"type":"integer","minimum":0}},"required":["start_cursor","end_cursor","next_cursor","prev_cursor","total"]}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/account/users/{user_id}/analytics/ai-usage":{"get":{"operationId":"getAccountMemberAiUsageAnalytics","tags":["Account directory"],"summary":"Get account member AI usage analytics","description":"Return recorded calls by a current member across projects owned by the authenticated user. This reads the project ledger, not the member’s personal account or quota rollups. API keys and runtime service credentials are refused.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"},{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","minLength":1,"default":"UTC"},"required":false,"name":"timezone","in":"query"}],"responses":{"200":{"description":"Owned-project member AI usage.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"credits_used":{"type":"number","description":"Total credits used."},"requests":{"type":"number","description":"Total AI requests."},"input_tokens":{"type":"number","description":"Total input tokens."},"output_tokens":{"type":"number","description":"Total output tokens."},"cache_creation_input_tokens":{"type":"number","description":"Total cache creation input tokens."},"cache_read_input_tokens":{"type":"number","description":"Total cache read input tokens."}},"required":["credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]},"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Usage aggregation granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of buckets returned."}},"required":["from","to","granularity","timezone","bucket_count"]},"series":{"type":"array","items":{"type":"object","properties":{"bucket_start":{"type":"string","description":"Bucket start timestamp."},"credits_used":{"type":"number","description":"Credits used in the bucket."},"requests":{"type":"number","description":"AI requests in the bucket."},"input_tokens":{"type":"number","description":"Input tokens in the bucket."},"output_tokens":{"type":"number","description":"Output tokens in the bucket."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens in the bucket."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens in the bucket."},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"credits_used":{"type":"number","description":"Credits used by this project."},"requests":{"type":"number","description":"AI requests billed to this project."},"input_tokens":{"type":"number","description":"Input tokens billed to this project."},"output_tokens":{"type":"number","description":"Output tokens billed to this project."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this project."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this project."}},"required":["project_id","project_name","project_slug","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}}},"required":["bucket_start","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","projects"]}},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"credits_used":{"type":"number","description":"Credits used by this project."},"requests":{"type":"number","description":"AI requests billed to this project."},"input_tokens":{"type":"number","description":"Input tokens billed to this project."},"output_tokens":{"type":"number","description":"Output tokens billed to this project."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this project."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this project."}},"required":["project_id","project_name","project_slug","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}},"models":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string","description":"Canonical or normalized AI model identifier."},"canonical_model_id":{"type":"string","description":"Canonical catalog model identifier."},"model_provider":{"type":"string","description":"Model vendor id. Known values: `anthropic`, `openai`, `google`, `mistral`, `moonshotai`, `deepseek`, `qwen`, `zai`, `unknown`. Other vendor ids may appear; clients must accept any string.","example":"anthropic"},"inference_provider":{"type":"string","description":"Inference provider handling the request. Known values: `veryfront-cloud`, `unknown`. Other values may appear; clients must accept any string.","example":"veryfront-cloud"},"credits_used":{"type":"number","description":"Credits used by this model."},"requests":{"type":"number","description":"AI requests billed to this model."},"input_tokens":{"type":"number","description":"Input tokens billed to this model."},"output_tokens":{"type":"number","description":"Output tokens billed to this model."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this model."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this model."},"provider_cost_usd":{"type":"number","description":"Model provider cost in USD for this model."},"veryfront_charge_usd":{"type":"number","description":"Veryfront charge in USD for this model."},"cost_attribution":{"type":"string","enum":["estimated"],"description":"Present when historical cost attribution was recovered from persisted credits."}},"required":["model","model_provider","inference_provider","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}},"serving":{"type":"array","items":{"type":"object","properties":{"host":{"type":["string","null"],"description":"Catalog ID of the deployment host, not a provider hostname or URL. Null means no deployment was recorded, including older usage, calls without a catalog deployment, and aggregated channel usage. Null does not indicate where inference ran."},"tier":{"type":["string","null"],"description":"Sovereignty tier as a catalog ID. Clients must accept unknown values as tiers can be added. Null means no tier was recorded and does not indicate where inference ran. The API does not infer a tier from billing or other fields.","example":"eu-resident"},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["host","tier","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]},"description":"The same spend cut by the deployment that served it. Ordered by spend descending, then by request count descending, then by host, then by tier; the row whose `host` and `tier` are both null is always last, because it is the absence of a record rather than a deployment. Additive: it neither replaces nor re-slices any other field. Omitted where the serving breakdown is not enabled; `models` is unchanged by it."},"scope":{"type":"object","properties":{"owner_id":{"type":"string","format":"uuid"},"member_id":{"type":"string","format":"uuid"}},"required":["owner_id","member_id"]},"attribution":{"type":"object","properties":{"enabled":{"type":"boolean"},"recording_since":{"type":["string","null"]}},"required":["enabled","recording_since"]}},"required":["summary","timeframe","series","projects","models","scope","attribution"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/users":{"get":{"operationId":"listProjectUsers","tags":["Project Members"],"summary":"List project users","description":"Returns a page of project members with their roles and resolved capabilities. Requires project.members.read. Use a user ID cursor; limit is an integer from 1 to 100 and defaults to 20.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Cursor for pagination (user ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of entries to return. Integer from 1 to 100; defaults to 20."},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated list of project members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectMember"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/users/{user_id}":{"get":{"operationId":"getProjectUser","tags":["Project Members"],"summary":"Get project user","description":"Returns a project member, resolved capabilities, and any member AI-budget projection. Requires project.members.read. Budget changes use the budgets API.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"responses":{"200":{"description":"Member details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectMemberDetail"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or member not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteProjectUser","tags":["Project Members"],"summary":"Delete project user","description":"Removes a project member. Requires project.members.manage. The last owner cannot be removed; transfer ownership first. Returns no response body.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"responses":{"204":{"description":"Member removed successfully"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or user not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/users/{user_id}/role":{"patch":{"operationId":"updateProjectUserRole","tags":["Project Members"],"summary":"Update project user role","description":"Updates a non-owner project member role. Requires project.members.manage. Existing owners cannot be changed and owner promotion is rejected; use ownership transfer.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["admin","editor","viewer"]}},"required":["role"]}}}},"responses":{"200":{"description":"Member role updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectMember"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or user not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/invites":{"get":{"operationId":"listProjectInvites","tags":["Project Invitations"],"summary":"List project invites","description":"Returns a page of pending invitations. Requires project.invites.read. Use an invitation ID cursor; limit is an integer from 1 to 100 and defaults to 20.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","description":"Cursor for pagination (invite ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of entries to return. Integer from 1 to 100; defaults to 20."},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated list of pending invites","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"role":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"invited_by":{"type":"string"},"created_at":{"type":["string","null"]}},"required":["id","email","role","project_id"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createProjectInvite","tags":["Project Invitations"],"summary":"Create project invite","description":"Adds an existing user directly or creates a pending invitation. Requires project.invites.manage and an available collaboration seat. The result type identifies which action occurred; email_sent reports notification delivery. Only a pending invitation has an invitation Location.","parameters":[{"$ref":"#/components/parameters/ProjectReference"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","editor","viewer"]}},"required":["email","role"]}}}},"responses":{"201":{"description":"User added or pending invitation created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"role":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"invited_by":{"type":"string"},"created_at":{"type":["string","null"]},"type":{"type":"string","enum":["USER_ADDED","INVITE_CREATED"],"description":"USER_ADDED means id identifies a user; INVITE_CREATED means id identifies a pending invitation."},"email_sent":{"type":"boolean","description":"Whether the email service accepted the notification send. False when sending is unavailable or fails; this does not confirm inbox delivery."}},"required":["id","email","role","project_id","type","email_sent"]}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Project owner has no available collaborator seats or collaborator feature allowance.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/invites/{invite_id}":{"get":{"operationId":"getProjectInvite","tags":["Project Invitations"],"summary":"Get project invite","description":"Returns a pending invitation belonging to the selected project. Requires project.invites.read.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"invite_id","in":"path"}],"responses":{"200":{"description":"Invite details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"role":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"invited_by":{"type":"string"},"created_at":{"type":["string","null"]}},"required":["id","email","role","project_id"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Invite not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteProjectInvite","tags":["Project Invitations"],"summary":"Delete project invite","description":"Deletes a pending invitation belonging to the selected project. Requires project.invites.manage. Returns no response body.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"invite_id","in":"path"}],"responses":{"204":{"description":"Invite deleted successfully"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Invite not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/invites/{invite_id}/resend":{"post":{"operationId":"resendProjectInvite","tags":["Project Invitations"],"summary":"Resend project invite","description":"Attempts to send another notification for a pending invitation without creating a duplicate. Requires project.invites.manage. The response returns the existing invitation; it does not report whether email delivery succeeded.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"invite_id","in":"path"}],"responses":{"200":{"description":"Existing invitation after notification attempt","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"role":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"invited_by":{"type":"string"},"created_at":{"type":["string","null"]}},"required":["id","email","role","project_id"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Invite not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/users/{user_id}/transfer-ownership":{"post":{"operationId":"transferProjectOwnership","tags":["Project Ownership"],"summary":"Transfer project ownership","description":"Transfers ownership to an existing project member. Requires project.members.manage and the authenticated current owner. Previous owners become administrators. Removes the new owner’s member AI budget.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"responses":{"200":{"description":"Project ownership transferred successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectMember"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Project or user not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api-keys":{"get":{"operationId":"listApiKeys","tags":["API keys"],"summary":"List API keys","description":"List API keys for the current user or a project.","parameters":[{"schema":{"type":"string"},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"description":"Deprecated project ID or slug alias. Use project_reference.","name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"description":"Deprecated camelCase project ID or slug alias. Use project_reference.","name":"projectId","in":"query"},{"schema":{"type":"string","enum":["active","expired","revoked","all"],"default":"active"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (API key ID)"},"required":false,"name":"cursor","in":"query"},{"$ref":"#/components/parameters/PaginationLimit"},{"schema":{"type":"string","enum":["created_at","name","last_used_at"],"default":"created_at","description":"Sort field. Defaults to \"created_at\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Paginated list of API keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":["string","null"],"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"},"last_used_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"status":{"type":"string","enum":["active","expired","revoked"]},"revoked_at":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["account","project"],"description":"Whether the key is restricted to one project or applies to the account. An account-wide key acts with its owner’s project roles, limited by the key’s scopes. Unlike project-scoped keys, it can inherit the owner’s administrative authority: `write` can allow API key creation, and `delete` can allow project deletion."},"inference_limits":{"$ref":"#/components/schemas/ApiKeyInferenceLimitsSummary"}},"required":["id","project_id","user_id","name","key_prefix","last_used_at","expires_at","created_at","updated_at","status","revoked_at","scopes","scope","inference_limits"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}},"post":{"operationId":"createApiKey","tags":["API keys"],"summary":"Create API key","description":"Create an API key for the current user or project.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_reference":{"type":"string"},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"projectId":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"name":{"type":"string","minLength":1,"maxLength":255},"scopes":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string"}},"required":["name"]}}}},"responses":{"201":{"description":"API key created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":["string","null"],"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key":{"type":"string"},"key_prefix":{"type":"string"},"expires_at":{"type":["string","null"]},"created_at":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["account","project"],"description":"Whether the key is restricted to one project or applies to the account. An account-wide key acts with its owner’s project roles, limited by the key’s scopes. Unlike project-scoped keys, it can inherit the owner’s administrative authority: `write` can allow API key creation, and `delete` can allow project deletion."}},"required":["id","project_id","user_id","name","key","key_prefix","expires_at","created_at","scopes","scope"]}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/api-keys/{id}":{"get":{"operationId":"getApiKey","tags":["API keys"],"summary":"Get API key","description":"Return an API key by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"API key details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":["string","null"],"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"},"last_used_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"status":{"type":"string","enum":["active","expired","revoked"]},"revoked_at":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["account","project"],"description":"Whether the key is restricted to one project or applies to the account. An account-wide key acts with its owner’s project roles, limited by the key’s scopes. Unlike project-scoped keys, it can inherit the owner’s administrative authority: `write` can allow API key creation, and `delete` can allow project deletion."},"budget":{"$ref":"#/components/schemas/SubjectBudget"},"budget_status":{"$ref":"#/components/schemas/SubjectBudgetStatus"}},"required":["id","project_id","user_id","name","key_prefix","last_used_at","expires_at","created_at","updated_at","status","revoked_at","scopes","scope","budget","budget_status"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"API key not found"},"500":{"description":"Server error"}}},"patch":{"operationId":"updateApiKey","tags":["API keys"],"summary":"Update API key","description":"Update an API key by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"expires_at":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"API key updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":["string","null"],"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"},"last_used_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"status":{"type":"string","enum":["active","expired","revoked"]},"revoked_at":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["account","project"],"description":"Whether the key is restricted to one project or applies to the account. An account-wide key acts with its owner’s project roles, limited by the key’s scopes. Unlike project-scoped keys, it can inherit the owner’s administrative authority: `write` can allow API key creation, and `delete` can allow project deletion."}},"required":["id","project_id","user_id","name","key_prefix","last_used_at","expires_at","created_at","updated_at","status","revoked_at","scopes","scope"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"API key not found"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteApiKey","tags":["API keys"],"summary":"Delete API key","description":"Delete an API key by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"API key deleted successfully"},"401":{"description":"Unauthorized"},"404":{"description":"API key not found"},"500":{"description":"Server error"}}}},"/.well-known/oauth-authorization-server":{"get":{"security":[],"operationId":"getMcpAuthorizationServerMetadata","tags":["OAuth Metadata"],"summary":"Discover MCP authorization endpoints","responses":{"200":{"description":"OAuth authorization server metadata","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string","format":"uri"},"authorization_endpoint":{"type":"string","format":"uri"},"token_endpoint":{"type":"string","format":"uri"},"registration_endpoint":{"type":"string","format":"uri"},"revocation_endpoint":{"type":"string","format":"uri"},"response_types_supported":{"type":"array","items":{"type":"string"}},"grant_types_supported":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_methods_supported":{"type":"array","items":{"type":"string"}},"revocation_endpoint_auth_methods_supported":{"type":"array","items":{"type":"string"}},"code_challenge_methods_supported":{"type":"array","items":{"type":"string"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"authorization_response_iss_parameter_supported":{"type":"boolean"}},"required":["issuer","authorization_endpoint","token_endpoint","registration_endpoint","revocation_endpoint","response_types_supported","grant_types_supported","token_endpoint_auth_methods_supported","revocation_endpoint_auth_methods_supported","code_challenge_methods_supported","scopes_supported","authorization_response_iss_parameter_supported"]}}}}}}},"/.well-known/oauth-protected-resource/mcp":{"get":{"security":[],"operationId":"getMcpProtectedResourceMetadata","tags":["OAuth Metadata"],"summary":"Discover root MCP authorization","responses":{"200":{"description":"OAuth protected resource metadata","content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}}},"required":["resource","authorization_servers","scopes_supported","bearer_methods_supported"]}}}}}}},"/.well-known/oauth-protected-resource/projects/{project_reference}/mcp":{"get":{"security":[],"operationId":"getProjectMcpProtectedResourceMetadata","tags":["OAuth Metadata"],"summary":"Discover project MCP authorization","parameters":[{"schema":{"type":"string","pattern":"^[a-zA-Z0-9-]+$"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"OAuth protected resource metadata","content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}}},"required":["resource","authorization_servers","scopes_supported","bearer_methods_supported"]}}}}}}},"/oauth/register":{"post":{"security":[],"operationId":"registerMcpOAuthClient","tags":["OAuth Clients"],"summary":"Register a public MCP client","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"redirect_uris":{"type":"array","items":{"type":"string","maxLength":2048},"minItems":1,"maxItems":20},"client_name":{"type":"string","minLength":1,"maxLength":200},"client_uri":{"type":"string","maxLength":2048,"format":"uri"},"software_id":{"type":"string","maxLength":200},"software_version":{"type":"string","maxLength":100},"token_endpoint_auth_method":{"type":"string","enum":["none"],"default":"none"},"grant_types":{"type":"array","items":{"type":"string","enum":["authorization_code","refresh_token"]},"default":["authorization_code","refresh_token"]},"response_types":{"type":"array","items":{"type":"string","enum":["code"]},"default":["code"]}},"required":["redirect_uris"]}}}},"responses":{"201":{"description":"Public client registration","content":{"application/json":{"schema":{"type":"object","properties":{"redirect_uris":{"type":"array","items":{"type":"string","maxLength":2048},"minItems":1,"maxItems":20},"client_name":{"type":"string","minLength":1,"maxLength":200},"client_uri":{"type":"string","maxLength":2048,"format":"uri"},"software_id":{"type":"string","maxLength":200},"software_version":{"type":"string","maxLength":100},"token_endpoint_auth_method":{"type":"string","enum":["none"],"default":"none"},"grant_types":{"type":"array","items":{"type":"string","enum":["authorization_code","refresh_token"]},"default":["authorization_code","refresh_token"]},"response_types":{"type":"array","items":{"type":"string","enum":["code"]},"default":["code"]},"client_id":{"type":"string"},"client_id_issued_at":{"type":"number"}},"required":["redirect_uris","client_id","client_id_issued_at"]}}}},"400":{"description":"Invalid OAuth request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}},"500":{"description":"OAuth service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}}}}},"/oauth/authorize":{"get":{"security":[],"operationId":"authorizeMcpOAuthClient","tags":["OAuth Authorization Requests"],"summary":"Start MCP authorization with PKCE","parameters":[{"schema":{"type":"string","enum":["code"]},"required":true,"name":"response_type","in":"query"},{"schema":{"type":"string","maxLength":200},"required":true,"name":"client_id","in":"query"},{"schema":{"type":"string","maxLength":2048},"required":true,"name":"redirect_uri","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"required":true,"name":"code_challenge","in":"query"},{"schema":{"type":"string","enum":["S256"]},"required":true,"name":"code_challenge_method","in":"query"},{"schema":{"type":"string","maxLength":2048},"required":false,"name":"resource","in":"query"},{"schema":{"type":"string","enum":["mcp"],"default":"mcp"},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","maxLength":2048},"required":false,"name":"state","in":"query"}],"responses":{"302":{"description":"Continue to Veryfront consent, or return an OAuth error to the validated callback with state and iss"},"400":{"description":"Unknown client or unregistered redirect URI; never redirected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}},"500":{"description":"OAuth service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}}}}},"/oauth/authorization-requests/{id}":{"get":{"operationId":"getMcpAuthorizationRequest","tags":["OAuth Authorization Requests"],"summary":"Read an MCP authorization request","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"User-bound consent request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client":{"type":"object","properties":{"client_id":{"type":"string"},"client_name":{"type":["string","null"]},"client_uri":{"type":["string","null"]}},"required":["client_id","client_name","client_uri"]},"redirect_host":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"resource":{"type":"string"},"expires_at":{"type":"string"},"consent_token":{"type":"string"}},"required":["id","client","redirect_host","scopes","resource","expires_at","consent_token"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Unsupported media type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/authorization-requests/{id}/decision":{"post":{"operationId":"decideMcpAuthorizationRequest","tags":["OAuth Authorization Requests"],"summary":"Approve or deny MCP access","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","deny"]},"consent_token":{"type":"string","minLength":20,"maxLength":200}},"required":["decision","consent_token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Registered client callback","content":{"application/json":{"schema":{"type":"object","properties":{"redirect_to":{"type":"string","format":"uri"}},"required":["redirect_to"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Unsupported media type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/token":{"post":{"security":[],"operationId":"exchangeMcpOAuthToken","tags":["OAuth Tokens"],"summary":"Exchange a code or rotate an MCP refresh token","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"oneOf":[{"type":"object","properties":{"grant_type":{"type":"string","enum":["authorization_code"]},"client_id":{"type":"string","maxLength":200},"code":{"type":"string","maxLength":200},"redirect_uri":{"type":"string","maxLength":2048},"code_verifier":{"type":"string","pattern":"^[A-Za-z0-9._~-]{43,128}$"},"resource":{"type":"string","maxLength":2048}},"required":["grant_type","client_id","code","redirect_uri","code_verifier"]},{"type":"object","properties":{"grant_type":{"type":"string","enum":["refresh_token"]},"client_id":{"type":"string","maxLength":200},"refresh_token":{"type":"string","maxLength":200},"resource":{"type":"string","maxLength":2048},"scope":{"type":"string","enum":["mcp"]}},"required":["grant_type","client_id","refresh_token"]}]}}}},"responses":{"200":{"description":"MCP access and refresh tokens","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"number"},"scope":{"type":"string","enum":["mcp"]}},"required":["access_token","refresh_token","token_type","expires_in","scope"]}}}},"400":{"description":"Invalid OAuth request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}},"500":{"description":"OAuth service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}}}}},"/oauth/revoke":{"post":{"security":[],"operationId":"revokeMcpOAuthToken","tags":["OAuth Tokens"],"summary":"Revoke an MCP client grant","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"client_id":{"type":"string","maxLength":200},"token":{"type":"string","maxLength":200},"token_type_hint":{"type":"string"}},"required":["client_id","token"]}}}},"responses":{"200":{"description":"Revocation processed without disclosing token validity"},"400":{"description":"Invalid OAuth request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}},"500":{"description":"OAuth service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}}}}},"/oauth/grants":{"get":{"operationId":"listMcpAuthorizationGrants","tags":["OAuth Grants"],"summary":"List authorized MCP apps","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Active grants for the signed-in user","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"client":{"type":"object","properties":{"client_id":{"type":"string"},"client_name":{"type":["string","null"]},"client_uri":{"type":["string","null"]}},"required":["client_id","client_name","client_uri"]},"redirect_host":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"resource":{"type":"string"},"created_at":{"type":"string"},"last_used_at":{"type":["string","null"]}},"required":["id","client","redirect_host","scopes","resource","created_at","last_used_at"]}},"page_info":{"type":"object","properties":{"self":{"type":["string","null"]},"first":{"type":["string","null"]},"next":{"type":["string","null"]},"prev":{"type":["string","null"]}},"required":["self","first","next","prev"]}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Unsupported media type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/grants/{id}":{"delete":{"operationId":"revokeMcpAuthorizationGrant","tags":["OAuth Grants"],"summary":"Revoke an authorized MCP app","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Grant revoked"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Unsupported media type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/collaboration":{"get":{"operationId":"getProjectCollaboration","tags":["Account Collaboration"],"summary":"Get project collaboration","description":"Returns entitlement and owner-wide seat usage across all projects owned by the project owner. can_invite means collaboration is entitled and a seat is available; it does not grant the requester permission to send invitations.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Project collaboration summary retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"seats":{"type":"object","properties":{"purchased":{"type":"integer","minimum":1,"description":"Seat capacity provided by the project owner subscription or external entitlement."},"active":{"type":"integer","minimum":0,"description":"Distinct active users across all projects owned by this project owner."},"reserved":{"type":"integer","minimum":0,"description":"Distinct pending invitation emails across owner projects, excluding emails already represented by active users."},"available":{"type":"integer","minimum":0,"description":"Owner seat capacity minus active and reserved seats, clamped to zero."}},"required":["purchased","active","reserved","available"],"description":"Owner-wide seat usage, shared across every project owned by the same user."},"over_capacity":{"type":"boolean","description":"True when owner-wide active plus reserved seats exceed seat capacity."},"collaboration_allowed":{"type":"boolean","description":"Whether the project owner entitlement allows collaborators."},"can_invite":{"type":"boolean","description":"True when the owner entitlement allows collaborators and at least one seat is available. Does not indicate whether the requester may send invitations."}},"required":["seats","over_capacity","collaboration_allowed","can_invite"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/account/subscription":{"get":{"operationId":"getSubscription","tags":["Subscriptions"],"summary":"Get subscription","description":"Returns the current authenticated user subscription. In external billing mode, returns configured entitlements for an existing user even without a stored subscription.","responses":{"200":{"description":"Subscription details","content":{"application/json":{"schema":{"type":"object","properties":{"billing_mode":{"type":"string","enum":["stripe","external"]},"entitlements":{"type":"object","properties":{"server_limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"seat_limit":{"type":"integer","exclusiveMinimum":0,"minimum":-9007199254740991,"maximum":9007199254740991}},"required":["server_limit","seat_limit"],"additionalProperties":false},"plan_type":{"type":"string","enum":["free","pro","enterprise"],"description":"Canonical plan resolved from the configured plan price ID, independent of billed amount"},"id":{"type":"string","format":"uuid","description":"Subscription ID"},"user_id":{"type":"string","format":"uuid","description":"User that owns the subscription"},"project_id":{"type":["string","null"],"format":"uuid","description":"Project this subscription is scoped to, when applicable"},"server_usage":{"type":"number","description":"Active dedicated server records for the account"},"sandbox_usage":{"type":"number","description":"Active sandbox records for the account"},"server_usage_details":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Server ID"},"short_id":{"type":"string","description":"Short server identifier"},"status":{"type":"string","enum":["pending","provisioning","running"],"description":"Active server status counted against add-on usage"},"environment_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Environment IDs linked to the server"},"environments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Environment ID linked to the server"},"name":{"type":"string","description":"Environment name"},"project_id":{"type":"string","format":"uuid","description":"Project ID that owns the environment"},"project_name":{"type":"string","description":"Project display name"},"project_slug":{"type":"string","description":"Project slug"}},"required":["id","name","project_id","project_name","project_slug"]},"description":"Linked environment labels across accessible projects"}},"required":["id","short_id","status","environment_ids","environments"]},"description":"Active server add-on usage with linked project and environment labels"},"line_items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["plan","seat","server","sandbox"],"description":"Subscription line item kind"},"quantity":{"type":"number","description":"Line item quantity"},"recurring_interval":{"type":["string","null"],"enum":["monthly","yearly",null],"description":"Line item billing interval when price-classifiable"},"unit_amount":{"type":["number","null"],"description":"Line item unit amount in minor currency units"},"currency":{"type":["string","null"],"description":"Line item currency"}},"required":["kind","quantity"]},"description":"Subscription line items. Credits are one-time top-ups and are not included here."},"status":{"type":"string","description":"Subscription status"},"current_period_start":{"type":["string","null"],"description":"Current billing period start timestamp"},"current_period_end":{"type":["string","null"],"description":"Current billing period end timestamp"},"expires_at":{"type":["string","null"],"description":"Subscription expiration timestamp"},"canceled_at":{"type":["string","null"],"description":"Subscription cancellation timestamp"},"created_at":{"type":"string","description":"Subscription creation timestamp"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No subscription found"},"500":{"description":"Server error"}}}},"/account/subscription/checkout":{"post":{"operationId":"createCheckoutSession","tags":["Subscriptions"],"summary":"Create checkout session","description":"Create a checkout session for a new subscription.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["free","pro","enterprise"],"description":"Subscription tier.","example":"pro"},"cycle":{"type":"string","enum":["monthly","yearly"],"description":"Billing cycle","example":"monthly"},"success_url":{"type":"string","format":"uri","description":"URL to redirect to after successful payment"},"cancel_url":{"type":"string","format":"uri","description":"URL to redirect to if payment is canceled."}},"required":["type","cycle"]}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri","description":"Stripe checkout URL"},"session_id":{"type":"string","description":"Checkout session ID, when returned"}},"required":["checkout_url"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - untrusted billing origin"},"500":{"description":"Server error"}}}},"/account/subscription/manage":{"get":{"operationId":"getBillingPortalUrl","tags":["Subscriptions"],"summary":"Get billing portal URL","description":"Return the billing portal URL for the current subscription.","responses":{"200":{"description":"Management portal URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Stripe billing portal URL"}},"required":["url"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - untrusted billing origin"},"404":{"description":"No active subscription to manage"},"500":{"description":"Server error"}}}},"/account/subscription/upgrade":{"post":{"operationId":"upgradeSubscription","tags":["Subscriptions"],"summary":"Upgrade subscription","description":"Create a checkout session to upgrade a subscription.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["free","pro","enterprise"],"description":"Subscription tier to upgrade to.","example":"pro"},"cycle":{"type":"string","enum":["monthly","yearly"],"description":"Billing cycle","example":"monthly"},"quantity":{"type":"integer","minimum":1,"description":"Seat quantity for licensed subscriptions","example":3},"server_quantity":{"type":["integer","null"],"minimum":0,"description":"Recurring server add-on quantity","example":2},"sandbox_quantity":{"type":["integer","null"],"minimum":0,"description":"Recurring sandbox add-on quantity","example":2},"success_url":{"type":"string","format":"uri","description":"URL to redirect to after successful payment"},"cancel_url":{"type":"string","format":"uri","description":"URL to redirect to if payment is canceled."}},"required":["type","cycle"]}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Upgrade status"},"amount":{"type":["string","null"],"description":"Formatted amount due, when available"},"checkout_url":{"type":["string","null"],"description":"Checkout URL, when payment is required"},"error":{"type":["string","null"],"description":"Error message when status is error"}},"required":["status"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - untrusted billing origin"},"500":{"description":"Server error"}}}},"/account/subscription/cancel":{"post":{"operationId":"cancelSubscription","tags":["Subscriptions"],"summary":"Cancel subscription","description":"Cancel the current authenticated user subscription.","responses":{"200":{"description":"Subscription canceled.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether cancellation succeeded"},"subscription":{"type":"object","properties":{"billing_mode":{"type":"string","enum":["stripe","external"]},"entitlements":{"type":"object","properties":{"server_limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"seat_limit":{"type":"integer","exclusiveMinimum":0,"minimum":-9007199254740991,"maximum":9007199254740991}},"required":["server_limit","seat_limit"],"additionalProperties":false},"plan_type":{"type":"string","enum":["free","pro","enterprise"],"description":"Canonical plan resolved from the configured plan price ID, independent of billed amount"},"id":{"type":"string","format":"uuid","description":"Subscription ID"},"user_id":{"type":"string","format":"uuid","description":"User that owns the subscription"},"project_id":{"type":["string","null"],"format":"uuid","description":"Project this subscription is scoped to, when applicable"},"server_usage":{"type":"number","description":"Active dedicated server records for the account"},"sandbox_usage":{"type":"number","description":"Active sandbox records for the account"},"server_usage_details":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Server ID"},"short_id":{"type":"string","description":"Short server identifier"},"status":{"type":"string","enum":["pending","provisioning","running"],"description":"Active server status counted against add-on usage"},"environment_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Environment IDs linked to the server"},"environments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Environment ID linked to the server"},"name":{"type":"string","description":"Environment name"},"project_id":{"type":"string","format":"uuid","description":"Project ID that owns the environment"},"project_name":{"type":"string","description":"Project display name"},"project_slug":{"type":"string","description":"Project slug"}},"required":["id","name","project_id","project_name","project_slug"]},"description":"Linked environment labels across accessible projects"}},"required":["id","short_id","status","environment_ids","environments"]},"description":"Active server add-on usage with linked project and environment labels"},"line_items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["plan","seat","server","sandbox"],"description":"Subscription line item kind"},"quantity":{"type":"number","description":"Line item quantity"},"recurring_interval":{"type":["string","null"],"enum":["monthly","yearly",null],"description":"Line item billing interval when price-classifiable"},"unit_amount":{"type":["number","null"],"description":"Line item unit amount in minor currency units"},"currency":{"type":["string","null"],"description":"Line item currency"}},"required":["kind","quantity"]},"description":"Subscription line items. Credits are one-time top-ups and are not included here."},"status":{"type":"string","description":"Subscription status"},"current_period_start":{"type":["string","null"],"description":"Current billing period start timestamp"},"current_period_end":{"type":["string","null"],"description":"Current billing period end timestamp"},"expires_at":{"type":["string","null"],"description":"Subscription expiration timestamp"},"canceled_at":{"type":["string","null"],"description":"Subscription cancellation timestamp"},"created_at":{"type":"string","description":"Subscription creation timestamp"}}},"error":{"type":["string","null"],"description":"Cancellation error message, when present"}},"required":["success"]}}}},"400":{"description":"No active subscription found"},"401":{"description":"Unauthorized"},"402":{"description":"Downgrade blocked until seat usage is reduced"},"403":{"description":"Forbidden - untrusted billing origin"},"500":{"description":"Server error"}}}},"/account/billing-details":{"get":{"operationId":"getBillingDetails","tags":["Billing Details"],"summary":"Get billing details","description":"Return Stripe customer billing details for the current account when available.","responses":{"200":{"description":"Billing details","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"phone":{"type":["string","null"]},"address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["line1","line2","city","state","postal_code","country"]},"tax_ids":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":["string","null"]}},"required":["id","type","value"]}}},"required":["name","email","phone","address","tax_ids"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}},"patch":{"operationId":"updateBillingDetails","tags":["Billing Details"],"summary":"Update billing details","description":"Update Stripe customer name, email, phone, or address, individually or together.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"phone":{"type":["string","null"]},"address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]}}}}}}}},"responses":{"200":{"description":"Updated billing details","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"phone":{"type":["string","null"]},"address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["line1","line2","city","state","postal_code","country"]},"tax_ids":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":["string","null"]}},"required":["id","type","value"]}}},"required":["name","email","phone","address","tax_ids"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Stripe billing customer found"},"500":{"description":"Server error"}}}},"/account/invoices":{"get":{"operationId":"listBillingInvoices","tags":["Invoices"],"summary":"List billing invoices","description":"List Stripe invoices for the current account customer when available.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["date","amount","status"],"default":"date","description":"Sort field. Defaults to \"date\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Billing invoices","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":["string","null"]},"status":{"type":["string","null"]},"description":{"type":["string","null"]},"amount_due":{"type":"number"},"amount_paid":{"type":"number"},"amount_total":{"type":"number"},"applied_balance_amount":{"type":"number"},"proration_amount":{"type":"number"},"recurring_amount":{"type":"number"},"currency":{"type":"string"},"issued_at":{"type":"string"},"hosted_invoice_url":{"type":["string","null"],"format":"uri"},"pdf_url":{"type":["string","null"],"format":"uri"}},"required":["id","number","status","description","amount_due","amount_paid","currency","issued_at","hosted_invoice_url","pdf_url"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/account/upcoming-invoices":{"get":{"operationId":"listUpcomingBillingInvoices","tags":["Invoices"],"summary":"List upcoming billing invoices","description":"List Stripe upcoming invoice previews and draft invoices for the current account customer when available.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["date","amount","status"],"default":"date","description":"Sort field. Defaults to \"date\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Upcoming billing invoices","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":["string","null"]},"status":{"type":["string","null"]},"description":{"type":["string","null"]},"amount_due":{"type":"number"},"amount_paid":{"type":"number"},"amount_total":{"type":"number"},"applied_balance_amount":{"type":"number"},"proration_amount":{"type":"number"},"recurring_amount":{"type":"number"},"currency":{"type":"string"},"issued_at":{"type":"string"},"hosted_invoice_url":{"type":["string","null"],"format":"uri"},"pdf_url":{"type":["string","null"],"format":"uri"}},"required":["id","number","status","description","amount_due","amount_paid","currency","issued_at","hosted_invoice_url","pdf_url"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/account/payment-methods":{"get":{"operationId":"listPaymentMethods","tags":["Payment Methods"],"summary":"List payment methods","description":"List Stripe card payment methods for the current account customer.","responses":{"200":{"description":"Payment methods","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":["string","null"]},"last4":{"type":["string","null"]},"exp_month":{"type":["number","null"]},"exp_year":{"type":["number","null"]},"is_default":{"type":"boolean"}},"required":["id","brand","last4","exp_month","exp_year","is_default"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}},"post":{"operationId":"attachPaymentMethod","tags":["Payment Methods"],"summary":"Attach payment method","description":"Attaches an existing Stripe PaymentMethod to the current account customer.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payment_method_id":{"type":"string","minLength":1}},"required":["payment_method_id"]}}}},"responses":{"200":{"description":"Attached payment method","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":["string","null"]},"last4":{"type":["string","null"]},"exp_month":{"type":["number","null"]},"exp_year":{"type":["number","null"]},"is_default":{"type":"boolean"}},"required":["id","brand","last4","exp_month","exp_year","is_default"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Stripe billing customer found"},"500":{"description":"Server error"}}}},"/account/payment-methods/{payment_method_id}":{"patch":{"operationId":"setDefaultPaymentMethod","tags":["Payment Methods"],"summary":"Set default payment method","description":"Set a payment method as the default for the current account customer.","parameters":[{"schema":{"type":"string"},"required":true,"name":"payment_method_id","in":"path"}],"responses":{"200":{"description":"Updated payment method","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":["string","null"]},"last4":{"type":["string","null"]},"exp_month":{"type":["number","null"]},"exp_year":{"type":["number","null"]},"is_default":{"type":"boolean"}},"required":["id","brand","last4","exp_month","exp_year","is_default"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Stripe billing customer found"},"500":{"description":"Server error"}}},"delete":{"operationId":"detachPaymentMethod","tags":["Payment Methods"],"summary":"Detach payment method","description":"Detaches a payment method from the current account customer.","parameters":[{"schema":{"type":"string"},"required":true,"name":"payment_method_id","in":"path"}],"responses":{"200":{"description":"Detached payment method ID","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Stripe billing customer found"},"500":{"description":"Server error"}}}},"/account/payments":{"get":{"operationId":"listBillingPayments","tags":["Payments"],"summary":"List billing payments","description":"List Stripe payments and receipt links for the current account customer when available.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["date","amount"],"default":"date","description":"Sort field. Defaults to \"date\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Billing payments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":["string","null"]},"paid":{"type":"boolean"},"amount":{"type":"number"},"currency":{"type":"string"},"created_at":{"type":"string"},"description":{"type":["string","null"]},"receipt_url":{"type":["string","null"],"format":"uri"},"invoice_id":{"type":["string","null"]},"payment_intent_id":{"type":["string","null"]}},"required":["id","status","paid","amount","currency","created_at","description","receipt_url","invoice_id","payment_intent_id"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/credits/balance":{"get":{"operationId":"getCreditBalance","tags":["Credits"],"summary":"Get credit balance","description":"Return the authenticated user credit balance by pool and the effective tier top-up rate in EUR.","responses":{"200":{"description":"Credit balance by pool","content":{"application/json":{"schema":{"type":"object","properties":{"credit_price_eur":{"type":"number","minimum":0,"description":"EUR top-up price per credit for the effective subscription tier; not a per-usage charge or package price","example":0.15},"tier":{"type":"number","description":"Credits remaining in the monthly tier pool","example":50},"purchased":{"type":"number","description":"Credits remaining in the purchased pool","example":100},"total":{"type":"number","description":"Total credits remaining across all pools","example":150},"tier_limit":{"type":"number","description":"Monthly credit allocation for the user tier","example":50}},"required":["credit_price_eur","tier","purchased","total","tier_limit"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/credits/packages":{"get":{"operationId":"listCreditPackages","tags":["Credits"],"summary":"List credit packages","description":"Return credit top-up packages available to the authenticated user.","responses":{"200":{"description":"Available credit packages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Credit package ID","example":"small"},"credits":{"type":"number","description":"Number of credits included in the package","example":100},"price_eur":{"type":"number","description":"Package price in EUR","example":5},"available":{"type":"boolean","description":"Whether this package is currently purchasable"}},"required":["id","credits","price_eur","available"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}}}}},"/credits/topup":{"post":{"operationId":"createCreditCheckout","tags":["Credits"],"summary":"Create credit checkout","description":"Create a checkout session for a credit package top-up.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"packageId":{"type":"string","enum":["small","medium","large","xl"],"description":"Credit package ID in camelCase form"},"package_id":{"type":"string","enum":["small","medium","large","xl"],"description":"Credit package ID in snake_case form"},"project_reference":{"type":"string","description":"Project UUID or slug for owner-pays top-up"},"projectId":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"project_id":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"successUrl":{"type":"string","format":"uri","description":"Checkout success redirect URL in camelCase form"},"success_url":{"type":"string","format":"uri","description":"Checkout success redirect URL in snake_case form"},"cancelUrl":{"type":"string","format":"uri","description":"Checkout cancellation redirect URL in camelCase form"},"cancel_url":{"type":"string","format":"uri","description":"Checkout cancellation redirect URL in snake_case form"}}}}}},"responses":{"200":{"description":"Checkout session result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["checkout_created"],"description":"Checkout creation status"},"checkout_url":{"type":"string","format":"uri","description":"Stripe checkout URL for the credit purchase"}},"required":["status","checkout_url"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/credits/coupons/redeem":{"post":{"operationId":"redeemCreditCoupon","tags":["Credits"],"summary":"Redeem credit coupon","description":"Redeems a Stripe promotion code for authenticated user account credits.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":100,"description":"Stripe promotion code to redeem for Veryfront credits","example":"FREE100"}},"required":["code"]}}}},"responses":{"200":{"description":"Coupon redemption result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["redeemed","already_redeemed"],"description":"Coupon redemption result"},"credits_granted":{"type":"integer","minimum":0,"description":"Credits granted by this request","example":100},"balance":{"type":"object","properties":{"tier":{"type":"number","description":"Credits remaining in the monthly tier pool","example":50},"purchased":{"type":"number","description":"Credits remaining in the purchased pool","example":100},"total":{"type":"number","description":"Total credits remaining across all pools","example":150}},"required":["tier","purchased","total"],"description":"Updated credit balance"},"transaction_id":{"type":["string","null"],"description":"Credit transaction associated with the redemption"}},"required":["status","credits_granted","balance","transaction_id"]}}}},"400":{"description":"Invalid coupon code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}},"402":{"description":"Coupon redemption limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/credits/transactions":{"get":{"operationId":"listCreditTransactions","tags":["Credits"],"summary":"List credit transactions","description":"Return cursor-paginated credit transaction history for the authenticated user, optionally filtered by normalized activity category.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of transactions to return","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque transaction cursor returned in page_info.next"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["ai_usage","run_runtime","sandbox_runtime","credit_purchase","coupon_redemption","tier_grant","refund","other_usage"],"description":"Normalized activity category to filter before pagination","example":"ai_usage"},"required":false,"name":"activity_type","in":"query"},{"schema":{"type":"string","enum":["date","amount","activity"],"default":"date","description":"Sort field. Defaults to \"date\"."},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order. Defaults to \"desc\"."},"required":false,"name":"sort_order","in":"query"}],"responses":{"200":{"description":"Credit transaction page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Credit transaction ID"},"user_id":{"type":"string","description":"User that owns the transaction"},"type":{"type":"string","enum":["tier_grant","purchase","spend","refund"],"description":"Credit transaction type"},"pool":{"type":"string","enum":["tier","purchased"],"description":"Credit pool affected by this transaction"},"amount":{"type":"number","description":"Credit delta for the transaction"},"description":{"type":["string","null"],"description":"Human-readable transaction description"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Structured transaction metadata such as sandbox lifecycle billing context"},"activity_type":{"type":"string","enum":["ai_usage","run_runtime","sandbox_runtime","credit_purchase","coupon_redemption","tier_grant","refund","other_usage"],"description":"Normalized activity category for usage filtering"},"project_id":{"type":["string","null"],"description":"Project ID associated with the transaction"},"project_name":{"type":["string","null"],"description":"Project name associated with the transaction"},"project_slug":{"type":["string","null"],"description":"Project slug associated with the transaction"},"created_at":{"type":"string","description":"ISO timestamp when the transaction was created"}},"required":["id","user_id","type","pool","amount","description","metadata","activity_type","created_at"]}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/budgets":{"get":{"operationId":"listBudgets","tags":["Budgets"],"summary":"List budgets","description":"Lists monthly AI budgets that you can manage. Filter by project, person, or API key.\n\nA budget caps monthly AI spending for a project, person, API key, or combination of these fields. A request must match every field in the budget scope. If several budgets apply, the most specific exhausted budget rejects the request before account credit and provider spending checks.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Lists the budgets of one project: its own, its members’, and the keys bound to it. Requires owner or admin on that project. Omitted, the listing covers every budget the caller may manage."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Narrows the listing to the budgets scoped to one person."},"required":false,"name":"user_id","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Narrows the listing to the budgets scoped to one API key."},"required":false,"name":"api_key_id","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (budget ID)"},"required":false,"name":"cursor","in":"query"},{"$ref":"#/components/parameters/PaginationLimit"}],"responses":{"200":{"description":"Budgets the caller may manage","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Budget"}},"page_info":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"createBudget","tags":["Budgets"],"summary":"Create budget","description":"Creates a monthly AI spending limit. Usage already recorded this month counts toward the limit. Only one budget is allowed per scope; use PATCH to change an existing limit.\n\nA budget caps monthly AI spending for a project, person, API key, or combination of these fields. A request must match every field in the budget scope. If several budgets apply, the most specific exhausted budget rejects the request before account credit and provider spending checks.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBudgetInput"}}}},"responses":{"201":{"description":"Budget created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Budget"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/budgets/{budget_id}":{"get":{"operationId":"getBudget","tags":["Budgets"],"summary":"Get budget","description":"Returns a budget, usage for the current month, remaining credits, and the reset time.\n\nA budget caps monthly AI spending for a project, person, API key, or combination of these fields. A request must match every field in the budget scope. If several budgets apply, the most specific exhausted budget rejects the request before account credit and provider spending checks.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"budget_id","in":"path"}],"responses":{"200":{"description":"The budget and its usage for the current month.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Budget"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"updateBudget","tags":["Budgets"],"summary":"Update budget","description":"Changes the monthly spending limit without resetting usage. If the new limit is below spending already recorded this month, the next call is rejected. The budget’s scope cannot change; create a separate budget for a different scope.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"budget_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBudgetInput"}}}},"responses":{"200":{"description":"Budget updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Budget"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"deleteBudget","tags":["Budgets"],"summary":"Delete budget","description":"Removes the budget without changing usage history. Other applicable budgets and the account credit balance continue to limit spending.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"budget_id","in":"path"}],"responses":{"204":{"description":"Budget removed"},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/account/usage":{"get":{"operationId":"getAccountUsageOverview","tags":["Account usage"],"summary":"Get account usage overview","description":"Return all tracked resource usage buckets for the authenticated account.","responses":{"200":{"description":"Account usage overview details.","content":{"application/json":{"schema":{"type":"object","properties":{"storage":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"bandwidth":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"api_calls":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"custom_domains":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"code_exports":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"veryfront_badge":{"type":"object","properties":{"used":{"type":"number","description":"Current usage amount."},"total":{"type":"number","description":"Maximum allowed total. A value of -1 means unlimited."},"remaining":{"type":"number","description":"Remaining amount available."},"percent_used":{"type":"number","description":"Percentage of quota used from 0 to 100."}},"required":["used","total","remaining","percent_used"]},"period_start":{"type":"string","description":"ISO timestamp for the start of the current billing period."},"period_end":{"type":"string","description":"ISO timestamp for the end of the current billing period."}},"required":["storage","bandwidth","api_calls","custom_domains","code_exports","veryfront_badge","period_start","period_end"]}}}},"401":{"description":"Unauthorized."},"500":{"description":"Server error."}}}},"/account/usage/credits":{"get":{"operationId":"getAccountAiCreditsUsage","tags":["Account usage"],"summary":"Get account AI credits usage","description":"Returns AI credit usage for the authenticated account by day and project. Optionally scoped to a single project.","parameters":[{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Relative timeframe preset."},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA timezone for daily bucket boundaries."},"required":false,"name":"timezone","in":"query"},{"schema":{"type":"string","description":"Optional project UUID or slug to scope credit usage to a single project."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"Account AI credits usage statistics.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"credits_used":{"type":"number","description":"Total credits used."},"requests":{"type":"number","description":"Total AI requests."},"input_tokens":{"type":"number","description":"Total input tokens."},"output_tokens":{"type":"number","description":"Total output tokens."},"cache_creation_input_tokens":{"type":"number","description":"Total cache creation input tokens."},"cache_read_input_tokens":{"type":"number","description":"Total cache read input tokens."}},"required":["credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]},"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Usage aggregation granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of buckets returned."}},"required":["from","to","granularity","timezone","bucket_count"]},"series":{"type":"array","items":{"type":"object","properties":{"bucket_start":{"type":"string","description":"Bucket start timestamp."},"credits_used":{"type":"number","description":"Credits used in the bucket."},"requests":{"type":"number","description":"AI requests in the bucket."},"input_tokens":{"type":"number","description":"Input tokens in the bucket."},"output_tokens":{"type":"number","description":"Output tokens in the bucket."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens in the bucket."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens in the bucket."},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"credits_used":{"type":"number","description":"Credits used by this project."},"requests":{"type":"number","description":"AI requests billed to this project."},"input_tokens":{"type":"number","description":"Input tokens billed to this project."},"output_tokens":{"type":"number","description":"Output tokens billed to this project."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this project."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this project."}},"required":["project_id","project_name","project_slug","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}}},"required":["bucket_start","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","projects"]}},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"credits_used":{"type":"number","description":"Credits used by this project."},"requests":{"type":"number","description":"AI requests billed to this project."},"input_tokens":{"type":"number","description":"Input tokens billed to this project."},"output_tokens":{"type":"number","description":"Output tokens billed to this project."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this project."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this project."}},"required":["project_id","project_name","project_slug","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}},"models":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string","description":"Canonical or normalized AI model identifier."},"canonical_model_id":{"type":"string","description":"Canonical catalog model identifier."},"model_provider":{"type":"string","description":"Model vendor id. Known values: `anthropic`, `openai`, `google`, `mistral`, `moonshotai`, `deepseek`, `qwen`, `zai`, `unknown`. Other vendor ids may appear; clients must accept any string.","example":"anthropic"},"inference_provider":{"type":"string","description":"Inference provider handling the request. Known values: `veryfront-cloud`, `unknown`. Other values may appear; clients must accept any string.","example":"veryfront-cloud"},"credits_used":{"type":"number","description":"Credits used by this model."},"requests":{"type":"number","description":"AI requests billed to this model."},"input_tokens":{"type":"number","description":"Input tokens billed to this model."},"output_tokens":{"type":"number","description":"Output tokens billed to this model."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this model."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this model."},"provider_cost_usd":{"type":"number","description":"Model provider cost in USD for this model."},"veryfront_charge_usd":{"type":"number","description":"Veryfront charge in USD for this model."},"cost_attribution":{"type":"string","enum":["estimated"],"description":"Present when historical cost attribution was recovered from persisted credits."}},"required":["model","model_provider","inference_provider","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}},"serving":{"type":"array","items":{"type":"object","properties":{"host":{"type":["string","null"],"description":"Catalog ID of the deployment host, not a provider hostname or URL. Null means no deployment was recorded, including older usage, calls without a catalog deployment, and aggregated channel usage. Null does not indicate where inference ran."},"tier":{"type":["string","null"],"description":"Sovereignty tier as a catalog ID. Clients must accept unknown values as tiers can be added. Null means no tier was recorded and does not indicate where inference ran. The API does not infer a tier from billing or other fields.","example":"eu-resident"},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["host","tier","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]},"description":"The same spend cut by the deployment that served it. Ordered by spend descending, then by request count descending, then by host, then by tier; the row whose `host` and `tier` are both null is always last, because it is the absence of a record rather than a deployment. Additive: it neither replaces nor re-slices any other field. Omitted where the serving breakdown is not enabled; `models` is unchanged by it."}},"required":["summary","timeframe","series","projects","models"]}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."},"403":{"description":"Access denied to the requested project."},"404":{"description":"Project not found."},"500":{"description":"Server error."}}}},"/account/usage/limits":{"get":{"operationId":"getAccountUsageLimits","tags":["Account usage"],"summary":"Get account usage limits","description":"Return resource quota limits for the authenticated account subscription tier.","responses":{"200":{"description":"Account usage limits for the current tier.","content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","description":"Current subscription tier name."},"limits":{"type":"object","properties":{"storage":{"type":"number","description":"Storage quota in bytes for the current tier."},"bandwidth":{"type":"number","description":"Bandwidth quota in bytes for the current tier."},"api_calls":{"type":"number","description":"API call quota per month for the current tier."},"custom_domains":{"type":"number","description":"Custom domain quota for the current tier."},"code_exports":{"type":"number","description":"Code export quota for the current tier."},"veryfront_badge":{"type":"number","description":"Veryfront badge requirement/quota for the current tier."}},"required":["storage","bandwidth","api_calls","custom_domains","code_exports","veryfront_badge"]}},"required":["tier","limits"]}}}},"401":{"description":"Unauthorized."},"500":{"description":"Server error."}}}},"/account/usage/series":{"get":{"operationId":"getAccountUsageSeries","tags":["Account usage"],"summary":"Get account usage series","description":"Returns a daily usage series for credits or another tracked account resource metric. Optionally scoped to a single project.","parameters":[{"schema":{"type":"string","enum":["credits","storage","bandwidth","api_calls"],"default":"credits","description":"Usage metric to chart."},"required":false,"name":"metric","in":"query"},{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Relative timeframe preset."},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA timezone for daily bucket boundaries."},"required":false,"name":"timezone","in":"query"},{"schema":{"type":"string","description":"Optional project UUID or slug to scope the usage series to a single project."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"Account usage series statistics.","content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string","enum":["credits","storage","bandwidth","api_calls"],"description":"Usage metric represented by this series."},"label":{"type":"string","description":"Human-readable metric label."},"unit":{"type":"string","description":"Unit used by values, such as credits, calls, or bytes."},"summary":{"type":"object","properties":{"value":{"type":"number","description":"Total usage value over the returned timeframe."}},"required":["value"]},"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Usage aggregation granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of buckets returned."}},"required":["from","to","granularity","timezone","bucket_count"]},"series":{"type":"array","items":{"type":"object","properties":{"bucket_start":{"type":"string","description":"Bucket start timestamp."},"value":{"type":"number","description":"Usage value in the bucket."},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"value":{"type":"number","description":"Usage value for this project."}},"required":["project_id","project_name","project_slug","value"]}}},"required":["bucket_start","value","projects"]}},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"value":{"type":"number","description":"Usage value for this project."}},"required":["project_id","project_name","project_slug","value"]}}},"required":["metric","label","unit","summary","timeframe","series","projects"]}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."},"403":{"description":"Access denied to the requested project."},"404":{"description":"Project not found."},"500":{"description":"Server error."}}}},"/account/usage/warnings":{"get":{"operationId":"getAccountUsageWarnings","tags":["Account usage"],"summary":"Get account usage warnings","description":"Return account usage warnings, optionally scoped to a project.","parameters":[{"schema":{"type":"string","description":"Optional project UUID or slug to evaluate project-specific usage warnings."},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","description":"Deprecated camelCase project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"List of account usage warning messages.","content":{"application/json":{"schema":{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"string"},"description":"Human-readable usage warning messages."}},"required":["warnings"]}}}},"401":{"description":"Unauthorized."},"403":{"description":"Access denied to the requested project."},"404":{"description":"Project not found."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/members/usage":{"get":{"operationId":"getProjectMembersUsage","tags":["Project usage"],"summary":"Get project member usage","description":"Returns AI spending by project member. Webhook and channel-bot usage without a person appears in an `Automations` row. Project owners and administrators can read all members; other members can read only their own usage.\n\n`serving` groups the same spending by deployment host and sovereignty tier. Null values mean the deployment was not recorded, not that inference ran in a particular location.\n\nUsage comes directly from the AI usage ledger. `usd` is the customer charge for credits at the credit rate; it does not expose provider cost.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Relative timeframe preset, counted in whole days of the requested timezone."},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA time zone for daily bucket boundaries, such as `Europe/Berlin`. Numeric UTC offsets are not accepted."},"required":false,"name":"timezone","in":"query"}],"responses":{"200":{"description":"Project member usage rows","content":{"application/json":{"schema":{"type":"object","properties":{"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Bucket granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of daily buckets in the timeframe."}},"required":["from","to","granularity","timezone","bucket_count"]},"attribution":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the ledger is recording who caused each call right now."},"recording_since":{"type":["string","null"],"description":"Time when the project first recorded caller attribution, or null if it never has. Recording can pause after this time. Usage recorded without attribution, including during deployment or while attribution is disabled, appears in an `unattributed` row even if a person or API key caused it."}},"required":["enabled","recording_since"],"description":"Whether attribution is complete for the returned usage. Treat it as incomplete if `enabled` is false, `recording_since` is null, or the selected period includes an `unattributed` row."},"summary":{"type":"object","properties":{"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"],"description":"Sum of the rows below."},"members":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["member","former_member","deleted_users","automations","unattributed"],"description":"Usage row type. `automations` groups webhook and channel-bot usage without a person. `deleted_users` groups usage by deleted accounts. `unattributed` groups usage recorded without caller attribution and does not imply that no person caused it. These rows have `user_id: null`; use this field to distinguish them."},"user_id":{"type":["string","null"],"format":"uuid","description":"Null on the \"Automations\" and \"Deleted users\" rows, which stand for no single person."},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"role":{"type":["string","null"],"description":"Null when the spender is no longer a member of the project."},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["kind","user_id","name","email","role","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]}},"serving":{"type":"array","items":{"type":"object","properties":{"host":{"type":["string","null"],"description":"Catalog ID of the deployment host, not a provider hostname or URL. Null means no deployment was recorded, including older usage, calls without a catalog deployment, and aggregated channel usage. Null does not indicate where inference ran."},"tier":{"type":["string","null"],"description":"Sovereignty tier as a catalog ID. Clients must accept unknown values as tiers can be added. Null means no tier was recorded and does not indicate where inference ran. The API does not infer a tier from billing or other fields.","example":"eu-resident"},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["host","tier","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]},"description":"The same spend cut by the deployment that served it. Ordered by spend descending, then by request count descending, then by host, then by tier; the row whose `host` and `tier` are both null is always last, because it is the absence of a record rather than a deployment. Additive: it neither replaces nor re-slices any other field."}},"required":["timeframe","attribution","summary","members","serving"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/usage":{"get":{"operationId":"getProjectUsage","tags":["Project usage"],"summary":"Get project usage","description":"Returns the project owner’s account-wide usage for the current billing period. These values are not limited to the selected project.\n\nRequires the project owner acting as an account principal with `project.settings.manage`. Other project members, API keys, and service accounts are rejected, including credentials owned by the project owner.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Project resource usage retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUsage"},"example":{"storage":{"used":5368709120,"total":10737418240,"remaining":5368709120,"percent_used":50},"bandwidth":{"used":21474836480,"total":107374182400,"remaining":85899345920,"percent_used":20},"api_calls":{"used":12500,"total":100000,"remaining":87500,"percent_used":12.5},"custom_domains":{"used":2,"total":10,"remaining":8,"percent_used":20},"code_exports":{"used":1,"total":-1,"remaining":-1,"percent_used":0},"veryfront_badge":{"used":0,"total":1,"remaining":1,"percent_used":0},"period_start":"2026-09-01T00:00:00.000Z","period_end":"2026-10-01T00:00:00.000Z","scope":"account"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{project_reference}/analytics/ai-usage":{"get":{"operationId":"getProjectAiUsageAnalytics","tags":["Project usage"],"summary":"Get project AI usage analytics","description":"Return project AI usage and daily customer charges. Owners and administrators can read the project or select a member. Other members can read only their own usage by supplying their member ID. API keys are refused. Member reports include calls with recorded actor attribution. Account quotas and provider costs are excluded.","parameters":[{"$ref":"#/components/parameters/ProjectReference"},{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","minLength":1,"default":"UTC"},"required":false,"name":"timezone","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Optional current project member UUID."},"required":false,"name":"member_id","in":"query"}],"responses":{"200":{"description":"Project or member daily AI usage.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"credits_used":{"type":"number","description":"Total credits used."},"requests":{"type":"number","description":"Total AI requests."},"input_tokens":{"type":"number","description":"Total input tokens."},"output_tokens":{"type":"number","description":"Total output tokens."},"cache_creation_input_tokens":{"type":"number","description":"Total cache creation input tokens."},"cache_read_input_tokens":{"type":"number","description":"Total cache read input tokens."},"usd":{"type":"number"}},"required":["credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","usd"]},"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Usage aggregation granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of buckets returned."}},"required":["from","to","granularity","timezone","bucket_count"]},"series":{"type":"array","items":{"type":"object","properties":{"bucket_start":{"type":"string","description":"Bucket start timestamp."},"credits_used":{"type":"number","description":"Credits used in the bucket."},"requests":{"type":"number","description":"AI requests in the bucket."},"input_tokens":{"type":"number","description":"Input tokens in the bucket."},"output_tokens":{"type":"number","description":"Output tokens in the bucket."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens in the bucket."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens in the bucket."},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"credits_used":{"type":"number","description":"Credits used by this project."},"requests":{"type":"number","description":"AI requests billed to this project."},"input_tokens":{"type":"number","description":"Input tokens billed to this project."},"output_tokens":{"type":"number","description":"Output tokens billed to this project."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this project."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this project."}},"required":["project_id","project_name","project_slug","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}},"usd":{"type":"number"}},"required":["bucket_start","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","projects","usd"]}},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":["string","null"],"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":["string","null"],"description":"Project slug, or null when unavailable."},"credits_used":{"type":"number","description":"Credits used by this project."},"requests":{"type":"number","description":"AI requests billed to this project."},"input_tokens":{"type":"number","description":"Input tokens billed to this project."},"output_tokens":{"type":"number","description":"Output tokens billed to this project."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this project."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this project."}},"required":["project_id","project_name","project_slug","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}},"models":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string","description":"Canonical or normalized AI model identifier."},"canonical_model_id":{"type":"string","description":"Canonical catalog model identifier."},"model_provider":{"type":"string","description":"Model vendor id. Known values: `anthropic`, `openai`, `google`, `mistral`, `moonshotai`, `deepseek`, `qwen`, `zai`, `unknown`. Other vendor ids may appear; clients must accept any string.","example":"anthropic"},"inference_provider":{"type":"string","description":"Inference provider handling the request. Known values: `veryfront-cloud`, `unknown`. Other values may appear; clients must accept any string.","example":"veryfront-cloud"},"credits_used":{"type":"number","description":"Credits used by this model."},"requests":{"type":"number","description":"AI requests billed to this model."},"input_tokens":{"type":"number","description":"Input tokens billed to this model."},"output_tokens":{"type":"number","description":"Output tokens billed to this model."},"cache_creation_input_tokens":{"type":"number","description":"Cache creation input tokens billed to this model."},"cache_read_input_tokens":{"type":"number","description":"Cache read input tokens billed to this model."},"provider_cost_usd":{"type":"number","description":"Model provider cost in USD for this model."},"veryfront_charge_usd":{"type":"number","description":"Veryfront charge in USD for this model."},"cost_attribution":{"type":"string","enum":["estimated"],"description":"Present when historical cost attribution was recovered from persisted credits."}},"required":["model","model_provider","inference_provider","credits_used","requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens"]}},"serving":{"type":"array","items":{"type":"object","properties":{"host":{"type":["string","null"],"description":"Catalog ID of the deployment host, not a provider hostname or URL. Null means no deployment was recorded, including older usage, calls without a catalog deployment, and aggregated channel usage. Null does not indicate where inference ran."},"tier":{"type":["string","null"],"description":"Sovereignty tier as a catalog ID. Clients must accept unknown values as tiers can be added. Null means no tier was recorded and does not indicate where inference ran. The API does not infer a tier from billing or other fields.","example":"eu-resident"},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["host","tier","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]},"description":"The same spend cut by the deployment that served it. Ordered by spend descending, then by request count descending, then by host, then by tier; the row whose `host` and `tier` are both null is always last, because it is the absence of a record rather than a deployment. Additive: it neither replaces nor re-slices any other field. Omitted where the serving breakdown is not enabled; `models` is unchanged by it."},"scope":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"member_id":{"type":["string","null"],"format":"uuid"}},"required":["project_id","member_id"]},"attribution":{"type":"object","properties":{"enabled":{"type":"boolean"},"recording_since":{"type":["string","null"]}},"required":["enabled","recording_since"]}},"required":["summary","timeframe","series","projects","models","scope","attribution"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api-keys/usage":{"get":{"operationId":"listApiKeysUsage","tags":["API key usage"],"summary":"List API key usage","description":"Returns AI spending by API key. Use `kind` to distinguish individual keys from grouped usage, including requests without API key authentication.\n\nWith `project_reference`, returns usage for the project’s keys and requests without a key. Without it, returns the caller’s own keys and requests without a key. Project listings also include usage from deleted key records. Account listings cannot recover that usage after the record identifying the key’s owner is deleted.\n\nUsage comes directly from the AI usage ledger. `usd` is the customer charge for credits at the credit rate; it does not expose provider cost.","parameters":[{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Relative timeframe preset, counted in whole days of the requested timezone."},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA time zone for daily bucket boundaries, such as `Europe/Berlin`. Numeric UTC offsets are not accepted."},"required":false,"name":"timezone","in":"query"},{"schema":{"type":"string","description":"Optional project UUID or slug. Scopes the listing to that project’s keys."},"required":false,"name":"project_reference","in":"query"}],"responses":{"200":{"description":"API key usage rows","content":{"application/json":{"schema":{"type":"object","properties":{"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Bucket granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of daily buckets in the timeframe."}},"required":["from","to","granularity","timezone","bucket_count"]},"attribution":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the ledger is recording who caused each call right now."},"recording_since":{"type":["string","null"],"description":"Time when the project first recorded caller attribution, or null if it never has. Recording can pause after this time. Usage recorded without attribution, including during deployment or while attribution is disabled, appears in an `unattributed` row even if a person or API key caused it."}},"required":["enabled","recording_since"],"description":"Whether attribution is complete for the returned usage. Treat it as incomplete if `enabled` is false, `recording_since` is null, or the selected period includes an `unattributed` row."},"summary":{"type":"object","properties":{"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"],"description":"Sum of the rows below."},"keys":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["api_key","no_api_key","other_keys","deleted_keys","unattributed"],"description":"Usage row type. `api_key` identifies one key. `no_api_key` groups usage without key authentication. `other_keys` groups usage from keys outside the listing, such as account-wide keys or newly created project keys. `deleted_keys` groups usage whose key record was removed when its creator was deleted. `unattributed` groups usage recorded without caller attribution and does not imply that no key caused it. Grouped rows have `api_key_id: null`; use this field to distinguish them."},"api_key_id":{"type":["string","null"],"format":"uuid","description":"Null on every bucket row, none of which stands for a single key."},"name":{"type":"string"},"key_prefix":{"type":["string","null"]},"project_id":{"type":["string","null"],"format":"uuid"},"revoked":{"type":"boolean"},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["kind","api_key_id","name","key_prefix","project_id","revoked","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]}}},"required":["timeframe","attribution","summary","keys"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api-keys/{id}/usage":{"get":{"operationId":"getApiKeyUsage","tags":["API key usage"],"summary":"Get API key usage","description":"Returns AI spending for one API key, including totals, daily usage, model breakdowns, and deployment breakdowns.\n\n`serving` identifies the catalog host and sovereignty tier when recorded. Null values mean no deployment was recorded; they do not indicate where inference ran.\n\nUsage comes directly from the AI usage ledger. `usd` is the customer charge for credits at the credit rate; it does not expose provider cost.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Relative timeframe preset, counted in whole days of the requested timezone."},"required":false,"name":"preset","in":"query"},{"schema":{"type":"string","default":"UTC","description":"IANA time zone for daily bucket boundaries, such as `Europe/Berlin`. Numeric UTC offsets are not accepted."},"required":false,"name":"timezone","in":"query"}],"responses":{"200":{"description":"API key usage statistics","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the ledger is recording who caused each call right now."},"recording_since":{"type":["string","null"],"description":"Time when the project first recorded caller attribution, or null if it never has. Recording can pause after this time. Usage recorded without attribution, including during deployment or while attribution is disabled, appears in an `unattributed` row even if a person or API key caused it."}},"required":["enabled","recording_since"],"description":"Whether attribution is complete for the returned usage. Treat it as incomplete if `enabled` is false, `recording_since` is null, or the selected period includes an `unattributed` row."},"api_key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"},"project_id":{"type":["string","null"],"format":"uuid"},"revoked":{"type":"boolean"}},"required":["id","name","key_prefix","project_id","revoked"]},"timeframe":{"type":"object","properties":{"from":{"type":"string","description":"Inclusive timeframe start timestamp."},"to":{"type":"string","description":"Exclusive timeframe end timestamp."},"granularity":{"type":"string","enum":["day"],"description":"Bucket granularity."},"timezone":{"type":"string","description":"IANA timezone used for buckets."},"bucket_count":{"type":"number","description":"Number of daily buckets in the timeframe."}},"required":["from","to","granularity","timezone","bucket_count"]},"summary":{"type":"object","properties":{"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]},"series":{"type":"array","items":{"type":"object","properties":{"bucket_start":{"type":"string","description":"UTC timestamp of the start of the local day."},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["bucket_start","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]}},"models":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"canonical_model_id":{"type":["string","null"]},"provider":{"type":"string"},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["model","canonical_model_id","provider","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]}},"serving":{"type":"array","items":{"type":"object","properties":{"host":{"type":["string","null"],"description":"Catalog ID of the deployment host, not a provider hostname or URL. Null means no deployment was recorded, including older usage, calls without a catalog deployment, and aggregated channel usage. Null does not indicate where inference ran."},"tier":{"type":["string","null"],"description":"Sovereignty tier as a catalog ID. Clients must accept unknown values as tiers can be added. Null means no tier was recorded and does not indicate where inference ran. The API does not infer a tier from billing or other fields.","example":"eu-resident"},"credits":{"type":"number","description":"Credits debited in the timeframe."},"usd":{"type":"number","description":"Customer-billed USD for those credits."},"requests":{"type":"number","description":"Number of provider calls recorded."},"input_tokens":{"type":"number","description":"Input tokens."},"output_tokens":{"type":"number","description":"Output tokens."},"cache_read_tokens":{"type":"number","description":"Tokens read from the prompt cache."},"cache_creation_tokens":{"type":"number","description":"Tokens written to the prompt cache."}},"required":["host","tier","credits","usd","requests","input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens"]},"description":"The same spend cut by the deployment that served it. Ordered by spend descending, then by request count descending, then by host, then by tier; the row whose `host` and `tier` are both null is always last, because it is the absence of a record rather than a deployment. Additive: it neither replaces nor re-slices any other field."}},"required":["attribution","api_key","timeframe","summary","series","models","serving"]}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api-keys/{id}/limits":{"get":{"operationId":"getApiKeyInferenceLimits","tags":["API key usage"],"summary":"Get API key inference limits","description":"Returns model and request-rate limits for a project-bound API key. `effective_allowed_models` accounts for the project’s inference policy. If no limits are configured, returns `configured: false` with null limits.\n\nRequires `project.api_keys.read` on the key’s project. Account-wide keys return `400` because only project-bound keys support these limits.\n\nThe gateway applies stored limits only when `enforced` is true.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The key's inference limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyInferenceLimits"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"operationId":"replaceApiKeyInferenceLimits","tags":["API key usage"],"summary":"Replace API key inference limits","description":"Replaces all inference limits for a project-bound API key. Omitted limits are removed.\n\n`allowed_models` accepts catalog IDs and stores their canonical values. Models excluded by the project policy can be stored, but are excluded from `effective_allowed_models` and rejected at request time. Key limits cannot broaden the project policy.\n\nRequires a signed-in user with `project.api_keys.manage` on the project: an administrator or owner. API keys, service accounts, and agent runs are rejected regardless of their scopes. The API audits the change with the caller’s identity.\n\nThe gateway applies stored limits only when `enforced` is true.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceApiKeyInferenceLimitsRequest"}}}},"responses":{"200":{"description":"The key's inference limits as they now stand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyInferenceLimits"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"clearApiKeyInferenceLimits","tags":["API key usage"],"summary":"Clear API key inference limits","description":"Removes all inference limits from a project-bound API key. Project policy and budgets still apply. If the key has no limits, the request succeeds without a change.\n\nRequires a signed-in user with `project.api_keys.manage` on the project. The API audits the removal with the caller’s identity.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"The key carries no inference limits"},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/gates/{gate}":{"get":{"operationId":"checkGateAccess","tags":["Feature gates"],"summary":"Check gate access","description":"Checks a user or project-owner feature gate. Project-owner checks require project read access.","parameters":[{"schema":{"type":"string","description":"Gate name such as custom_domains, code_export, collaborators, or projects"},"required":true,"name":"gate","in":"path"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Current resource count in camelCase form","example":2},"required":false,"name":"currentCount","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Current resource count in snake_case form","example":2},"required":false,"name":"current_count","in":"query"},{"schema":{"type":"string","description":"Project UUID or slug for project-scoped gates"},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"projectId","in":"query"},{"schema":{"type":"string","description":"Deprecated project ID or slug alias. Use project_reference."},"required":false,"name":"project_id","in":"query"}],"responses":{"200":{"description":"Gate check result","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean","description":"Whether the authenticated user can access the gate"},"requiredTier":{"type":"string","description":"Tier required when access is denied"},"limit":{"type":"number","description":"Numeric limit for count-based gates"},"currentCount":{"type":"number","description":"Current count considered for count-based gates"}},"required":["allowed"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/mcp/tools":{"get":{"operationId":"listPublicMcpTools","tags":["MCP discovery"],"summary":"List public MCP tools","description":"List public MCP tool summaries for anonymous browsing.","responses":{"200":{"description":"Public MCP tool browse summaries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"legacyName":{"type":"string","description":"Stable platform selector accepted by older clients and APIs."},"canonicalName":{"type":"string","description":"Canonical tool identity. Legacy selectors remain accepted for agent tool_ids. Runtime-only tools still require the project-agent runtime."},"type":{"type":"string","enum":["platform","integration","project"]},"category":{"type":"string"},"description":{"type":"string"},"availability":{"type":"object","properties":{"kind":{"type":"string","enum":["always_available","requires_project_integration","requires_user_connection"]},"integration":{"type":"string"}},"required":["kind"]},"riskLevel":{"type":"string","enum":["read_only","mutating","credential_bearing"]},"href":{"type":"string"},"hasOutputSchema":{"type":"boolean"},"attachVia":{"type":["string","null"],"enum":["tool_ids",null]}},"required":["name","canonicalName","type","category","description","availability","riskLevel","href","hasOutputSchema","attachVia"]}},"generatedAt":{"type":"string"}},"required":["data","generatedAt"]}}}}}}},"/mcp/tools/{tool_name}":{"get":{"operationId":"getPublicMcpToolDetail","tags":["MCP discovery"],"summary":"Get public MCP tool detail","description":"Return public MCP metadata and schemas for one tool.","security":[],"parameters":[{"schema":{"type":"string"},"required":true,"name":"tool_name","in":"path"}],"responses":{"200":{"description":"Public MCP tool detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"legacyName":{"type":"string","description":"Stable platform selector accepted by older clients and APIs."},"canonicalName":{"type":"string","description":"Canonical tool identity. Legacy selectors remain accepted for agent tool_ids. Runtime-only tools still require the project-agent runtime."},"type":{"type":"string","enum":["platform","integration","project"]},"category":{"type":"string"},"description":{"type":"string"},"inputSchema":{},"outputSchema":{},"availability":{"type":"object","properties":{"kind":{"type":"string","enum":["always_available","requires_project_integration","requires_user_connection"]},"integration":{"type":"string"}},"required":["kind"]},"riskLevel":{"type":"string","enum":["read_only","mutating","credential_bearing"]}},"required":["name","canonicalName","type","category","description","availability","riskLevel"]},"generatedAt":{"type":"string"}},"required":["data","generatedAt"]}}}},"404":{"description":"MCP tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/mcp/playground":{"get":{"operationId":"openMcpPlayground","tags":["MCP discovery"],"summary":"Open MCP playground","description":"Serves the browser-based MCP tool playground.","security":[],"responses":{"200":{"description":"MCP playground HTML.","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/mcp/catalog":{"get":{"operationId":"listPublicMcpCatalog","tags":["MCP discovery"],"summary":"List public MCP catalog (deprecated alias)","description":"Deprecated compatibility alias for the full public MCP catalog. Browse with [`GET /mcp/tools`](https://veryfront.com/docs/cloud/rest/api-reference/mcp-discovery/list-public-mcp-tools) and read full schemas with [`GET /mcp/tools/{tool_name}`](https://veryfront.com/docs/cloud/rest/api-reference/mcp-discovery/get-public-mcp-tool-detail). No removal date is scheduled.","deprecated":true,"x-deprecation":{"register_id":"CR-rest-mcp-catalog-alias","deprecated_at":"2026-09-11","replacement":"GET /mcp/tools for the browse listing, then GET /mcp/tools/{tool_name} for the full per-tool schemas.","rollout_state":"announced","old_semantics":"Returns the full public MCP tool catalog — every public tool with its input and output schemas — in one anonymous response. Body shape, tool naming and ordering stay unchanged until removal.","documentation":"https://github.com/veryfront/veryfront-api/blob/main/docs/reference/api-surface-inventory.md"},"responses":{"200":{"description":"Public MCP tool catalog","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"legacyName":{"type":"string","description":"Stable platform selector accepted by older clients and APIs."},"canonicalName":{"type":"string","description":"Canonical tool identity. Legacy selectors remain accepted for agent tool_ids. Runtime-only tools still require the project-agent runtime."},"type":{"type":"string","enum":["platform","integration","project"]},"category":{"type":"string"},"description":{"type":"string"},"inputSchema":{},"outputSchema":{},"availability":{"type":"object","properties":{"kind":{"type":"string","enum":["always_available","requires_project_integration","requires_user_connection"]},"integration":{"type":"string"}},"required":["kind"]},"riskLevel":{"type":"string","enum":["read_only","mutating","credential_bearing"]}},"required":["name","canonicalName","type","category","description","availability","riskLevel"]}},"generatedAt":{"type":"string"}},"required":["data","generatedAt"]}}}}}}},"/errors":{"get":{"operationId":"listErrorTypes","tags":["Error metadata"],"summary":"List error types","description":"Return all known API error types with their slug, title, HTTP status, and category.","responses":{"200":{"description":"List of error types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListErrorsResponse"}}}}}}},"/errors/{slug}":{"get":{"operationId":"getErrorTypeBySlug","tags":["Error metadata"],"summary":"Get error type by slug","description":"Returns JSON error details including solution steps and related errors. Redirects when Accept contains text/html but not application/json; media-range quality values are not parsed. RFC 9457 type URIs resolve here.","parameters":[{"schema":{"type":"string","description":"Error slug identifier","example":"insufficient-credits"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Error type details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDetail"}}}},"302":{"description":"Redirect when Accept contains text/html but not application/json","headers":{"Location":{"description":"URL of the error documentation.","schema":{"type":"string","format":"uri"}}}},"404":{"description":"Error type not found"}}}}},"webhooks":{},"tags":[{"name":"Agents API","description":"Define agents, tasks and workflows, and configure their prompts, skills, tools and resources.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Accessible agents](#tag/accessible-agents) | List agents you can access across projects. Each result includes the project needed to locate its definition. |\n| [Agent templates](#tag/agent-templates) | Browse agent templates. Use [agent installation](#tag/agent-installation) to add a selected template. |\n| [Project agents](#tag/project-agents) | Configure agent definitions, capabilities, labels, avatars, and installations. Use the [run endpoints](#tag/runs-api) to start and monitor agent runs. |\n| [Agent Capabilities](#tag/agent-capabilities) | Read project capabilities and the capabilities enabled for an agent. |\n| [Agent Tool References](#tag/agent-tool-references) | Search tools that can be attached to agents. |\n| [Agent Labels](#tag/agent-labels) | List, create, update, or delete labels on an agent. |\n| [Agent Avatars](#tag/agent-avatars) | Preview, generate, or read agent avatars. |\n| [Agent Installation](#tag/agent-installation) | Install or remove agents from selected projects. |\n| [Project prompts](#tag/project-prompts) | Manage prompts stored in project source. List prompts, read their source, and edit supported fields for the selected source version. |\n| [Project skills](#tag/project-skills) | Manage skills stored in project source. List skills, read their source, and edit the fields supported by the selected source and definition format. |\n| [Project tools](#tag/project-tools) | Manage tool definitions in project source. Use [integration tool endpoints](#tag/integration-tools) to discover and invoke connected-service tools. |\n| [Project tasks](#tag/project-tasks) | Manage task definitions stored in project source. List definitions, read their source, and edit supported fields. To start a task run, use [`POST /runs`](#tag/run-resource/POST/runs) with `project_id` and `target: { type: \"task\", id }`. |\n| [Project workflows](#tag/project-workflows) | Manage workflow definitions stored in project source. List definitions, read their source, and edit supported fields. To start a workflow run, use [`POST /runs`](#tag/run-resource/POST/runs) with `project_id` and `target: { type: \"workflow\", id }`. |\n| [Project resources](#tag/project-resources) | Create and edit project resource documents. Manage servers and other deployment infrastructure through the [Deployment API](#tag/deployment-api). |"},{"name":"Accessible agents","parent":"Agents API","description":"List agents you can access across projects. Each result includes the project needed to locate its definition."},{"name":"Agent templates","parent":"Agents API","description":"Browse agent templates. Use [agent installation](#tag/agent-installation) to add a selected template."},{"name":"Project agents","parent":"Agents API","description":"Configure agent definitions, capabilities, labels, avatars, and installations. Use the [run endpoints](#tag/runs-api) to start and monitor agent runs."},{"name":"Agent Capabilities","parent":"Agents API","description":"Read project capabilities and the capabilities enabled for an agent."},{"name":"Agent Tool References","parent":"Agents API","description":"Search tools that can be attached to agents."},{"name":"Agent Labels","parent":"Agents API","description":"List, create, update, or delete labels on an agent."},{"name":"Agent Avatars","parent":"Agents API","description":"Preview, generate, or read agent avatars."},{"name":"Agent Installation","parent":"Agents API","description":"Install or remove agents from selected projects."},{"name":"Project prompts","parent":"Agents API","description":"Manage prompts stored in project source. List prompts, read their source, and edit supported fields for the selected source version."},{"name":"Project skills","parent":"Agents API","description":"Manage skills stored in project source. List skills, read their source, and edit the fields supported by the selected source and definition format."},{"name":"Project tools","parent":"Agents API","description":"Manage tool definitions in project source. Use [integration tool endpoints](#tag/integration-tools) to discover and invoke connected-service tools."},{"name":"Project tasks","parent":"Agents API","description":"Manage task definitions stored in project source. List definitions, read their source, and edit supported fields. To start a task run, use [`POST /runs`](#tag/run-resource/POST/runs) with `project_id` and `target: { type: \"task\", id }`."},{"name":"Project workflows","parent":"Agents API","description":"Manage workflow definitions stored in project source. List definitions, read their source, and edit supported fields. To start a workflow run, use [`POST /runs`](#tag/run-resource/POST/runs) with `project_id` and `target: { type: \"workflow\", id }`."},{"name":"Project resources","parent":"Agents API","description":"Create and edit project resource documents. Manage servers and other deployment infrastructure through the [Deployment API](#tag/deployment-api)."},{"name":"Execution API","description":"Start and monitor agent, task, and workflow runs.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Runs API](#tag/runs-api) | Start, list, inspect, cancel, and resume agent, task, and workflow runs, follow their events, answer their input requests, and find the runs that schedules, webhooks, and evaluations start. |\n| [Run runtime callbacks](#tag/run-runtime-callbacks) | Acknowledge server-issued cancellation stops and pauses, and read private pause continuations. |\n| [Conversations](#tag/conversations) | Create, read, and edit conversations and inspect their trees. Find a conversation’s runs and the input requests that need a response under [Runs](#tag/runs-api). |\n| [Conversation Messages](#tag/conversation-messages) | List, send, read, edit, or delete messages. |\n| [Conversation Branches](#tag/conversation-branches) | Fork messages and select the active branch. |\n| [Conversation Participants](#tag/conversation-participants) | List, add, or remove participants. |\n| [Conversation Read State](#tag/conversation-read-state) | Read or update conversation read state. |\n| [Participant lookup](#tag/participant-lookup) | Find an existing participant identity by user or agent ID. Use the conversation participant endpoints to [add](#tag/conversation-participants/POST/conversations/{conversation_id}/participants) or [remove](#tag/conversation-participants/DELETE/conversations/{conversation_id}/participants/{user_id}) users. |\n| [Project schedules](#tag/project-schedules) | Configure schedules. To start a run from an existing schedule, use [`POST /runs`](#tag/run-resource/POST/runs) with `project_id` and `source: { type: \"schedule\", id }`. |\n| [Project webhooks](#tag/project-webhooks) | Configure automation webhooks and replay recorded deliveries. Start a webhook run and list its runs under [Runs](#tag/runs-api). |\n| [Webhook delivery](#tag/webhook-delivery) | Receive automation webhook deliveries. Authenticate with the webhook secret and use an idempotency key to identify duplicate deliveries. Manage definitions through [project webhooks](#tag/project-webhooks). |\n| [Agent runtime registration](#tag/agent-runtime-registration) | Register runtime services and manage their availability. Project registrations require `project.runtime.manage`; global registrations require platform administrator access. |\n| [Agent workers](#tag/agent-workers) | Register workers, claim runs, renew leases, and report session state. Project administrators manage workers; worker operations accept credentials scoped to the worker. |"},{"name":"Runs API","parent":"Execution API","description":"Start, list, inspect, cancel, and resume agent, task, and workflow runs, follow their events, answer their input requests, and find the runs that schedules, webhooks, and evaluations start.\n\n34 run operations. Select an endpoint for its full description, request and response schemas, and examples.\n\n### [Runtime compatibility](#tag/runtime-compatibility)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /conversations/{conversation_id}/runs/{run_id}/stream`](#tag/runtime-compatibility/GET/conversations/{conversation_id}/runs/{run_id}/stream) | Stream conversation run events (compatibility) |\n\n### [Run resource](#tag/run-resource)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /runs`](#tag/run-resource/GET/runs) | List runs |\n| [`POST /runs`](#tag/run-resource/POST/runs) | Create run |\n| [`GET /runs/{run_id}`](#tag/run-resource/GET/runs/{run_id}) | Get run |\n| [`PATCH /runs/{run_id}`](#tag/run-resource/PATCH/runs/{run_id}) | Update run |\n| [`DELETE /runs/{run_id}`](#tag/run-resource/DELETE/runs/{run_id}) | Delete run |\n\n### [Run actions](#tag/run-actions)\n\n| Endpoint | Description |\n| --- | --- |\n| [`POST /runs/{run_id}/cancel`](#tag/run-actions/POST/runs/{run_id}/cancel) | Cancel run |\n| [`POST /runs/{run_id}/resume`](#tag/run-actions/POST/runs/{run_id}/resume) | Resume run |\n| [`POST /runs/{run_id}/pause`](#tag/run-actions/POST/runs/{run_id}/pause) | Pause run |\n| [`POST /runs/{run_id}/finalize`](#tag/run-actions/POST/runs/{run_id}/finalize) | Finalize a run |\n| [`POST /runs/{run_id}/succeed`](#tag/run-actions/POST/runs/{run_id}/succeed) | Succeed a run |\n| [`POST /runs/{run_id}/fail`](#tag/run-actions/POST/runs/{run_id}/fail) | Fail a run |\n\n### [Run events](#tag/run-events)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /runs/{run_id}/events`](#tag/run-events/GET/runs/{run_id}/events) | List run events |\n| [`POST /runs/{run_id}/events`](#tag/run-events/POST/runs/{run_id}/events) | Append run events |\n| [`GET /runs/{run_id}/events/{event_id}`](#tag/run-events/GET/runs/{run_id}/events/{event_id}) | Get run event |\n| [`GET /runs/{run_id}/events/summary`](#tag/run-events/GET/runs/{run_id}/events/summary) | Get run event summary |\n| [`GET /runs/{run_id}/snapshot`](#tag/run-events/GET/runs/{run_id}/snapshot) | Get run snapshot |\n| [`GET /runs/{run_id}/stream`](#tag/run-events/GET/runs/{run_id}/stream) | Stream run events |\n| [`GET /runs/event-types`](#tag/run-events/GET/runs/event-types) | List run event types |\n\n### [Child runs](#tag/child-runs)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /runs/{run_id}/child-runs`](#tag/child-runs/GET/runs/{run_id}/child-runs) | List child runs |\n\n### [Run input request](#tag/run-input-request)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /runs/{run_id}/input-requests`](#tag/run-input-request/GET/runs/{run_id}/input-requests) | List run input requests |\n| [`POST /runs/{run_id}/input-requests`](#tag/run-input-request/POST/runs/{run_id}/input-requests) | Create input request |\n\n### [Input request](#tag/input-request)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /input-requests/{input_request_id}`](#tag/input-request/GET/input-requests/{input_request_id}) | Get input request |\n| [`POST /input-requests/{input_request_id}/responses`](#tag/input-request/POST/input-requests/{input_request_id}/responses) | Respond to input request |\n| [`POST /input-requests/{input_request_id}/cancel`](#tag/input-request/POST/input-requests/{input_request_id}/cancel) | Cancel input request |\n\n### [Runtime](#tag/runtime)\n\n| Endpoint | Description |\n| --- | --- |\n| [`POST /runs/{run_id}/heartbeats`](#tag/runtime/POST/runs/{run_id}/heartbeats) | Send run heartbeat |\n| [`POST /runs/{run_id}/event-tokens`](#tag/runtime/POST/runs/{run_id}/event-tokens) | Create run event token |\n\n### [Project runs](#tag/project-runs)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /projects/{project_reference}/runs`](#tag/project-runs/GET/projects/{project_reference}/runs) | List project runs |\n\n### [Webhook runs](#tag/webhook-runs)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /projects/{project_reference}/webhooks/{webhook_definition_id}/runs`](#tag/webhook-runs/GET/projects/{project_reference}/webhooks/{webhook_definition_id}/runs) | List webhook runs |\n\n### [Eval runs](#tag/eval-runs)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /projects/{project_reference}/evals/{eval_id}/runs`](#tag/eval-runs/GET/projects/{project_reference}/evals/{eval_id}/runs) | List evaluation runs |\n\n### [Conversation runs](#tag/conversation-runs)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /conversations/{conversation_id}/runs`](#tag/conversation-runs/GET/conversations/{conversation_id}/runs) | List conversation runs |\n| [`GET /conversations/{conversation_id}/input-requests`](#tag/conversation-runs/GET/conversations/{conversation_id}/input-requests) | List conversation input requests |\n| [`GET /conversations/{conversation_id}/child-runs`](#tag/conversation-runs/GET/conversations/{conversation_id}/child-runs) | List conversation child runs |\n\n### [Account runs](#tag/account-runs)\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /account/analytics/runs`](#tag/account-runs/GET/account/analytics/runs) | Get run analytics |\n\n### Supporting operations\n\nArtifact downloads and event schema discovery supplement the run operations.\n\n| Endpoint | Description |\n| --- | --- |\n| [`GET /runs/{run_id}/artifacts/{artifact_id}`](#tag/run-resource/GET/runs/{run_id}/artifacts/{artifact_id}) | Download a run artifact |\n| [`GET /schemas/run-events/{schema_file}`](#tag/run-events/GET/schemas/run-events/{schema_file}) | Get run event data schema |"},{"name":"Runtime compatibility","parent":"Runs API","description":"Deprecated runtime turn and recovery operations."},{"name":"Run resource","parent":"Runs API","description":"Run resource operations."},{"name":"Run actions","parent":"Runs API","description":"Run actions operations."},{"name":"Run events","parent":"Runs API","description":"Run events operations."},{"name":"Child runs","parent":"Runs API","description":"Child runs operations."},{"name":"Run input request","parent":"Runs API","description":"Run input request operations."},{"name":"Input request","parent":"Runs API","description":"Input request operations."},{"name":"Runtime","parent":"Runs API","description":"Runtime operations."},{"name":"Project runs","parent":"Runs API","description":"Project runs operations."},{"name":"Webhook runs","parent":"Runs API","description":"Webhook runs operations."},{"name":"Eval runs","parent":"Runs API","description":"Eval runs operations."},{"name":"Conversation runs","parent":"Runs API","description":"Conversation runs operations."},{"name":"Account runs","parent":"Runs API","description":"Account runs operations."},{"name":"Run runtime callbacks","parent":"Execution API","description":"**Internal interface.** Acknowledge server-issued cancellation stops and pauses, and read private pause continuations.","x-audience":"component-internal"},{"name":"Conversations","parent":"Execution API","description":"Create, read, and edit conversations and inspect their trees. Find a conversation’s runs and the input requests that need a response under [Runs](#tag/runs-api)."},{"name":"Conversation Messages","parent":"Execution API","description":"List, send, read, edit, or delete messages."},{"name":"Conversation Branches","parent":"Execution API","description":"Fork messages and select the active branch."},{"name":"Conversation Participants","parent":"Execution API","description":"List, add, or remove participants."},{"name":"Conversation Read State","parent":"Execution API","description":"Read or update conversation read state."},{"name":"Participant lookup","parent":"Execution API","description":"Find an existing participant identity by user or agent ID. Use the conversation participant endpoints to [add](#tag/conversation-participants/POST/conversations/{conversation_id}/participants) or [remove](#tag/conversation-participants/DELETE/conversations/{conversation_id}/participants/{user_id}) users."},{"name":"Project schedules","parent":"Execution API","description":"Configure schedules. To start a run from an existing schedule, use [`POST /runs`](#tag/run-resource/POST/runs) with `project_id` and `source: { type: \"schedule\", id }`."},{"name":"Project webhooks","parent":"Execution API","description":"Configure automation webhooks and replay recorded deliveries. Start a webhook run and list its runs under [Runs](#tag/runs-api)."},{"name":"Webhook delivery","parent":"Execution API","description":"**Internal interface.** Receive automation webhook deliveries. Authenticate with the webhook secret and use an idempotency key to identify duplicate deliveries. Manage definitions through [project webhooks](#tag/project-webhooks).","x-audience":"component-internal"},{"name":"Agent runtime registration","parent":"Execution API","description":"**Internal interface.** Register runtime services and manage their availability. Project registrations require `project.runtime.manage`; global registrations require platform administrator access.","x-audience":"component-internal"},{"name":"Agent workers","parent":"Execution API","description":"**Internal interface.** Register workers, claim runs, renew leases, and report session state. Project administrators manage workers; worker operations accept credentials scoped to the worker.","x-audience":"component-internal"},{"name":"Evaluations API","description":"Define agent evaluations, run them, and inspect results.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Evaluation Definitions](#tag/evaluation-definitions) | List and create evaluation definitions stored in project source. Read the source document to inspect its dataset, metrics, and editable fields, then update supported fields. |"},{"name":"Evaluation Definitions","parent":"Evaluations API","description":"List and create evaluation definitions stored in project source. Read the source document to inspect its dataset, metrics, and editable fields, then update supported fields."},{"name":"AI Gateway API","description":"Generate messages, responses, embeddings, and images.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Application Inference](#tag/application-inference) | Host-authenticated admission and finalization for published application inference. These operations are mounted only on the internal host application. |\n| [Model discovery](#tag/model-discovery) | Find available models and inspect their metadata. Provider-compatible model lists are grouped with [inference models](#tag/inference-models). |\n| [Anthropic Messages](#tag/anthropic-messages) | Create Anthropic-compatible messages or count message tokens. |\n| [OpenAI Chat Completions](#tag/openai-chat-completions) | Create OpenAI-compatible chat completions. |\n| [OpenAI Responses](#tag/openai-responses) | Create OpenAI-compatible responses. |\n| [Embeddings](#tag/embeddings) | Create embeddings. |\n| [Inference Models](#tag/inference-models) | List provider-compatible inference models. |\n| [Gemini Models](#tag/gemini-models) | Call Gemini-compatible generateContent methods. |\n| [Image generation](#tag/image-generation) | Generate images from a prompt. Manage generated images through [project upload endpoints](#tag/project-uploads). |\n| [Provider gateway](#tag/provider-gateway) | Use [billing finalization](#tag/provider-gateway/POST/ai/gateway/billing/finalize) when your integration manages gateway billing groups. Inspect spending limits through [budgets](#tag/budgets). |\n| [Project inference policy](#tag/project-inference-policy) | Read, replace, or clear project inference constraints. These endpoints require a signed-in project administrator. Record standard-tier consent through [the opt-in endpoint](#tag/project-inference-policy/POST/projects/{project_reference}/inference-policy/standard-tier-opt-in). |"},{"name":"Application Inference","parent":"AI Gateway API","description":"**Internal interface.** Host-authenticated admission and finalization for published application inference. These operations are mounted only on the internal host application.","x-audience":"component-internal"},{"name":"Model discovery","parent":"AI Gateway API","description":"Find available models and inspect their metadata. Provider-compatible model lists are grouped with [inference models](#tag/inference-models)."},{"name":"Anthropic Messages","parent":"AI Gateway API","description":"Create Anthropic-compatible messages or count message tokens."},{"name":"OpenAI Chat Completions","parent":"AI Gateway API","description":"Create OpenAI-compatible chat completions."},{"name":"OpenAI Responses","parent":"AI Gateway API","description":"Create OpenAI-compatible responses."},{"name":"Embeddings","parent":"AI Gateway API","description":"Create embeddings."},{"name":"Inference Models","parent":"AI Gateway API","description":"List provider-compatible inference models."},{"name":"Gemini Models","parent":"AI Gateway API","description":"Call Gemini-compatible generateContent methods."},{"name":"Image generation","parent":"AI Gateway API","description":"Generate images from a prompt. Manage generated images through [project upload endpoints](#tag/project-uploads)."},{"name":"Provider gateway","parent":"AI Gateway API","description":"Use [billing finalization](#tag/provider-gateway/POST/ai/gateway/billing/finalize) when your integration manages gateway billing groups. Inspect spending limits through [budgets](#tag/budgets)."},{"name":"Project inference policy","parent":"AI Gateway API","description":"Read, replace, or clear project inference constraints. These endpoints require a signed-in project administrator. Record standard-tier consent through [the opt-in endpoint](#tag/project-inference-policy/POST/projects/{project_reference}/inference-policy/standard-tier-opt-in)."},{"name":"Knowledge API","description":"Store document metadata, index file chunks, and search project content.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Project documents](#tag/project-documents) | List, create, or update metadata records in the project’s retrieval-augmented generation (RAG) store. Use [project file endpoints](#tag/project-files) to edit source content. |\n| [File Chunks](#tag/file-chunks) | Read file chunks used for indexing. Create or delete chunks on a branch, or read chunks from a branch, environment, or release. |\n| [Project embeddings](#tag/project-embeddings) | Store and retrieve vectors by chunk ID. Generate vectors through [the embeddings endpoint](#tag/embeddings/POST/ai/v1/embeddings) or your provider before storing them here. |\n| [Vector search](#tag/vector-search) | Search indexed content with an embedding vector. Choose the branch, environment, or release endpoint for the content you need. |\n| [Project knowledge](#tag/project-knowledge) | Search metadata in project knowledge files. Specify a branch, environment, or release to query the required content version. |"},{"name":"Project documents","parent":"Knowledge API","description":"List, create, or update metadata records in the project’s retrieval-augmented generation (RAG) store. Use [project file endpoints](#tag/project-files) to edit source content."},{"name":"File Chunks","parent":"Knowledge API","description":"Read file chunks used for indexing. Create or delete chunks on a branch, or read chunks from a branch, environment, or release."},{"name":"Project embeddings","parent":"Knowledge API","description":"Store and retrieve vectors by chunk ID. Generate vectors through [the embeddings endpoint](#tag/embeddings/POST/ai/v1/embeddings) or your provider before storing them here."},{"name":"Vector search","parent":"Knowledge API","description":"Search indexed content with an embedding vector. Choose the branch, environment, or release endpoint for the content you need."},{"name":"Project knowledge","parent":"Knowledge API","description":"Search metadata in project knowledge files. Specify a branch, environment, or release to query the required content version."},{"name":"Integrations API","description":"Connect external accounts, invoke integration tools, and configure messaging channels.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Integration catalog](#tag/integration-catalog) | Browse integrations and read their metadata, icons, and connection summaries. Configure project-specific settings through the [project integration endpoints](#tag/project-integrations). |\n| [Project integrations](#tag/project-integrations) | Read or update an integration’s project configuration and connection state. Some integrations also expose service-specific metadata, such as Salesforce objects and fields. |\n| [Integration OAuth](#tag/integration-oauth) | Authorize or disconnect an external account. Use [platform authentication](#tag/authentication) to sign in to Veryfront. Inspect connection status and retrieve tokens with the required permissions. |\n| [Connections](#tag/connections) | List connected external accounts across projects you can access. |\n| [Integration tools](#tag/integration-tools) | List tools exposed by connected services and invoke them with the required connection context. Manage source-defined tools through the [Agents API](#tag/project-tools). |\n| [Channel Bindings](#tag/channel-bindings) | List, create, read, update, delete, or test channel bindings. |\n| [Channel Platforms](#tag/channel-platforms) | Read, update, delete, or test platform channel configuration. |\n| [Channel Assistants](#tag/channel-assistants) | List assistants that can receive channel messages. |\n| [Slack Channels](#tag/slack-channels) | List Slack conversations available to a project channel integration. |\n| [Channel delivery](#tag/channel-delivery) | Receive messaging-platform events. Each platform defines its signature verification and binding requirements. Configure bindings through [channel bindings](#tag/channel-bindings). |\n| [Provider Files](#tag/provider-files) | Browse, upload, move, import, or delete provider files. Use [project files](#tag/project-files) for files already stored in a project. |\n| [Provider Folders](#tag/provider-folders) | Create folders through a connected storage provider. |\n| [Provider Search](#tag/provider-search) | Search files through a connected storage provider. |"},{"name":"Integration catalog","parent":"Integrations API","description":"Browse integrations and read their metadata, icons, and connection summaries. Configure project-specific settings through the [project integration endpoints](#tag/project-integrations)."},{"name":"Project integrations","parent":"Integrations API","description":"Read or update an integration’s project configuration and connection state. Some integrations also expose service-specific metadata, such as Salesforce objects and fields."},{"name":"Integration OAuth","parent":"Integrations API","description":"Authorize or disconnect an external account. Use [platform authentication](#tag/authentication) to sign in to Veryfront. Inspect connection status and retrieve tokens with the required permissions."},{"name":"Connections","parent":"Integrations API","description":"List connected external accounts across projects you can access."},{"name":"Integration tools","parent":"Integrations API","description":"List tools exposed by connected services and invoke them with the required connection context. Manage source-defined tools through the [Agents API](#tag/project-tools)."},{"name":"Channel Bindings","parent":"Integrations API","description":"List, create, read, update, delete, or test channel bindings."},{"name":"Channel Platforms","parent":"Integrations API","description":"Read, update, delete, or test platform channel configuration."},{"name":"Channel Assistants","parent":"Integrations API","description":"List assistants that can receive channel messages."},{"name":"Slack Channels","parent":"Integrations API","description":"List Slack conversations available to a project channel integration."},{"name":"Channel delivery","parent":"Integrations API","description":"**Internal interface.** Receive messaging-platform events. Each platform defines its signature verification and binding requirements. Configure bindings through [channel bindings](#tag/channel-bindings).","x-audience":"component-internal"},{"name":"Provider Files","parent":"Integrations API","description":"Browse, upload, move, import, or delete provider files. Use [project files](#tag/project-files) for files already stored in a project."},{"name":"Provider Folders","parent":"Integrations API","description":"Create folders through a connected storage provider."},{"name":"Provider Search","parent":"Integrations API","description":"Search files through a connected storage provider."},{"name":"Projects API","description":"Create projects and manage source files, branches, and uploads.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Projects](#tag/projects) | List, create, read, update, or delete projects. |\n| [Project Labels](#tag/project-labels) | List, create, update, or delete project labels. |\n| [Account Projects](#tag/account-projects) | List or create projects assigned to an account. |\n| [Project Templates](#tag/project-templates) | List or search starter templates before creating a project. |\n| [Project Files](#tag/project-files) | List, read, write, move, delete, diff, or batch-read project files. |\n| [Project File Versions](#tag/project-file-versions) | List or read saved project file versions. |\n| [File search](#tag/file-search) | Search project or branch files by text. Use the [Knowledge API](#tag/vector-search) for vector search. |\n| [Branches](#tag/branches) | Create, read, delete, preview, check, or merge branches. |\n| [Branch Approvals](#tag/branch-approvals) | List, create, or dismiss branch approvals. |\n| [Branch Status Checks](#tag/branch-status-checks) | List or upsert branch status checks. |\n| [Branch Policies](#tag/branch-policies) | List, create, or delete branch policies. |\n| [Project Commits](#tag/project-commits) | Commit project file changes. |\n| [Branch Files](#tag/branch-files) | Read branch files and diffs. |\n| [Branch File Versions](#tag/branch-file-versions) | List or read saved branch file versions. |\n| [Branch File Drafts](#tag/branch-file-drafts) | Read, replace, or discard pending file drafts. |\n| [Environment Files](#tag/environment-files) | Read files and diffs from a named environment. Manage environment settings through [Environments](#tag/environments). |\n| [Release Files](#tag/release-files) | Read files and diffs from a specific release. |\n| [Project Uploads](#tag/project-uploads) | List, upload, read, move, restore, delete, or get download URLs for uploads. |\n| [Upload Folders](#tag/upload-folders) | Create, rename, or delete upload folders. |\n| [Upload Grants](#tag/upload-grants) | List, set, or revoke upload grants. |\n| [Upload Visibility](#tag/upload-visibility) | Set or remove upload path visibility. |\n| [Dependencies](#tag/dependencies) | Resolve and pin project dependencies. Read recent dependency metadata to inspect the recorded configuration. |\n| [Dependency artifacts](#tag/dependency-artifacts) | Look up dependency artifacts, upload build assets, and report build results. These endpoints require a project-scoped runtime token; uploads and results also require authority for the current build attempt. |\n| [Style artifacts](#tag/style-artifacts) | Read or register the current CSS artifact and request its background build. Select the project and style profile in the request. |\n| [Favorites](#tag/favorites) | List, add, or remove favorite projects for the current user. Favorites do not grant project access. |"},{"name":"Projects","parent":"Projects API","description":"List, create, read, update, or delete projects."},{"name":"Project Labels","parent":"Projects API","description":"List, create, update, or delete project labels."},{"name":"Account Projects","parent":"Projects API","description":"List or create projects assigned to an account."},{"name":"Project Templates","parent":"Projects API","description":"List or search starter templates before creating a project."},{"name":"Project Files","parent":"Projects API","description":"List, read, write, move, delete, diff, or batch-read project files."},{"name":"Project File Versions","parent":"Projects API","description":"List or read saved project file versions."},{"name":"File search","parent":"Projects API","description":"Search project or branch files by text. Use the [Knowledge API](#tag/vector-search) for vector search."},{"name":"Branches","parent":"Projects API","description":"Create, read, delete, preview, check, or merge branches."},{"name":"Branch Approvals","parent":"Projects API","description":"List, create, or dismiss branch approvals."},{"name":"Branch Status Checks","parent":"Projects API","description":"List or upsert branch status checks."},{"name":"Branch Policies","parent":"Projects API","description":"List, create, or delete branch policies."},{"name":"Project Commits","parent":"Projects API","description":"Commit project file changes."},{"name":"Branch Files","parent":"Projects API","description":"Read branch files and diffs."},{"name":"Branch File Versions","parent":"Projects API","description":"List or read saved branch file versions."},{"name":"Branch File Drafts","parent":"Projects API","description":"Read, replace, or discard pending file drafts."},{"name":"Environment Files","parent":"Projects API","description":"Read files and diffs from a named environment. Manage environment settings through [Environments](#tag/environments)."},{"name":"Release Files","parent":"Projects API","description":"Read files and diffs from a specific release."},{"name":"Project Uploads","parent":"Projects API","description":"List, upload, read, move, restore, delete, or get download URLs for uploads."},{"name":"Upload Folders","parent":"Projects API","description":"Create, rename, or delete upload folders."},{"name":"Upload Grants","parent":"Projects API","description":"List, set, or revoke upload grants."},{"name":"Upload Visibility","parent":"Projects API","description":"Set or remove upload path visibility."},{"name":"Dependencies","parent":"Projects API","description":"Resolve and pin project dependencies. Read recent dependency metadata to inspect the recorded configuration."},{"name":"Dependency artifacts","parent":"Projects API","description":"**Internal interface.** Look up dependency artifacts, upload build assets, and report build results. These endpoints require a project-scoped runtime token; uploads and results also require authority for the current build attempt.","x-audience":"component-internal"},{"name":"Style artifacts","parent":"Projects API","description":"Read or register the current CSS artifact and request its background build. Select the project and style profile in the request."},{"name":"Favorites","parent":"Projects API","description":"List, add, or remove favorite projects for the current user. Favorites do not grant project access."},{"name":"Deployment API","description":"Create releases and deploy them to project environments.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Releases](#tag/releases) | Create, read, delete, or find project releases. |\n| [Release Versions](#tag/release-versions) | List the versions recorded for a release. |\n| [Release Source Manifests](#tag/release-source-manifests) | Export the source manifest for a release. |\n| [Release Asset Manifests](#tag/release-asset-manifests) | Read, write, build, or update release asset manifests. |\n| [Environments](#tag/environments) | Create and manage deployment environments. Use the environment ID when configuring [deployments](#tag/project-deployments), [domains](#tag/environment-domains), [variables](#tag/environment-variables), or [servers](#tag/environment-servers). |\n| [Project deployments](#tag/project-deployments) | Deploy a release to an environment. Read deployment records to inspect the resulting configuration. Investigate application behavior through [project logs](#tag/project-logs). |\n| [Project Domains](#tag/project-domains) | List domains across a project. |\n| [Environment Domains](#tag/environment-domains) | Create, read, update, or delete domains for an environment. |\n| [Environment Variable Keys](#tag/environment-variable-keys) | List environment variable keys without values. |\n| [Environment variables](#tag/environment-variables) | List, create, read, update, or delete environment variables. |\n| [Project servers](#tag/project-servers) | List, read, or delete project server records. |\n| [Environment Servers](#tag/environment-servers) | Create a server for an environment. |\n| [Account servers](#tag/account-servers) | Create, read, or delete account-owned servers. Access depends on server ownership and linked project permissions. |\n| [Server Environments](#tag/server-environments) | Link or unlink environments from account-owned servers. |\n| [Proxy metadata](#tag/proxy-metadata) | Read routing or access metadata for proxy requests. These endpoints have separate freshness and authorization requirements. |"},{"name":"Releases","parent":"Deployment API","description":"Create, read, delete, or find project releases."},{"name":"Release Versions","parent":"Deployment API","description":"List the versions recorded for a release."},{"name":"Release Source Manifests","parent":"Deployment API","description":"Export the source manifest for a release."},{"name":"Release Asset Manifests","parent":"Deployment API","description":"Read, write, build, or update release asset manifests."},{"name":"Environments","parent":"Deployment API","description":"Create and manage deployment environments. Use the environment ID when configuring [deployments](#tag/project-deployments), [domains](#tag/environment-domains), [variables](#tag/environment-variables), or [servers](#tag/environment-servers)."},{"name":"Project deployments","parent":"Deployment API","description":"Deploy a release to an environment. Read deployment records to inspect the resulting configuration. Investigate application behavior through [project logs](#tag/project-logs)."},{"name":"Project Domains","parent":"Deployment API","description":"List domains across a project."},{"name":"Environment Domains","parent":"Deployment API","description":"Create, read, update, or delete domains for an environment."},{"name":"Environment Variable Keys","parent":"Deployment API","description":"List environment variable keys without values."},{"name":"Environment variables","parent":"Deployment API","description":"List, create, read, update, or delete environment variables."},{"name":"Project servers","parent":"Deployment API","description":"List, read, or delete project server records."},{"name":"Environment Servers","parent":"Deployment API","description":"Create a server for an environment."},{"name":"Account servers","parent":"Deployment API","description":"**Internal interface.** Create, read, or delete account-owned servers. Access depends on server ownership and linked project permissions.","x-audience":"company-internal"},{"name":"Server Environments","parent":"Deployment API","description":"**Internal interface.** Link or unlink environments from account-owned servers.","x-audience":"company-internal"},{"name":"Proxy metadata","parent":"Deployment API","description":"Read routing or access metadata for proxy requests. These endpoints have separate freshness and authorization requirements."},{"name":"Sandbox API","description":"Create isolated sessions, run commands, and manage files.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Sandbox Sessions](#tag/sandbox-sessions) | Create, read, update, or delete sandbox sessions. |\n| [Sandbox Commands](#tag/sandbox-commands) | Run commands and inspect command output. |\n| [Sandbox Files](#tag/sandbox-files) | List, read, or write sandbox files. |\n| [Sandbox Terminal](#tag/sandbox-terminal) | Open a sandbox terminal. |\n| [Sandbox Health](#tag/sandbox-health) | Check sandbox health, readiness, and heartbeat state. |"},{"name":"Sandbox Sessions","parent":"Sandbox API","description":"Create, read, update, or delete sandbox sessions."},{"name":"Sandbox Commands","parent":"Sandbox API","description":"Run commands and inspect command output."},{"name":"Sandbox Files","parent":"Sandbox API","description":"List, read, or write sandbox files."},{"name":"Sandbox Terminal","parent":"Sandbox API","description":"Open a sandbox terminal."},{"name":"Sandbox Health","parent":"Sandbox API","description":"Check sandbox health, readiness, and heartbeat state."},{"name":"Cache API","description":"Read and write cached values in project or user scope.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Project Cache](#tag/project-cache) | Read and write individual values or batches. Inspect keys and statistics, delete matching keys, or clear the project cache. |\n| [User Cache](#tag/user-cache) | Read, write, or delete values in the authenticated user’s cache. |"},{"name":"Project Cache","parent":"Cache API","description":"Read and write individual values or batches. Inspect keys and statistics, delete matching keys, or clear the project cache."},{"name":"User Cache","parent":"Cache API","description":"Read, write, or delete values in the authenticated user’s cache."},{"name":"Observability API","description":"Query logs, metrics, traces, and alerts to investigate application behavior.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Project logs](#tag/project-logs) | Query project logs to investigate activity and failures. Each endpoint reference lists the supported filters. |\n| [Project metrics](#tag/project-metrics) | Query project metrics to inspect measurements over time. |\n| [Project traces](#tag/project-traces) | Find project traces and inspect individual traces by ID. Trace spans connect related execution activity. For a run’s event history, use the [run endpoints](#tag/runs-api). |\n| [Project alerts](#tag/project-alerts) | List the alerts that fired for a project, firing and recently resolved, with links to the logs and traces they cover. |\n| [Account conversation analytics](#tag/account-conversation-analytics) | Read account-level conversation analytics. Find account run analytics under [Runs](#tag/runs-api). Use the [Billing and Usage API](#tag/billing-and-usage-api) for consumption and spending data. |"},{"name":"Project logs","parent":"Observability API","description":"Query project logs to investigate activity and failures. Each endpoint reference lists the supported filters."},{"name":"Project metrics","parent":"Observability API","description":"Query project metrics to inspect measurements over time."},{"name":"Project traces","parent":"Observability API","description":"Find project traces and inspect individual traces by ID. Trace spans connect related execution activity. For a run’s event history, use the [run endpoints](#tag/runs-api)."},{"name":"Project alerts","parent":"Observability API","description":"List the alerts that fired for a project, firing and recently resolved, with links to the logs and traces they cover."},{"name":"Account conversation analytics","parent":"Observability API","description":"Read account-level conversation analytics. Find account run analytics under [Runs](#tag/runs-api). Use the [Billing and Usage API](#tag/billing-and-usage-api) for consumption and spending data."},{"name":"Identity and Access API","description":"Authenticate callers and manage account and project access.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Authentication](#tag/authentication) | Sign in through an identity provider or magic link, create tokens, and end sessions. Retrieve public verification keys from [the JWKS endpoint](#tag/authentication/GET/.well-known/jwks.json). |\n| [Current user](#tag/current-user) | Read the authenticated user’s profile. |\n| [Accounts](#tag/accounts) | List, create, or read accounts. |\n| [Account Members](#tag/account-members) | List, update, or remove account members. |\n| [Account Invitations](#tag/account-invitations) | List, create, revoke, or accept account invitations. |\n| [Account directory](#tag/account-directory) | List pending invitations and active members across projects you own. |\n| [Project Members](#tag/project-members) | List, read, remove, or update project members. |\n| [Project Invitations](#tag/project-invitations) | Create, read, delete, or resend project invitations. |\n| [Project Ownership](#tag/project-ownership) | Transfer project ownership. |\n| [API keys](#tag/api-keys) | Create, inspect, update, and revoke API keys. View [API key usage](#tag/api-key-usage) in the Billing and Usage API. |\n| [OAuth Metadata](#tag/oauth-metadata) | Discover OAuth authorization and protected-resource metadata. |\n| [OAuth Clients](#tag/oauth-clients) | Register public OAuth clients. |\n| [OAuth Authorization Requests](#tag/oauth-authorization-requests) | Start, read, or decide MCP authorization requests. |\n| [OAuth Tokens](#tag/oauth-tokens) | Exchange, rotate, or revoke OAuth tokens. |\n| [OAuth Grants](#tag/oauth-grants) | List or revoke authorized MCP app grants. |"},{"name":"Authentication","parent":"Identity and Access API","description":"Sign in through an identity provider or magic link, create tokens, and end sessions. Retrieve public verification keys from [the JWKS endpoint](#tag/authentication/GET/.well-known/jwks.json)."},{"name":"Current user","parent":"Identity and Access API","description":"Read the authenticated user’s profile."},{"name":"Accounts","parent":"Identity and Access API","description":"List, create, or read accounts."},{"name":"Account Members","parent":"Identity and Access API","description":"List, update, or remove account members."},{"name":"Account Invitations","parent":"Identity and Access API","description":"List, create, revoke, or accept account invitations."},{"name":"Account directory","parent":"Identity and Access API","description":"List pending invitations and active members across projects you own."},{"name":"Project Members","parent":"Identity and Access API","description":"List, read, remove, or update project members."},{"name":"Project Invitations","parent":"Identity and Access API","description":"Create, read, delete, or resend project invitations."},{"name":"Project Ownership","parent":"Identity and Access API","description":"Transfer project ownership."},{"name":"API keys","parent":"Identity and Access API","description":"Create, inspect, update, and revoke API keys. View [API key usage](#tag/api-key-usage) in the Billing and Usage API."},{"name":"OAuth Metadata","parent":"Identity and Access API","description":"Discover OAuth authorization and protected-resource metadata."},{"name":"OAuth Clients","parent":"Identity and Access API","description":"Register public OAuth clients."},{"name":"OAuth Authorization Requests","parent":"Identity and Access API","description":"Start, read, or decide MCP authorization requests."},{"name":"OAuth Tokens","parent":"Identity and Access API","description":"Exchange, rotate, or revoke OAuth tokens."},{"name":"OAuth Grants","parent":"Identity and Access API","description":"List or revoke authorized MCP app grants."},{"name":"Billing and Usage API","description":"Manage subscriptions, payments, credits, budgets, and usage.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [Account Collaboration](#tag/account-collaboration) | Read owner-wide collaboration entitlements and seat usage. The project reference selects its owner; can_invite does not grant requester invitation permission. |\n| [Subscriptions](#tag/subscriptions) | Read, upgrade, or cancel the account subscription. Create [a checkout session](#tag/subscriptions/POST/account/subscription/checkout) or open [the billing portal](#tag/subscriptions/GET/account/subscription/manage). |\n| [Billing Details](#tag/billing-details) | Read or update account billing details. |\n| [Invoices](#tag/invoices) | List invoices and upcoming invoices. |\n| [Payment Methods](#tag/payment-methods) | List, attach, detach, or select payment methods. |\n| [Payments](#tag/payments) | List account payments. |\n| [Credits](#tag/credits) | Check the credit balance, review transactions, buy credits, or redeem a coupon. |\n| [Budgets](#tag/budgets) | Set monthly AI spending caps by project, person, API key, or a combination of these fields. New budgets count spending already incurred that month; use [`PATCH /budgets/{budget_id}`](#tag/budgets/PATCH/budgets/{budget_id}) to change an existing cap. |\n| [Account usage](#tag/account-usage) | Read account consumption, credit usage, limits, trends, and warnings. |\n| [Project usage](#tag/project-usage) | Use [member usage](#tag/project-usage/GET/projects/{project_reference}/members/usage) for project AI spend by person and automation. [AI usage analytics](#tag/project-usage/GET/projects/{project_reference}/analytics/ai-usage) adds daily project or member consumption and customer charges. The [project usage endpoint](#tag/project-usage/GET/projects/{project_reference}/usage) returns the project owner’s account-wide totals, not project-attributed usage. |\n| [API key usage](#tag/api-key-usage) | List usage across API keys or inspect one key. Manage the keys themselves through [API key endpoints](#tag/api-keys). Manage [inference limits](#tag/api-key-usage/GET/api-keys/{id}/limits) for project-bound keys. |\n| [Feature gates](#tag/feature-gates) | Check access to a named plan or feature gate. Individual endpoints still enforce their resource permissions. |"},{"name":"Account Collaboration","parent":"Billing and Usage API","description":"Read owner-wide collaboration entitlements and seat usage. The project reference selects its owner; can_invite does not grant requester invitation permission."},{"name":"Subscriptions","parent":"Billing and Usage API","description":"Read, upgrade, or cancel the account subscription. Create [a checkout session](#tag/subscriptions/POST/account/subscription/checkout) or open [the billing portal](#tag/subscriptions/GET/account/subscription/manage)."},{"name":"Billing Details","parent":"Billing and Usage API","description":"Read or update account billing details."},{"name":"Invoices","parent":"Billing and Usage API","description":"List invoices and upcoming invoices."},{"name":"Payment Methods","parent":"Billing and Usage API","description":"List, attach, detach, or select payment methods."},{"name":"Payments","parent":"Billing and Usage API","description":"List account payments."},{"name":"Credits","parent":"Billing and Usage API","description":"Check the credit balance, review transactions, buy credits, or redeem a coupon."},{"name":"Budgets","parent":"Billing and Usage API","description":"Set monthly AI spending caps by project, person, API key, or a combination of these fields. New budgets count spending already incurred that month; use [`PATCH /budgets/{budget_id}`](#tag/budgets/PATCH/budgets/{budget_id}) to change an existing cap."},{"name":"Account usage","parent":"Billing and Usage API","description":"Read account consumption, credit usage, limits, trends, and warnings."},{"name":"Project usage","parent":"Billing and Usage API","description":"Use [member usage](#tag/project-usage/GET/projects/{project_reference}/members/usage) for project AI spend by person and automation. [AI usage analytics](#tag/project-usage/GET/projects/{project_reference}/analytics/ai-usage) adds daily project or member consumption and customer charges. The [project usage endpoint](#tag/project-usage/GET/projects/{project_reference}/usage) returns the project owner’s account-wide totals, not project-attributed usage."},{"name":"API key usage","parent":"Billing and Usage API","description":"List usage across API keys or inspect one key. Manage the keys themselves through [API key endpoints](#tag/api-keys). Manage [inference limits](#tag/api-key-usage/GET/api-keys/{id}/limits) for project-bound keys."},{"name":"Feature gates","parent":"Billing and Usage API","description":"Check access to a named plan or feature gate. Individual endpoints still enforce their resource permissions."},{"name":"API discovery and metadata","description":"Discover tools, inspect schemas, and look up API error types.\n\n| Endpoint group | Use it to |\n| --- | --- |\n| [MCP discovery](#tag/mcp-discovery) | List MCP tools and inspect their schemas before invoking them through the [MCP interface](https://veryfront.com/docs/cloud/rest/protocols#mcp). Use [the MCP playground](#tag/mcp-discovery/GET/mcp/playground) to explore tools. The older catalog alias is deprecated; use [the tool list](#tag/mcp-discovery/GET/mcp/tools) and [tool details](#tag/mcp-discovery/GET/mcp/tools/{tool_name}). |\n| [Error metadata](#tag/error-metadata) | Read the meaning of a published error type. Use [logs](#tag/project-logs) or [traces](#tag/project-traces) to investigate a specific failed request. |"},{"name":"MCP discovery","parent":"API discovery and metadata","description":"List MCP tools and inspect their schemas before invoking them through the [MCP interface](https://veryfront.com/docs/cloud/rest/protocols#mcp). Use [the MCP playground](#tag/mcp-discovery/GET/mcp/playground) to explore tools. The older catalog alias is deprecated; use [the tool list](#tag/mcp-discovery/GET/mcp/tools) and [tool details](#tag/mcp-discovery/GET/mcp/tools/{tool_name})."},{"name":"Error metadata","parent":"API discovery and metadata","description":"Read the meaning of a published error type. Use [logs](#tag/project-logs) or [traces](#tag/project-traces) to investigate a specific failed request."}],"x-tagGroups":[{"name":"Agents API","tags":["Agents API","Accessible agents","Agent templates","Project agents","Agent Capabilities","Agent Tool References","Agent Labels","Agent Avatars","Agent Installation","Project prompts","Project skills","Project tools","Project tasks","Project workflows","Project resources"]},{"name":"Execution API","tags":["Execution API","Runs API","Runtime compatibility","Run resource","Run actions","Run events","Child runs","Run input request","Input request","Runtime","Project runs","Webhook runs","Eval runs","Conversation runs","Account runs","Run runtime callbacks","Conversations","Conversation Messages","Conversation Branches","Conversation Participants","Conversation Read State","Participant lookup","Project schedules","Project webhooks","Webhook delivery","Agent runtime registration","Agent workers"]},{"name":"Evaluations API","tags":["Evaluations API","Evaluation Definitions"]},{"name":"AI Gateway API","tags":["AI Gateway API","Application Inference","Model discovery","Anthropic Messages","OpenAI Chat Completions","OpenAI Responses","Embeddings","Inference Models","Gemini Models","Image generation","Provider gateway","Project inference policy"]},{"name":"Knowledge API","tags":["Knowledge API","Project documents","File Chunks","Project embeddings","Vector search","Project knowledge"]},{"name":"Integrations API","tags":["Integrations API","Integration catalog","Project integrations","Integration OAuth","Connections","Integration tools","Channel Bindings","Channel Platforms","Channel Assistants","Slack Channels","Channel delivery","Provider Files","Provider Folders","Provider Search"]},{"name":"Projects API","tags":["Projects API","Projects","Project Labels","Account Projects","Project Templates","Project Files","Project File Versions","File search","Branches","Branch Approvals","Branch Status Checks","Branch Policies","Project Commits","Branch Files","Branch File Versions","Branch File Drafts","Environment Files","Release Files","Project Uploads","Upload Folders","Upload Grants","Upload Visibility","Dependencies","Dependency artifacts","Style artifacts","Favorites"]},{"name":"Deployment API","tags":["Deployment API","Releases","Release Versions","Release Source Manifests","Release Asset Manifests","Environments","Project deployments","Project Domains","Environment Domains","Environment Variable Keys","Environment variables","Project servers","Environment Servers","Account servers","Server Environments","Proxy metadata"]},{"name":"Sandbox API","tags":["Sandbox API","Sandbox Sessions","Sandbox Commands","Sandbox Files","Sandbox Terminal","Sandbox Health"]},{"name":"Cache API","tags":["Cache API","Project Cache","User Cache"]},{"name":"Observability API","tags":["Observability API","Project logs","Project metrics","Project traces","Project alerts","Account conversation analytics"]},{"name":"Identity and Access API","tags":["Identity and Access API","Authentication","Current user","Accounts","Account Members","Account Invitations","Account directory","Project Members","Project Invitations","Project Ownership","API keys","OAuth Metadata","OAuth Clients","OAuth Authorization Requests","OAuth Tokens","OAuth Grants"]},{"name":"Billing and Usage API","tags":["Billing and Usage API","Account Collaboration","Subscriptions","Billing Details","Invoices","Payment Methods","Payments","Credits","Budgets","Account usage","Project usage","API key usage","Feature gates"]},{"name":"API discovery and metadata","tags":["API discovery and metadata","MCP discovery","Error metadata"]}],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"servers":[{"url":"https://api.veryfront.com","description":"Current request origin"},{"url":"http://localhost:4000","description":"Local development"}],"externalDocs":{"description":"Interactive REST reference","url":"https://api.veryfront.com/docs"}}