{"openapi":"3.1.0","info":{"title":"Veryfront REST API","version":"1.0.0","summary":"Domain-first REST reference for the maintained Veryfront HTTP API surface.","description":"Project-first HTTP API for Veryfront project resources. Root account/platform endpoints that still appear in this reference are transitional compatibility surfaces unless the canonical inventory marks them otherwise.\n\n## Start here\n\n- **Interactive REST reference:** [/docs](/docs)\n- **Raw OpenAPI document:** [/openapi.json](/openapi.json)\n- **Canonical inventory:** `docs/api-surface-inventory.md` in this repository\n- **GraphQL endpoint:** [/graphql](/graphql)\n- **MCP playground:** [/mcp/playground](/mcp/playground)\n\n## Authentication\n\nUse one of these request headers:\n\n- `Authorization: Bearer <jwt>`\n- `Authorization: Bearer vf_<prefix>_<secret>`\n- `X-API-Key: vf_<prefix>_<secret>`\n\nJWTs must use the Bearer token contract. API keys work in either the Bearer header or `X-API-Key`.\n\n## Discovery model\n\nVeryfront is one platform with multiple access modes:\n\n- **REST** for resource-oriented and operational HTTP workflows\n- **GraphQL** for connected app-facing data and typed mutations\n- **MCP** for tool-style automation and agent workflows\n\nFor the fastest path through the platform, start with the project-scoped domain groups. Transitional account/platform groups are retained for compatibility and follow the removal register in the canonical inventory.","contact":{"name":"Veryfront API Support","url":"https://veryfront.com/docs","email":"support@veryfront.com"}},"components":{"schemas":{"UploadFolder":{"type":"object","properties":{"type":{"type":"string","enum":["folder"],"description":"Item type","example":"folder"},"path":{"type":"string"},"visibility":{"type":"string","enum":["project","public","private"]},"permission":{"type":"string","enum":["read","write","admin"]},"created_at":{"type":"string"}},"required":["type","path","visibility","permission","created_at"]},"UploadFile":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"file_name":{"type":"string"},"content_type":{"type":"string","nullable":true},"size":{"type":"number"},"url":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","active","failed"]},"visibility":{"type":"string","enum":["project","public","private"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"type":{"type":"string","enum":["file"],"description":"Item type","example":"file"},"permission":{"type":"string","enum":["read","write","admin"]}},"required":["id","path","file_name","content_type","size","url","status","visibility","created_at","updated_at","deleted_at","type","permission"]},"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"]},"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":{"nullable":true},"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 or slug alias. Use project_reference."},"project_slug":{"type":"string","description":"Deprecated project slug alias. 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","minimum":0,"exclusiveMinimum":true,"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","format":"uri","description":"URL to redirect after verification"},"redirect_url":{"type":"string","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"]}},"parameters":{},"securitySchemes":{"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."}}},"paths":{"/projects":{"get":{"operationId":"listProjects","tags":["Projects"],"summary":"List Projects","parameters":[{"schema":{"type":"string","description":"Cursor for pagination from previous response","example":"eyJpZCI6IjEyMyJ9"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Sort field.","example":"created_at"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort order.","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","nullable":true,"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"}],"responses":{"200":{"description":"Paginated list of projects","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"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":{"nullable":true}},"active_release_id":{"type":"string","nullable":true,"format":"uuid"},"server_hostname":{"type":"string","nullable":true}},"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":{"type":"object","additionalProperties":{"nullable":true}},"provider":{"type":"string","nullable":true},"layout":{"type":"string","nullable":true},"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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"]}},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true}},"required":["id","namespace","key","value"]}}},"required":["id","slug","name"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"400":{"description":"Invalid label filter"},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}},"post":{"operationId":"createProject","tags":["Projects"],"summary":"Create Project","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"templateSlug":{"type":"string"},"templateProjectId":{"type":"string","format":"uuid"}},"required":["name"]},"example":{"name":"My Project","description":"A sample project description","templateSlug":"minimal"}}}},"responses":{"201":{"description":"Project created","content":{"application/json":{"schema":{"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":{"nullable":true}},"active_release_id":{"type":"string","nullable":true,"format":"uuid"},"server_hostname":{"type":"string","nullable":true}},"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":{"type":"object","additionalProperties":{"nullable":true}},"provider":{"type":"string","nullable":true},"layout":{"type":"string","nullable":true},"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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"]}},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true}},"required":["id","namespace","key","value"]}}},"required":["id","slug","name"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/projects/-/proxy-routing/{lookup_key}":{"get":{"operationId":"getProjectProxyRouting","tags":["Projects"],"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","nullable":true}},"required":["id","name","domains","active_release_id"]}}},"required":["id","slug","name","environments"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/-/proxy-access/{lookup_key}":{"get":{"operationId":"getProjectProxyAccess","tags":["Projects"],"summary":"Get proxy access metadata","description":"Returns 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/{project_reference}/labels":{"get":{"operationId":"listProjectLabels","tags":["Projects"],"summary":"List project labels","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Project labels","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resource_kind":{"type":"string","enum":["project","project_agent"]},"project_id":{"type":"string","format":"uuid"},"source_target_kind":{"type":"string","nullable":true},"source_agent_id":{"type":"string","nullable":true},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","resource_kind","project_id","namespace","key","value","created_at","updated_at"]}}},"required":["labels"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"}}},"post":{"operationId":"createProjectLabel","tags":["Projects"],"summary":"Create project label","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"value":{"type":"string","nullable":true,"maxLength":128},"color":{"type":"string","nullable":true,"maxLength":32}},"required":["key"]}}}},"responses":{"200":{"description":"Created label","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resource_kind":{"type":"string","enum":["project","project_agent"]},"project_id":{"type":"string","format":"uuid"},"source_target_kind":{"type":"string","nullable":true},"source_agent_id":{"type":"string","nullable":true},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","resource_kind","project_id","namespace","key","value","created_at","updated_at"]}}}},"400":{"description":"Invalid label input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Project not found"},"409":{"description":"Label already exists"}}}},"/projects/{project_reference}/labels/{label_id}":{"put":{"operationId":"updateProjectLabel","tags":["Projects"],"summary":"Update project label","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"label_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"value":{"type":"string","nullable":true,"maxLength":128},"color":{"type":"string","nullable":true,"maxLength":32}},"required":["key"]}}}},"responses":{"200":{"description":"Updated label","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resource_kind":{"type":"string","enum":["project","project_agent"]},"project_id":{"type":"string","format":"uuid"},"source_target_kind":{"type":"string","nullable":true},"source_agent_id":{"type":"string","nullable":true},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","resource_kind","project_id","namespace","key","value","created_at","updated_at"]}}}},"400":{"description":"Invalid label input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Label not found"},"409":{"description":"Label already exists"}}},"delete":{"operationId":"deleteProjectLabel","tags":["Projects"],"summary":"Delete project label","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"label_id","in":"path"}],"responses":{"204":{"description":"Label removed"},"401":{"description":"Unauthorized"},"404":{"description":"Label not found"}}}},"/projects/{project_reference}/agents/{agent_id}/labels":{"get":{"operationId":"listProjectAgentLabels","tags":["Agents"],"summary":"List project agent labels","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch"],"default":"project"},"required":false,"name":"source_target_kind","in":"query"}],"responses":{"200":{"description":"Agent labels","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resource_kind":{"type":"string","enum":["project","project_agent"]},"project_id":{"type":"string","format":"uuid"},"source_target_kind":{"type":"string","nullable":true},"source_agent_id":{"type":"string","nullable":true},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","resource_kind","project_id","namespace","key","value","created_at","updated_at"]}}},"required":["labels"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"}}},"post":{"operationId":"createProjectAgentLabel","tags":["Agents"],"summary":"Create project agent label","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch"],"default":"project"},"required":false,"name":"source_target_kind","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"value":{"type":"string","nullable":true,"maxLength":128},"color":{"type":"string","nullable":true,"maxLength":32}},"required":["key"]}}}},"responses":{"200":{"description":"Created label","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resource_kind":{"type":"string","enum":["project","project_agent"]},"project_id":{"type":"string","format":"uuid"},"source_target_kind":{"type":"string","nullable":true},"source_agent_id":{"type":"string","nullable":true},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","resource_kind","project_id","namespace","key","value","created_at","updated_at"]}}}},"400":{"description":"Invalid label input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Project or agent not found"},"409":{"description":"Label already exists"}}}},"/projects/{project_reference}/agents/{agent_id}/labels/{label_id}":{"put":{"operationId":"updateProjectAgentLabel","tags":["Agents"],"summary":"Update project agent label","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"label_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch"],"default":"project"},"required":false,"name":"source_target_kind","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"value":{"type":"string","nullable":true,"maxLength":128},"color":{"type":"string","nullable":true,"maxLength":32}},"required":["key"]}}}},"responses":{"200":{"description":"Updated label","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resource_kind":{"type":"string","enum":["project","project_agent"]},"project_id":{"type":"string","format":"uuid"},"source_target_kind":{"type":"string","nullable":true},"source_agent_id":{"type":"string","nullable":true},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","resource_kind","project_id","namespace","key","value","created_at","updated_at"]}}}},"400":{"description":"Invalid label input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Agent or label not found"},"409":{"description":"Label already exists"}}},"delete":{"operationId":"deleteProjectAgentLabel","tags":["Agents"],"summary":"Delete project agent label","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"label_id","in":"path"},{"schema":{"type":"string","enum":["project","main_branch"],"default":"project"},"required":false,"name":"source_target_kind","in":"query"}],"responses":{"204":{"description":"Label removed"},"401":{"description":"Unauthorized"},"404":{"description":"Label not found"}}}},"/projects/{project_reference}":{"get":{"operationId":"getProject","tags":["Projects"],"summary":"Get Project","description":"Returns the authenticated caller’s accessible project with related environments.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Project found","content":{"application/json":{"schema":{"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":{"nullable":true}},"active_release_id":{"type":"string","nullable":true,"format":"uuid"},"server_hostname":{"type":"string","nullable":true}},"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":{"type":"object","additionalProperties":{"nullable":true}},"provider":{"type":"string","nullable":true},"layout":{"type":"string","nullable":true},"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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"]}},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true}},"required":["id","namespace","key","value"]}}},"required":["id","slug","name"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"patch":{"operationId":"updateProject","tags":["Projects"],"summary":"Update Project","parameters":[{"schema":{"type":"string","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-z0-9-]+$"},"name":{"type":"string","minLength":1},"description":{"type":"string"},"config":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"nullable":true}}]}}},"example":{"name":"Updated Project Name","description":"Updated description"}}}},"responses":{"200":{"description":"Project updated successfully","content":{"application/json":{"schema":{"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":{"nullable":true}},"active_release_id":{"type":"string","nullable":true,"format":"uuid"},"server_hostname":{"type":"string","nullable":true}},"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":{"type":"object","additionalProperties":{"nullable":true}},"provider":{"type":"string","nullable":true},"layout":{"type":"string","nullable":true},"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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"]}},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"value":{"type":"string","nullable":true},"color":{"type":"string","nullable":true}},"required":["id","namespace","key","value"]}}},"required":["id","slug","name"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteProject","tags":["Projects"],"summary":"Delete Project","description":"Deletes the resolved project and returns no content when the project is removed.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"}],"responses":{"204":{"description":"Project deleted"},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/collaboration":{"get":{"operationId":"getProjectCollaboration","tags":["Projects"],"summary":"Get Project Collaboration","description":"Returns owner-scoped collaboration seat capacity and availability for the resolved project. Not a billing endpoint: this is the project-scoped collaboration/seat status used by clients to gate invites and collaboration.","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},"active":{"type":"integer","minimum":0},"reserved":{"type":"integer","minimum":0},"available":{"type":"integer","minimum":0}},"required":["purchased","active","reserved","available"]},"over_capacity":{"type":"boolean"},"collaboration_allowed":{"type":"boolean"},"can_invite":{"type":"boolean"}},"required":["seats","over_capacity","collaboration_allowed","can_invite"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/usage":{"get":{"operationId":"getProjectUsage","tags":["Usage"],"summary":"Get Project Usage","description":"Returns storage and API call usage totals for the owner of the resolved project.","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":{"type":"object","properties":{"storage":{"type":"object","properties":{"used":{"type":"number"},"total":{"type":"number"},"percent_used":{"type":"number"},"remaining":{"type":"number"}},"required":["used","total","percent_used","remaining"]},"api_calls":{"type":"object","properties":{"used":{"type":"number"},"total":{"type":"number"},"percent_used":{"type":"number"},"remaining":{"type":"number"}},"required":["used","total","percent_used","remaining"]},"period_start":{"type":"string"},"period_end":{"type":"string"}},"required":["storage","api_calls","period_start","period_end"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/files":{"get":{"operationId":"listFiles","tags":["Files"],"summary":"List Project Files","description":"Returns all file fields including content by default. Use ?fields=(id,path,size) to filter response fields per Zalando #157.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"File pattern filter (e.g., *.tsx)"},"required":false,"name":"pattern","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","default":"updated_at","description":"Sort field."},"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","description":"Branch name or ID (omit for main branch)"},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Sparse fieldset filter per Zalando #157. Examples: (id,name), (id,files(path)), !(content)","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"Paginated list of files (supports sparse fieldsets per Zalando #157)","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"},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"},"checksum":{"type":"string","nullable":true},"_links":{"type":"object","properties":{"self":{"type":"object","properties":{"href":{"type":"string"}},"required":["href"]}},"required":["self"]}},"required":["path","content","size","type","updated_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"_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"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/files/batch":{"post":{"operationId":"getFilesBatch","tags":["Files"],"summary":"Batch Get Project Files","description":"Fetch multiple files in a single request","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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"},"found":{"type":"boolean"},"checksum":{"type":"string","nullable":true},"error":{"type":"string"}},"required":["path","type","content","size","found"]}}},"required":["files"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/files/search":{"post":{"operationId":"searchFiles","tags":["Search"],"summary":"Search Project Files (Text)","description":"Grep-like text search across all project files with regex support","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","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 (e.g., *.tsx)"},"is_regex":{"type":"boolean","description":"Treat query as regex (default: false)"},"case_sensitive":{"type":"boolean","description":"Case sensitive search (default: false)"},"context_lines":{"type":"number","description":"Number of context lines (default: 1)"},"max_results":{"type":"number","description":"Maximum results (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"},"content":{"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 or regex"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/files/move":{"post":{"operationId":"moveFile","tags":["Files"],"summary":"Move Project File","description":"Move a file from one path to another","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (null for main branch)"},"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"}},"required":["source_path","destination_path"]}}}},"responses":{"200":{"description":"File moved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"source_path":{"type":"string"},"destination_path":{"type":"string"},"success":{"type":"boolean"}},"required":["source_path","destination_path","success"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Source file not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/files/{file_path}":{"get":{"operationId":"getFile","tags":["Files"],"summary":"Get Project File","description":"Get a file by its path (e.g., pages/index.mdx) or entity UUID. The identifier type is auto-detected. Use ?fields=(id,path,size) to filter response fields per Zalando #157. The filePath should be URL-encoded if it contains special characters (e.g., 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, e.g., pages%2Findex.mdx)"},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Branch name or ID (omit for main branch)"},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","pattern":"^!?\\([^)]*\\)$","description":"Sparse fieldset filter per Zalando #157. Examples: (id,name), (id,files(path)), !(content)","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"File content with metadata (supports sparse fieldsets per Zalando #157)","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"},"checksum":{"type":"string","nullable":true},"_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"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"File not found"},"500":{"description":"Server error"}}},"put":{"operationId":"createOrUpdateFile","tags":["Files"],"summary":"Upsert Project File","description":"The filePath should be URL-encoded if it contains special characters (e.g., 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, e.g., pages%2Findex.mdx)"},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (null for main branch)"},"required":false,"name":"branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"File content"},"content_type":{"type":"string","description":"MIME type (default: text/plain)"},"expected_checksum":{"type":"string","description":"Expected current file checksum for optimistic concurrency"},"expected_version_id":{"type":"string","description":"Expected current file version ID for optimistic concurrency"},"expected_absent":{"type":"boolean","description":"Require the file to be absent when it is created"}},"required":["content"]}}}},"responses":{"200":{"description":"File updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number"},"updated_at":{"type":"string"}},"required":["id","path","content","size","updated_at"]}}}},"201":{"description":"File created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number"},"created_at":{"type":"string"}},"required":["id","path","content","size","created_at"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"409":{"description":"File changed since it was read"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteFile","tags":["Files"],"summary":"Delete Project File","description":"The filePath should be URL-encoded if it contains special characters (e.g., 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, e.g., pages%2Findex.mdx)"},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (null for main branch)"},"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"},"400":{"description":"Missing file path"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"File not found"},"409":{"description":"File changed since it was read"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/files/{file_path}/versions":{"get":{"operationId":"listFileVersions","tags":["Files"],"summary":"List Project File Versions","description":"The filePath should be URL-encoded if it contains special characters (e.g., 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, e.g., pages%2Findex.mdx)"},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["date","version"],"default":"date","description":"Sort field."},"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"}],"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"},"file_id":{"type":"string"},"path":{"type":"string"},"type":{"type":"string"},"created_at":{"type":"string"},"created_by":{"type":"string","nullable":true}},"required":["id","path","type","created_at","created_by"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"400":{"description":"Missing file path"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"File not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/files/{file_path}/versions/{version_id}":{"get":{"operationId":"getFileVersion","tags":["Files"],"summary":"Get Project File Version","description":"The filePath should be URL-encoded if it contains special characters (e.g., 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, e.g., pages%2Findex.mdx)"},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Version UUID or numeric index (0 = current)"},"required":true,"name":"version_id","in":"path"}],"responses":{"200":{"description":"File version content with metadata","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"size":{"type":"number"},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"}},"required":["id","path","content","size","type","updated_at"]}}}},"400":{"description":"Missing parameters"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Version not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/files/{file_path}/diff":{"get":{"operationId":"getFileDiff","tags":["Files"],"summary":"Get Project File Diff","description":"Returns a unified diff (git-compatible format) comparing the current version to a previous version. Requires source_ref to specify the version to compare against. The filePath should be URL-encoded if it contains special characters (e.g., 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, e.g., pages%2Findex.mdx)"},"required":true,"name":"file_path","in":"path"},{"schema":{"type":"string","description":"Source version ID to compare from (required for main branch diff)"},"required":true,"name":"source_ref","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"maximum":10,"default":3,"description":"Number of context lines around changes (default: 3)"},"required":false,"name":"context_lines","in":"query"},{"schema":{"type":"string","description":"Branch name or ID (omit for main branch)"},"required":false,"name":"branch","in":"query"}],"responses":{"200":{"description":"Unified diff","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"diff":{"type":"string"},"additions":{"type":"number"},"deletions":{"type":"number"}},"required":["path","diff","additions","deletions"]}}}},"400":{"description":"Missing file path or source_ref"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"File or version not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/uploads":{"get":{"tags":["Uploads"],"summary":"List Uploads","description":"Paginated list of folders and files. Use the `path` query param to scope to a specific directory level.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Folder path prefix to list (e.g., \"assets/\"). Omit for root."},"required":false,"name":"path","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ISO timestamp)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"500":{"description":"Server error"}}},"post":{"tags":["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":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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":"number","minimum":0,"exclusiveMinimum":true,"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"},"file_path":{"type":"string"},"upload_id":{"type":"string"},"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":"Invalid input"},"401":{"description":"Unauthorized"},"402":{"description":"Storage quota exceeded"},"403":{"description":"Forbidden - insufficient permissions"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/uploads/{upload_reference}":{"get":{"tags":["Uploads"],"summary":"Get Upload","description":"Get uploaded file by ID or path. Public uploads are served without auth. Private uploads require auth. With Accept: application/json returns metadata. Otherwise returns 302 redirect to signed URL (for img src).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Upload ID (UUID) or URL-encoded file path"},"required":true,"name":"upload_reference","in":"path"}],"responses":{"200":{"description":"File metadata (when Accept: application/json)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"file_name":{"type":"string"},"content_type":{"type":"string","nullable":true},"size":{"type":"number"},"url":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","active","failed"]},"visibility":{"type":"string","enum":["project","public","private"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true}},"required":["id","path","file_name","content_type","size","url","status","visibility","created_at","updated_at","deleted_at"]}}}},"302":{"description":"Redirect to signed URL (default behavior for browsers/img tags)"},"401":{"description":"Unauthorized"},"404":{"description":"File not found"},"500":{"description":"Server error"}}},"delete":{"tags":["Uploads"],"summary":"Delete Upload","description":"Soft deletes a user-uploaded file. The file can be restored within the retention period.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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"},"401":{"description":"Unauthorized"},"404":{"description":"File not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/uploads/{upload_reference}/move":{"post":{"tags":["Uploads"],"summary":"Move Upload","description":"Moves a user-uploaded file from one path to another within the project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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"},"error":{"type":"string"},"file":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"file_name":{"type":"string"},"content_type":{"type":"string","nullable":true},"size":{"type":"number"},"url":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","active","failed"]},"visibility":{"type":"string","enum":["project","public","private"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true}},"required":["id","path","file_name","content_type","size","url","status","visibility","created_at","updated_at","deleted_at"]}},"required":["success"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Source file not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/uploads/{upload_reference}/restore":{"post":{"tags":["Uploads"],"summary":"Restore Upload","description":"Restores a soft-deleted file if it is still within the retention period.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Upload ID (UUID) or URL-encoded file path"},"required":true,"name":"upload_reference","in":"path"}],"responses":{"200":{"description":"File restored successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"file_name":{"type":"string"},"content_type":{"type":"string","nullable":true},"size":{"type":"number"},"url":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","active","failed"]},"visibility":{"type":"string","enum":["project","public","private"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true}},"required":["id","path","file_name","content_type","size","url","status","visibility","created_at","updated_at","deleted_at"]}}}},"400":{"description":"Invalid upload ID"},"401":{"description":"Unauthorized"},"404":{"description":"Upload not found or not deleted"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/uploads/{upload_reference}/url":{"get":{"tags":["Uploads"],"summary":"Get Upload Download URL","description":"Generates a signed URL for reading/downloading an uploaded file. Private files get 30-minute URLs, public files get 24-hour URLs. Use the `ttl` query param to request a shorter TTL (capped at the max for the visibility level).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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},"required":false,"name":"ttl","in":"query"}],"responses":{"200":{"description":"Signed download URL","content":{"application/json":{"schema":{"type":"object","properties":{"signed_url":{"type":"string"},"expires_at":{"type":"string"}},"required":["signed_url","expires_at"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"File not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/uploads/folders":{"post":{"tags":["Uploads"],"summary":"Create Folder","description":"Create a folder with optional visibility (default: internal).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"Folder path (e.g., \"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"},"visibility":{"type":"string","enum":["project","public","private"]}},"required":["path","visibility"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/projects/{project_reference}/uploads/folders/{path}":{"delete":{"tags":["Uploads"],"summary":"Delete Folder","description":"Deletes a folder, its visibility setting, all child folder visibility settings, and soft-deletes all files under the folder prefix.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"URL-encoded folder path (e.g., \"assets%2Fimages%2F\")"},"required":true,"name":"path","in":"path"}],"responses":{"204":{"description":"Folder deleted"},"400":{"description":"Invalid URL encoding in path"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Folder not found"}}}},"/projects/{project_reference}/uploads/folders/{path}/rename":{"post":{"tags":["Uploads"],"summary":"Rename Folder","description":"Renames/moves a folder and all its contents (subfolders, files, shares) to a new path.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"URL-encoded source folder path (e.g., \"assets%2Fimages%2F\")"},"required":true,"name":"path","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"string","description":"Destination folder path (e.g., \"assets/photos/\")"}},"required":["destination"]}}}},"responses":{"200":{"description":"Folder renamed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"old_path":{"type":"string"},"new_path":{"type":"string"},"folders_moved":{"type":"number"},"files_moved":{"type":"number"}},"required":["old_path","new_path","folders_moved","files_moved"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Source folder not found"},"409":{"description":"Destination folder already exists"}}}},"/projects/{project_reference}/uploads/visibility/{path}":{"put":{"tags":["Uploads"],"summary":"Set Path Visibility","description":"Set or update visibility for a path (folder prefix or individual file). Creates the setting if it does not exist.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Encoded path."},"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"},"visibility":{"type":"string","enum":["project","public","private"]}},"required":["path","visibility"]}}}},"400":{"description":"Invalid URL encoding in path"}}},"delete":{"tags":["Uploads"],"summary":"Remove Path Visibility","description":"Remove the visibility setting for a path. Files revert to the nearest parent setting or default project visibility.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Encoded path."},"required":true,"name":"path","in":"path"}],"responses":{"204":{"description":"Visibility removed"},"400":{"description":"Invalid URL encoding in path"},"404":{"description":"No visibility setting found for this path"}}}},"/projects/{project_reference}/uploads/grants/{path}":{"get":{"tags":["Uploads"],"summary":"List Grants","description":"Lists grants for a private path.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Encoded path."},"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"},"permission":{"type":"string","enum":["read","write","admin"]},"created_at":{"type":"string"}},"required":["user_id","permission","created_at"]}},"resolved_path":{"type":"string"},"resolved_type":{"type":"string","enum":["folder","upload"]},"resolved_id":{"type":"string"}},"required":["data","resolved_path"]}}}},"400":{"description":"Invalid URL encoding in path"},"403":{"description":"Admin access required"}}},"put":{"tags":["Uploads"],"summary":"Set Grants","description":"Sets grants for a private path.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Encoded path."},"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"},"permission":{"type":"string","enum":["read","write","admin"]},"created_at":{"type":"string"}},"required":["user_id","permission","created_at"]}},"resolved_path":{"type":"string"},"resolved_type":{"type":"string","enum":["folder","upload"]},"resolved_id":{"type":"string"}},"required":["data","resolved_path"]}}}},"400":{"description":"Invalid request"},"403":{"description":"Admin access required to manage grants"}}}},"/projects/{project_reference}/uploads/grants/{path}/{user_id}":{"delete":{"tags":["Uploads"],"summary":"Revoke Grant","description":"Removes a grant from a private path.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Encoded path."},"required":true,"name":"path","in":"path"},{"schema":{"type":"string","description":"User ID to remove"},"required":true,"name":"user_id","in":"path"}],"responses":{"204":{"description":"Grant removed"},"400":{"description":"Invalid URL encoding in path"},"403":{"description":"Admin access required"},"404":{"description":"Grant not found"}}}},"/projects/{project_reference}/deployments":{"get":{"tags":["Deployments"],"summary":"List Deployments","description":"Lists deployments for a project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination (deployment ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","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":"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","nullable":true,"format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","release_id","environment_id"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"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":{"tags":["Deployments"],"summary":"Create Deployment","description":"Creates a deployment for a release and environment.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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","nullable":true,"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":{"tags":["Deployments"],"summary":"Get Deployment","description":"Returns a deployment by ID.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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":{"tags":["Deployments"],"summary":"Update Deployment","description":"Updates a deployment.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":"New release ID"},"environment_id":{"type":"string","format":"uuid","description":"New environment ID"}}}}}},"responses":{"200":{"description":"Deployment updated 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","nullable":true,"format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","release_id","environment_id"]}}}},"400":{"description":"Invalid input - New release and environment must belong to the same project as the deployment"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - User does not have permission to update deployments in this project"},"404":{"description":"Deployment not found"},"500":{"description":"Server error"}}},"delete":{"tags":["Deployments"],"summary":"Delete Deployment","description":"Deletes a deployment.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"deployment_id","in":"path"}],"responses":{"204":{"description":"Deployment deleted successfully"},"401":{"description":"Unauthorized"},"404":{"description":"Deployment not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environments/{environment_id}/domains":{"get":{"tags":["Domains"],"summary":"List Domains","description":"Get 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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Environment not found"},"500":{"description":"Server error"}}},"post":{"tags":["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":{"tags":["Domains"],"summary":"Get Domain","description":"Get 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 (e.g., 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":{"tags":["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 (e.g., 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":{"tags":["Domains"],"summary":"Delete Domain","description":"Removes 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 (e.g., 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-variables":{"get":{"tags":["Environment Variables"],"summary":"List Environment Variables","description":"Lists 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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Environment not found"},"500":{"description":"Server error"}}},"post":{"tags":["Environment Variables"],"summary":"Create Environment Variable","description":"Creates 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-variable-keys":{"get":{"tags":["Environment Variables"],"summary":"List Environment Variable Keys","description":"Lists 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/{key}":{"get":{"tags":["Environment Variables"],"summary":"Get Environment Variable","description":"Returns 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":{"tags":["Environment Variables"],"summary":"Update Environment Variable","description":"Updates 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":{"tags":["Environment Variables"],"summary":"Delete Environment Variable","description":"Deletes 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}/releases":{"get":{"tags":["Releases"],"summary":"List Releases","description":"Lists 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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"version":{"type":"string","nullable":true,"description":"Semver version, for example \"1.2.3\"."},"project_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"export_status":{"type":"string","enum":["in_progress","completed","error"]},"build_status":{"type":"string","enum":["in_progress","completed","error"]},"deploy_status":{"type":"string","enum":["in_progress","completed","error"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"asset_manifest":{"type":"object","nullable":true,"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"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"tags":["Releases"],"summary":"Create Release","description":"Creates 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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"version":{"type":"string","nullable":true,"description":"Semver version, for example \"1.2.3\"."},"project_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"export_status":{"type":"string","enum":["in_progress","completed","error"]},"build_status":{"type":"string","enum":["in_progress","completed","error"]},"deploy_status":{"type":"string","enum":["in_progress","completed","error"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"asset_manifest":{"type":"object","nullable":true,"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"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/latest":{"get":{"tags":["Releases"],"summary":"Get Latest Release","description":"Returns 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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"version":{"type":"string","nullable":true,"description":"Semver version, for example \"1.2.3\"."},"project_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"export_status":{"type":"string","enum":["in_progress","completed","error"]},"build_status":{"type":"string","enum":["in_progress","completed","error"]},"deploy_status":{"type":"string","enum":["in_progress","completed","error"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"asset_manifest":{"type":"object","nullable":true,"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No releases found for this project"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/version/{version_spec}":{"get":{"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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"version":{"type":"string","nullable":true,"description":"Semver version, for example \"1.2.3\"."},"project_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"export_status":{"type":"string","enum":["in_progress","completed","error"]},"build_status":{"type":"string","enum":["in_progress","completed","error"]},"deploy_status":{"type":"string","enum":["in_progress","completed","error"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"asset_manifest":{"type":"object","nullable":true,"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No release found matching the version specifier"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{release_id}":{"get":{"tags":["Releases"],"summary":"Get Release","description":"Returns 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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"version":{"type":"string","nullable":true,"description":"Semver version, for example \"1.2.3\"."},"project_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"export_status":{"type":"string","enum":["in_progress","completed","error"]},"build_status":{"type":"string","enum":["in_progress","completed","error"]},"deploy_status":{"type":"string","enum":["in_progress","completed","error"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"asset_manifest":{"type":"object","nullable":true,"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Release not found"},"500":{"description":"Server error"}}},"delete":{"tags":["Releases"],"summary":"Delete Release","description":"Deletes 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/{release_id}/versions":{"get":{"tags":["Releases"],"summary":"List Release Versions","description":"Returns paginated file version data associated with a release.","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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"path":{"type":"string"},"entity":{"type":"string","format":"uuid"},"date":{"type":"string"},"data":{"type":"string"},"user_id":{"type":"string","format":"uuid"}},"required":["id","path","date","data"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Release not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{version}/asset-manifest/builds":{"post":{"tags":["Releases"],"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 (e.g. \"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/assets":{"post":{"tags":["Releases"],"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 (e.g. \"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":"Hash mismatch or invalid request"},"401":{"description":"Unauthorized"},"404":{"description":"Project or release not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{version}/asset-manifest":{"put":{"tags":["Releases"],"summary":"Put Release Asset Manifest","description":"Validates 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 (e.g. \"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"}}},"get":{"tags":["Releases"],"summary":"Get Release Asset Manifest","description":"Returns 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 (e.g. \"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","nullable":true,"additionalProperties":{"nullable":true}}},"required":["state","manifest_version","manifest"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project, release, or manifest not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/releases/{version}/asset-manifest/state":{"post":{"tags":["Releases"],"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 (e.g. \"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}/users":{"get":{"tags":["Members"],"summary":"List Project Users","description":"Get all users of a project with their roles.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination (user ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"project_role":{"type":"string"},"avatar_src":{"type":"string","nullable":true},"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/users/{user_id}":{"get":{"tags":["Members"],"summary":"Get Project User","description":"Get details of a specific project user.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"responses":{"200":{"description":"Member details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"project_role":{"type":"string"},"avatar_src":{"type":"string","nullable":true},"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Project or member not found"},"500":{"description":"Server error"}}},"delete":{"tags":["Members"],"summary":"Delete Project User","description":"Removes a user from the project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"responses":{"204":{"description":"Member removed successfully"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Project or user not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/users/{user_id}/role":{"patch":{"tags":["Project Users"],"summary":"Update Project User Role","description":"Updates a project member role. Use the ownership transfer endpoint for owner changes.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"project_role":{"type":"string"},"avatar_src":{"type":"string","nullable":true},"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Project or user not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/users/{user_id}/transfer-ownership":{"post":{"tags":["Project Users"],"summary":"Transfer Project Ownership","description":"Transfers project ownership to an existing project member.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"user_id","in":"path"}],"responses":{"200":{"description":"Project ownership transferred successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"project_role":{"type":"string"},"avatar_src":{"type":"string","nullable":true},"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Project or user not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/invites":{"get":{"tags":["Members"],"summary":"List Project Invites","description":"Get all pending invites for a project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination (invite ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":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","nullable":true}},"required":["id","email","role","project_id"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"tags":["Members"],"summary":"Create Project Invite","description":"Creates a pending invite for a project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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":"Invite created successfully","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","nullable":true}},"required":["id","email","role","project_id"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/invites/{invite_id}":{"get":{"tags":["Members"],"summary":"Get Project Invite","description":"Get details of a specific invite.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true}},"required":["id","email","role","project_id"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Invite not found"},"500":{"description":"Server error"}}},"delete":{"tags":["Members"],"summary":"Delete Project Invite","description":"Deletes a pending project invite.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"invite_id","in":"path"}],"responses":{"204":{"description":"Invite deleted successfully"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Invite not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/invites/{invite_id}/resend":{"post":{"tags":["Project Users"],"summary":"Resend Project Invite","description":"Re-sends an existing pending project invite without creating a duplicate invite.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"invite_id","in":"path"}],"responses":{"200":{"description":"Invite re-sent successfully","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","nullable":true}},"required":["id","email","role","project_id"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Invite not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/channels":{"get":{"tags":["Channels"],"summary":"List Channel Bindings","description":"Lists channel bindings for a project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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","nullable":true,"format":"uuid"},"platform":{"type":"string","enum":["slack"]},"name":{"type":"string","nullable":true},"assistant_id":{"type":"string","nullable":true,"minLength":1},"enabled":{"type":"boolean"},"platform_team_id":{"type":"string","nullable":true},"platform_bot_id":{"type":"string","nullable":true},"workspace_name":{"type":"string","nullable":true},"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","nullable":true},"error_message":{"type":"string","nullable":true},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"resolved_environment":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true}},"required":["id","name"]},"resolved_branch":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"resolved_deployment":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"runtime_version":{"type":"string","nullable":true},"deployment_revision":{"type":"string","nullable":true},"last_deployed_at":{"type":"string","nullable":true}},"required":["id","runtime_version","deployment_revision","last_deployed_at"]},"resolved_managed_domain":{"type":"object","nullable":true,"properties":{"domain":{"type":"string"},"health_url":{"type":"string","nullable":true}},"required":["domain","health_url"]},"resolved_invoke_mode":{"type":"string","nullable":true,"enum":["dispatch_override","managed_domain"]},"last_resolution_error":{"type":"object","nullable":true,"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":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"post":{"tags":["Channels"],"summary":"Create Channel Binding","description":"Creates a new channel binding for a project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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","nullable":true,"maxLength":4000},"error_message":{"type":"string","nullable":true,"maxLength":4000},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":65536},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["platform","assistant_id"]}}}},"responses":{"201":{"description":"Created channel binding","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"binding_id":{"type":"string","format":"uuid"},"installation_id":{"type":"string","nullable":true,"format":"uuid"},"platform":{"type":"string","enum":["slack"]},"name":{"type":"string","nullable":true},"assistant_id":{"type":"string","nullable":true,"minLength":1},"enabled":{"type":"boolean"},"platform_team_id":{"type":"string","nullable":true},"platform_bot_id":{"type":"string","nullable":true},"workspace_name":{"type":"string","nullable":true},"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","nullable":true},"error_message":{"type":"string","nullable":true},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"resolved_environment":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true}},"required":["id","name"]},"resolved_branch":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"resolved_deployment":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"runtime_version":{"type":"string","nullable":true},"deployment_revision":{"type":"string","nullable":true},"last_deployed_at":{"type":"string","nullable":true}},"required":["id","runtime_version","deployment_revision","last_deployed_at"]},"resolved_managed_domain":{"type":"object","nullable":true,"properties":{"domain":{"type":"string"},"health_url":{"type":"string","nullable":true}},"required":["domain","health_url"]},"resolved_invoke_mode":{"type":"string","nullable":true,"enum":["dispatch_override","managed_domain"]},"last_resolution_error":{"type":"object","nullable":true,"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"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/channels/assistants":{"get":{"tags":["Channels"],"summary":"List Target Assistants","description":"Lists assistants for the selected channel target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","enum":["main_branch","environment","preview_branch"],"default":"main_branch"},"required":false,"name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"format":"uuid"},"required":false,"name":"target_environment_id","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true},"model":{"type":"string","nullable":true}},"required":["id","name"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/channels/slack/conversations":{"get":{"tags":["Channels"],"summary":"List Slack Channels","description":"Lists public and private Slack channels available to the connected Slack app.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","maxLength":255},"required":false,"name":"query","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/channels/{platform}/test":{"post":{"tags":["Channels"],"summary":"Send Platform Test Message","description":"Sends a test message through the platform compatibility route.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true}},"required":["ok","channel_id","ts"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/channels/bindings/{binding_id}/test":{"post":{"tags":["Channels"],"summary":"Send Binding Test Message","description":"Sends a test message through a specific channel binding.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true}},"required":["ok","channel_id","ts"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/channels/{platform}":{"get":{"tags":["Channels"],"summary":"Get Platform Channel Binding","description":"Returns the channel binding for a platform compatibility route.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","enum":["slack"]},"required":true,"name":"platform","in":"path"}],"responses":{"200":{"description":"Channel binding","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"binding_id":{"type":"string","format":"uuid"},"installation_id":{"type":"string","nullable":true,"format":"uuid"},"platform":{"type":"string","enum":["slack"]},"name":{"type":"string","nullable":true},"assistant_id":{"type":"string","nullable":true,"minLength":1},"enabled":{"type":"boolean"},"platform_team_id":{"type":"string","nullable":true},"platform_bot_id":{"type":"string","nullable":true},"workspace_name":{"type":"string","nullable":true},"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","nullable":true},"error_message":{"type":"string","nullable":true},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"resolved_environment":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true}},"required":["id","name"]},"resolved_branch":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"resolved_deployment":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"runtime_version":{"type":"string","nullable":true},"deployment_revision":{"type":"string","nullable":true},"last_deployed_at":{"type":"string","nullable":true}},"required":["id","runtime_version","deployment_revision","last_deployed_at"]},"resolved_managed_domain":{"type":"object","nullable":true,"properties":{"domain":{"type":"string"},"health_url":{"type":"string","nullable":true}},"required":["domain","health_url"]},"resolved_invoke_mode":{"type":"string","nullable":true,"enum":["dispatch_override","managed_domain"]},"last_resolution_error":{"type":"object","nullable":true,"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"patch":{"tags":["Channels"],"summary":"Update Platform Channel Binding","description":"Updates the channel binding for a platform compatibility route.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"maxLength":4000},"error_message":{"type":"string","nullable":true,"maxLength":4000},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":65536},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}}}}}},"responses":{"200":{"description":"Updated channel binding","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"binding_id":{"type":"string","format":"uuid"},"installation_id":{"type":"string","nullable":true,"format":"uuid"},"platform":{"type":"string","enum":["slack"]},"name":{"type":"string","nullable":true},"assistant_id":{"type":"string","nullable":true,"minLength":1},"enabled":{"type":"boolean"},"platform_team_id":{"type":"string","nullable":true},"platform_bot_id":{"type":"string","nullable":true},"workspace_name":{"type":"string","nullable":true},"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","nullable":true},"error_message":{"type":"string","nullable":true},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"resolved_environment":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true}},"required":["id","name"]},"resolved_branch":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"resolved_deployment":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"runtime_version":{"type":"string","nullable":true},"deployment_revision":{"type":"string","nullable":true},"last_deployed_at":{"type":"string","nullable":true}},"required":["id","runtime_version","deployment_revision","last_deployed_at"]},"resolved_managed_domain":{"type":"object","nullable":true,"properties":{"domain":{"type":"string"},"health_url":{"type":"string","nullable":true}},"required":["domain","health_url"]},"resolved_invoke_mode":{"type":"string","nullable":true,"enum":["dispatch_override","managed_domain"]},"last_resolution_error":{"type":"object","nullable":true,"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"delete":{"tags":["Channels"],"summary":"Delete Platform Channel Binding","description":"Deletes the channel binding for a platform compatibility route.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/channels/bindings/{binding_id}":{"get":{"tags":["Channels"],"summary":"Get Channel Binding","description":"Returns a single channel binding for the project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"binding_id","in":"path"}],"responses":{"200":{"description":"Channel binding","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"binding_id":{"type":"string","format":"uuid"},"installation_id":{"type":"string","nullable":true,"format":"uuid"},"platform":{"type":"string","enum":["slack"]},"name":{"type":"string","nullable":true},"assistant_id":{"type":"string","nullable":true,"minLength":1},"enabled":{"type":"boolean"},"platform_team_id":{"type":"string","nullable":true},"platform_bot_id":{"type":"string","nullable":true},"workspace_name":{"type":"string","nullable":true},"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","nullable":true},"error_message":{"type":"string","nullable":true},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"resolved_environment":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true}},"required":["id","name"]},"resolved_branch":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"resolved_deployment":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"runtime_version":{"type":"string","nullable":true},"deployment_revision":{"type":"string","nullable":true},"last_deployed_at":{"type":"string","nullable":true}},"required":["id","runtime_version","deployment_revision","last_deployed_at"]},"resolved_managed_domain":{"type":"object","nullable":true,"properties":{"domain":{"type":"string"},"health_url":{"type":"string","nullable":true}},"required":["domain","health_url"]},"resolved_invoke_mode":{"type":"string","nullable":true,"enum":["dispatch_override","managed_domain"]},"last_resolution_error":{"type":"object","nullable":true,"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"patch":{"tags":["Channels"],"summary":"Update Channel Binding","description":"Updates a specific channel binding.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"maxLength":4000},"error_message":{"type":"string","nullable":true,"maxLength":4000},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"maximum":65536},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}}}}}},"responses":{"200":{"description":"Updated channel binding","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"binding_id":{"type":"string","format":"uuid"},"installation_id":{"type":"string","nullable":true,"format":"uuid"},"platform":{"type":"string","enum":["slack"]},"name":{"type":"string","nullable":true},"assistant_id":{"type":"string","nullable":true,"minLength":1},"enabled":{"type":"boolean"},"platform_team_id":{"type":"string","nullable":true},"platform_bot_id":{"type":"string","nullable":true},"workspace_name":{"type":"string","nullable":true},"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","nullable":true},"error_message":{"type":"string","nullable":true},"max_response_tokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"resolved_environment":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true}},"required":["id","name"]},"resolved_branch":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"resolved_deployment":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"runtime_version":{"type":"string","nullable":true},"deployment_revision":{"type":"string","nullable":true},"last_deployed_at":{"type":"string","nullable":true}},"required":["id","runtime_version","deployment_revision","last_deployed_at"]},"resolved_managed_domain":{"type":"object","nullable":true,"properties":{"domain":{"type":"string"},"health_url":{"type":"string","nullable":true}},"required":["domain","health_url"]},"resolved_invoke_mode":{"type":"string","nullable":true,"enum":["dispatch_override","managed_domain"]},"last_resolution_error":{"type":"object","nullable":true,"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"delete":{"tags":["Channels"],"summary":"Delete Channel Binding","description":"Deletes a specific channel binding.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/webhooks":{"get":{"tags":["Webhooks"],"summary":"List Project Webhooks","description":"Lists minimal webhook definitions for a project automation panel.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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 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","nullable":true,"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","nullable":true},"event_filter":{"type":"object","nullable":true,"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":{"nullable":true}},"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid"},"enabled_at":{"type":"string","nullable":true},"disabled_at":{"type":"string","nullable":true},"disabled_reason":{"type":"string","nullable":true},"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"]}},"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","nullable":true,"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","nullable":true,"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","nullable":true,"description":"The prompt template associated with this record."},"event_filter":{"nullable":true,"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["webhooks"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"post":{"tags":["Webhooks"],"summary":"Create Project Webhook","description":"Creates 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","nullable":true,"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","nullable":true,"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":{"nullable":true}},"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","nullable":true,"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","nullable":true},"event_filter":{"type":"object","nullable":true,"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":{"nullable":true}},"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid"},"enabled_at":{"type":"string","nullable":true},"disabled_at":{"type":"string","nullable":true},"disabled_reason":{"type":"string","nullable":true},"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":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/webhooks/{webhook_definition_id}/events/{webhook_event_id}/replay":{"post":{"tags":["Webhooks"],"summary":"Replay Project Webhook Event","description":"Creates 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":{"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","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string","nullable":true},"canonical_run_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","nullable":true,"minimum":0},"status":{"type":"string"},"duplicate":{"type":"boolean"},"payload":{"nullable":true},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"invoked_by":{"type":"string","nullable":true},"manual_invoked_by_user_id":{"type":"string","nullable":true,"format":"uuid"},"received_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"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"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/webhooks/{webhook_definition_id}":{"get":{"tags":["Webhooks"],"summary":"Get Project Webhook","description":"Returns 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","nullable":true,"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","nullable":true},"event_filter":{"type":"object","nullable":true,"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":{"nullable":true}},"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid"},"enabled_at":{"type":"string","nullable":true},"disabled_at":{"type":"string","nullable":true},"disabled_reason":{"type":"string","nullable":true},"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"patch":{"tags":["Webhooks"],"summary":"Update Project Webhook","description":"Updates 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","nullable":true,"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","nullable":true,"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":{"nullable":true}},"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","nullable":true,"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","nullable":true},"event_filter":{"type":"object","nullable":true,"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":{"nullable":true}},"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"created_by_user_id":{"type":"string","format":"uuid"},"enabled_at":{"type":"string","nullable":true},"disabled_at":{"type":"string","nullable":true},"disabled_reason":{"type":"string","nullable":true},"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":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete Project Webhook","description":"Deletes 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":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/webhooks/{webhook_definition_id}/runs":{"get":{"tags":["Webhooks"],"summary":"List Project Webhook Runs","description":"Returns the persisted webhook run/event history for a webhook definition, newest first.","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 runs","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"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","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string","nullable":true},"canonical_run_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","nullable":true,"minimum":0},"status":{"type":"string"},"duplicate":{"type":"boolean"},"payload":{"nullable":true},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"invoked_by":{"type":"string","nullable":true},"manual_invoked_by_user_id":{"type":"string","nullable":true,"format":"uuid"},"received_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"}},"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","created_at"]}}},"required":["runs"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/webhooks/{webhook_definition_id}/run":{"post":{"tags":["Webhooks"],"summary":"Run Project Webhook","description":"Runs a webhook for an authenticated automation invocation. Agent targets run headlessly by default, or create/append a conversation message when configured with create_new or existing conversation mode.","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":{"payload":{"nullable":true}},"additionalProperties":false}}}},"responses":{"202":{"description":"Webhook run accepted","content":{"application/json":{"schema":{"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","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string","nullable":true},"canonical_run_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","nullable":true,"minimum":0},"status":{"type":"string"},"duplicate":{"type":"boolean"},"payload":{"nullable":true},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"invoked_by":{"type":"string","nullable":true},"manual_invoked_by_user_id":{"type":"string","nullable":true,"format":"uuid"},"received_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"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"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/images/generate":{"post":{"tags":["Images"],"summary":"Generate Project Images","description":"Generate AI images using Cloudflare AI with Flux Schnell model. Images are stored as project uploads and returned as API upload URLs.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":1000,"description":"Text description of the desired image (max 1000 characters)"},"count":{"type":"number","minimum":1,"maximum":10,"default":1,"description":"Number of images to generate (1-10, default: 1)"},"seed":{"type":"number","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":"Array of upload URLs for generated images. Successful generations resolve to project upload URLs; failures fall back to a placeholder image."},"count":{"type":"number","description":"Number of images successfully generated"}},"required":["sources","count"]}}}},"400":{"description":"Invalid input - prompt too long or invalid count"},"401":{"description":"Unauthorized"},"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"}}}},"/agents":{"get":{"tags":["Agents"],"summary":"List Accessible Agents","description":"Lists runnable agents the authenticated user can access across all projects visible through RAM. `page_info.next` is present only when matching agent results remain, never merely because additional projects exist. Use /agent-templates for the public template catalog.","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. Supported only with sort=+project_name, access=all, no kind or runtime_status filter, and a cursor from a search-compatible page; other combinations return 400 rather than silently searching a narrower candidate set."},"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","nullable":true},"avatar_url":{"type":"string","nullable":true,"format":"uri"},"kind":{"type":"string","enum":["source_project_agent","installed_project_agent"]},"source_type":{"type":"string","enum":["project","catalog_install"]},"can_run":{"type":"boolean","enum":[true]},"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","nullable":true},"runtime_target_kind":{"type":"string","nullable":true,"enum":["registered_push_service","pull_worker"]},"runtime_service_key":{"type":"string","nullable":true}},"required":["status","reason","runtime_target_kind","runtime_service_key"]},"model":{"type":"string","nullable":true},"url":{"type":"string"}},"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"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page of matching agents; null when no matching agents remain."},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/agent-templates":{"get":{"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","nullable":true,"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":"Search term matched (case-insensitive substring) against agent name, description, agent_id, and category_label. Matched against the catalog cache, so edits to template projects surface within ~60s.","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","nullable":true},"avatar_url":{"type":"string","nullable":true,"format":"uri"},"category_id":{"type":"string"},"category_label":{"type":"string"},"provider_name":{"type":"string"},"provider_url":{"type":"string","nullable":true,"format":"uri"},"model":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"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","nullable":true,"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","nullable":true}},"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","nullable":true,"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","nullable":true},"provider":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","nullable":true,"format":"uri"}},"required":["name","url"]},"version":{"type":"string","nullable":true},"runtime_mode":{"type":"string","enum":["push_service","pull_worker","none"]},"runtime_service_key":{"type":"string","nullable":true},"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","nullable":true}},"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":{"tags":["Agents"],"summary":"List Agents","description":"Lists agents from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"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","nullable":true},"runtime_target_kind":{"type":"string","nullable":true,"enum":["registered_push_service","pull_worker"]},"runtime_service_key":{"type":"string","nullable":true}},"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","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":"string","nullable":true},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Agents"],"summary":"Create Agent","description":"Creates an agent document.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"system_prompt":{"type":"string","minLength":1},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budget_tokens":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["enabled"],"additionalProperties":false},"temperature":{"type":"number","nullable":true,"minimum":0,"maximum":2},"max_steps":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"allowed_models":{"type":"array","items":{"type":"string","minLength":1}},"skill_ids":{"type":"array","items":{"type":"string","minLength":1}},"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"},"tool_ids":{"type":"array","items":{"type":"string","minLength":1}},"provider_tool_ids":{"type":"array","items":{"type":"string","minLength":1}},"suggestions":{"type":"array","nullable":true,"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","nullable":true,"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 config details associated with this record."},"avatar_url":{"type":"string","nullable":true,"format":"uri"},"security_enabled":{"type":"boolean"}},"required":["id","name","system_prompt"]}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budget_tokens":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["enabled"],"additionalProperties":false},"temperature":{"type":"number","nullable":true,"minimum":0,"maximum":2},"max_steps":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"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","nullable":true,"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 config details associated with this record."},"avatar_url":{"type":"string","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"security_enabled":{"type":"boolean","nullable":true,"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/agents/{agent_id}":{"get":{"tags":["Agents"],"summary":"Get Agent","description":"Returns an agent document.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Agent document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budget_tokens":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["enabled"],"additionalProperties":false},"temperature":{"type":"number","nullable":true,"minimum":0,"maximum":2},"max_steps":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"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","nullable":true,"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 config details associated with this record."},"avatar_url":{"type":"string","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"security_enabled":{"type":"boolean","nullable":true,"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"put":{"tags":["Agents"],"summary":"Update Agent","description":"Updates an agent document.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"system_prompt":{"type":"string","minLength":1},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budget_tokens":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["enabled"],"additionalProperties":false},"temperature":{"type":"number","nullable":true,"minimum":0,"maximum":2},"max_steps":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"allowed_models":{"type":"array","items":{"type":"string","minLength":1}},"skill_ids":{"type":"array","items":{"type":"string","minLength":1}},"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"},"tool_ids":{"type":"array","items":{"type":"string","minLength":1}},"provider_tool_ids":{"type":"array","items":{"type":"string","minLength":1}},"suggestions":{"type":"array","nullable":true,"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","nullable":true,"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 config details associated with this record."},"avatar_url":{"type":"string","nullable":true,"format":"uri"},"security_enabled":{"type":"boolean"},"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":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budget_tokens":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["enabled"],"additionalProperties":false},"temperature":{"type":"number","nullable":true,"minimum":0,"maximum":2},"max_steps":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"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","nullable":true,"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 config details associated with this record."},"avatar_url":{"type":"string","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"security_enabled":{"type":"boolean","nullable":true,"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}},"delete":{"tags":["Agents"],"summary":"Delete Agent","description":"Deletes an agent document.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"204":{"description":"Agent deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/agents/{agent_id}/avatar.svg":{"get":{"tags":["Agents"],"summary":"Get Agent Avatar SVG","description":"Returns the agent avatar SVG, rendered from the agent's persisted avatar config. Public for agents that live in configured template projects; otherwise requires project read access.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Agent not found","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/projects/{project_reference}/agents/{agent_id}/avatar":{"post":{"tags":["Agents"],"summary":"Generate Agent Avatar","description":"Generates an SVG avatar from config options, stores it as a project upload, and returns the API upload URL.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"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":"Agent avatar config options. Omit seed to reroll a new avatar. With an explicit seed, missing visual values default from the existing agent avatar config."}}}}}},"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":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/agents/{agent_id}/rename":{"post":{"tags":["Agents"],"summary":"Rename Agent","description":"Renames an agent to a new identifier. The rename rejects while the target identifier is occupied, while colocated capability files (such as agents/{agent_id}/SKILL.md) would be stranded under the old identifier, or while schedules or channel bindings still reference the agent. When the agent has a generated avatar, the avatar is first copied to the new identity and the renamed agent references the copy. The previous avatar upload and storage object are left in place because preview branches and immutable releases can still reference them; their cleanup is asynchronous, handled by the reference-aware avatar garbage collector once nothing references them anymore. Agent labels follow the renamed identifier.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true},"thinking":{"type":"object","properties":{"enabled":{"type":"boolean"},"budget_tokens":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["enabled"],"additionalProperties":false},"temperature":{"type":"number","nullable":true,"minimum":0,"maximum":2},"max_steps":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"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","nullable":true,"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 config details associated with this record."},"avatar_url":{"type":"string","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"security_enabled":{"type":"boolean","nullable":true,"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/agents/{agent_id}/install":{"post":{"tags":["Agents"],"summary":"Install Agent","description":"Installs a catalog agent into the project by creating or reusing an agent access grant.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true},"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","nullable":true},"runtime_target_kind":{"type":"string","nullable":true,"enum":["registered_push_service","pull_worker"]},"runtime_service_key":{"type":"string","nullable":true}},"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","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":"string","nullable":true},"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","nullable":true},"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","nullable":true},"runtime_target_kind":{"type":"string","nullable":true,"enum":["registered_push_service","pull_worker"]},"runtime_service_key":{"type":"string","nullable":true}},"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","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":"string","nullable":true},"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":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"delete":{"tags":["Agents"],"summary":"Uninstall Agent","description":"Revokes an installed catalog agent access grant from the project agent surface.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/agents/{agent_id}/install-selected":{"post":{"tags":["Agents"],"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":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"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","nullable":true},"runtime_target_kind":{"type":"string","nullable":true,"enum":["registered_push_service","pull_worker"]},"runtime_service_key":{"type":"string","nullable":true}},"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","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":"string","nullable":true},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"201":{"description":"Installed agent cards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"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","nullable":true},"runtime_target_kind":{"type":"string","nullable":true,"enum":["registered_push_service","pull_worker"]},"runtime_service_key":{"type":"string","nullable":true}},"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","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":"string","nullable":true},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/capabilities":{"get":{"tags":["Agents"],"summary":"Get Project Capabilities","description":"Returns project capabilities for the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"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","nullable":true},"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":{"nullable":true}}},"required":["type","name"],"title":"ControlPlaneTool"},{"type":"object","properties":{"type":{"type":"string","enum":["integration"]},"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","additionalProperties":{"nullable":true}}},"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","nullable":true},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"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","nullable":true,"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","nullable":true},"client_secret_env_var":{"type":"string","nullable":true}},"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","nullable":true,"enum":["project","user"]},"connected_count":{"type":"integer","nullable":true,"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","minimum":0,"exclusiveMinimum":true,"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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","nullable":true},"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"version":{"type":"string","nullable":true},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"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","nullable":true},"runtime_target_kind":{"type":"string","nullable":true,"enum":["registered_push_service","pull_worker"]},"runtime_service_key":{"type":"string","nullable":true}},"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","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":"string","nullable":true},"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":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/agents/{agent_id}/capabilities":{"get":{"tags":["Agents"],"summary":"Get Agent Capabilities","description":"Returns agent capabilities for the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Agent identifier"},"required":true,"name":"agent_id","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"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","nullable":true},"runtime_target_kind":{"type":"string","nullable":true,"enum":["registered_push_service","pull_worker"]},"runtime_service_key":{"type":"string","nullable":true}},"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","nullable":true,"format":"uri","description":"Absolute URL for this agent avatar. Null when no custom avatar has been set."},"x-veryfront-model":{"type":"string","nullable":true},"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","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","target_environment_id","target_branch_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"]},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"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","nullable":true},"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":{"nullable":true}}},"required":["type","name"],"title":"ControlPlaneTool"},{"type":"object","properties":{"type":{"type":"string","enum":["integration"]},"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","additionalProperties":{"nullable":true}}},"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","nullable":true},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"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","nullable":true,"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","nullable":true},"client_secret_env_var":{"type":"string","nullable":true}},"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","nullable":true,"enum":["project","user"]},"connected_count":{"type":"integer","nullable":true,"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","minimum":0,"exclusiveMinimum":true,"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.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.domains.write","project.environments.manage","project.env_vars.write","project.runs.read","project.runs.write","project.agents.read","project.agents.write","project.evals.read","project.evals.write","project.evals.run","project.conversations.read","project.conversations.write","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","nullable":true},"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"version":{"type":"string","nullable":true},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"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":{"nullable":true}}},"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":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/skills":{"get":{"tags":["Skills"],"summary":"List Skills","description":"Lists skills from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Skills"],"summary":"Create Skill","description":"Creates a structured skill document in the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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":"Full markdown body of SKILL.md — everything below the frontmatter."},"source":{"type":"string","minLength":1}},"required":["name","description"]}}}},"responses":{"201":{"description":"Created project skill document","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"},"instructions":{"type":"string","description":"Full markdown body of SKILL.md, below the frontmatter"},"sections":{"type":"object","additionalProperties":{"type":"string"},"description":"Read-only, best-effort projection of the body split on `## ` headings. Empty when the body is not section-addressable, and never authoritative — `instructions` is the body. Not writable."},"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/skills/{skill_id}":{"get":{"tags":["Skills"],"summary":"Get Skill","description":"Returns a skill from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Skill identifier"},"required":true,"name":"skill_id","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"put":{"tags":["Skills"],"summary":"Update Skill","description":"Updates a structured skill document in the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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":"Full markdown body of SKILL.md — everything below the frontmatter."},"source":{"type":"string","minLength":1}},"required":["description"]}}}},"responses":{"200":{"description":"Updated project skill document","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"},"instructions":{"type":"string","description":"Full markdown body of SKILL.md, below the frontmatter"},"sections":{"type":"object","additionalProperties":{"type":"string"},"description":"Read-only, best-effort projection of the body split on `## ` headings. Empty when the body is not section-addressable, and never authoritative — `instructions` is the body. Not writable."},"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}},"delete":{"tags":["Skills"],"summary":"Delete Skill","description":"Deletes a project skill source file from the selected source target, including source-only recovery files.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/skills/{skill_id}/source":{"get":{"tags":["Skills"],"summary":"Get Skill Source","description":"Returns the structured skill document from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Project skill document","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"},"instructions":{"type":"string","description":"Full markdown body of SKILL.md, below the frontmatter"},"sections":{"type":"object","additionalProperties":{"type":"string"},"description":"Read-only, best-effort projection of the body split on `## ` headings. Empty when the body is not section-addressable, and never authoritative — `instructions` is the body. Not writable."},"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/prompts":{"get":{"tags":["Prompts"],"summary":"List Prompts","description":"Lists prompts from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Prompts"],"summary":"Create Prompt","description":"Creates a structured prompt source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true},"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","nullable":true},"content":{"type":"string","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/prompts/{prompt_id}/source":{"get":{"tags":["Prompts"],"summary":"Get Prompt Source","description":"Returns the structured prompt document from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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","nullable":true},"content":{"type":"string","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/prompts/{prompt_id}":{"put":{"tags":["Prompts"],"summary":"Update Prompt","description":"Updates a structured prompt source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","nullable":true},"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","nullable":true},"content":{"type":"string","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}},"delete":{"tags":["Prompts"],"summary":"Delete Prompt","description":"Deletes a structured prompt source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Prompt deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}},"get":{"tags":["Prompts"],"summary":"Get Prompt","description":"Returns a prompt from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Prompt identifier"},"required":true,"name":"prompt_id","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/tools":{"get":{"tags":["Tools"],"summary":"List Tools","description":"Lists tools from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Tools"],"summary":"Create Tool","description":"Creates a structured tool source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true},"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/tools/{tool_id}/source":{"get":{"tags":["Tools"],"summary":"Get Tool Source","description":"Returns the structured tool document from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/tools/{tool_id}":{"get":{"tags":["Tools"],"summary":"Get Tool","description":"Returns a tool from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Tool identifier"},"required":true,"name":"tool_id","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["id","name","description","source_path","edit_mode","input_schema","output_schema"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"put":{"tags":["Tools"],"summary":"Update Tool","description":"Updates a structured tool source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","nullable":true},"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}},"delete":{"tags":["Tools"],"summary":"Delete Tool","description":"Deletes a structured tool source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Tool deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/tasks":{"get":{"tags":["Tasks"],"summary":"List Tasks","description":"Lists tasks from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Tasks"],"summary":"Create Task","description":"Creates a structured task source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true},"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/tasks/{task_id}":{"get":{"tags":["Tasks"],"summary":"Get Task","description":"Returns a task from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Task identifier"},"required":true,"name":"task_id","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"schedulable":{"type":"boolean"}},"required":["id","name","description","target","source_path","edit_mode","input_schema","output_schema","schedulable"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"put":{"tags":["Tasks"],"summary":"Update Task","description":"Updates a structured task source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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","nullable":true},"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}},"delete":{"tags":["Tasks"],"summary":"Delete Task","description":"Deletes a structured task source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Task deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/tasks/{task_id}/source":{"get":{"tags":["Tasks"],"summary":"Get Task Source","description":"Returns the structured task document from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Task document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/evals":{"get":{"tags":["Evals"],"summary":"List Evals","description":"Lists source-backed eval definitions from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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":{"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":{"nullable":true},"reference":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"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":{"nullable":true}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["name","family","severity","editable","dynamic"]}},"repetitions":{"type":"integer","minimum":0,"exclusiveMinimum":true},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"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"]}},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Evals"],"summary":"Create Eval","description":"Creates a structured eval source document in the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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"},"input":{"nullable":true},"reference":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id"]}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["kind","editable","dynamic"]},"repetitions":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"tags":{"type":"array","items":{"type":"string"},"default":[]},"metadata":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"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":{"nullable":true}},"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":{"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":{"nullable":true},"reference":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"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":{"nullable":true}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["name","family","severity","editable","dynamic"]}},"repetitions":{"type":"integer","minimum":0,"exclusiveMinimum":true},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/evals/{eval_id}/source":{"get":{"tags":["Evals"],"summary":"Get Eval Source","description":"Returns an eval source document and editable source content.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"eval_id","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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":{"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":{"nullable":true},"reference":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"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":{"nullable":true}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["name","family","severity","editable","dynamic"]}},"repetitions":{"type":"integer","minimum":0,"exclusiveMinimum":true},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"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"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"patch":{"tags":["Evals"],"summary":"Update Eval Source","description":"Updates a structured eval source document.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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"},"description":{"type":"string"},"target":{"type":"string"},"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":{"nullable":true},"reference":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id"]}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["kind","editable","dynamic"]},"repetitions":{"type":"integer","minimum":0,"exclusiveMinimum":true},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"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":{"nullable":true}},"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":{"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":{"nullable":true},"reference":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"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":{"nullable":true}},"editable":{"type":"boolean"},"dynamic":{"type":"boolean"}},"required":["name","family","severity","editable","dynamic"]}},"repetitions":{"type":"integer","minimum":0,"exclusiveMinimum":true},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"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"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/evals/{eval_id}/runs":{"get":{"tags":["Evals"],"summary":"List Eval Runs","description":"Lists eval run projections for an eval definition.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"eval_id","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100},"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":"Eval runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["eval-run"]},"runId":{"type":"string"},"evalId":{"type":"string"},"status":{"type":"string","enum":["pending","running","waiting","completed","failed","cancelled"]},"targetKind":{"type":"string","enum":["agent"]},"target":{"type":"string"},"source":{"type":"object","properties":{"filePath":{"type":"string"},"exportName":{"type":"string"},"content":{"type":"string"}},"required":["filePath","exportName"]},"summary":{"type":"object","nullable":true,"properties":{"records":{"type":"number"},"passed":{"type":"number"},"failed":{"type":"number"},"skippedResults":{"type":"number"},"passRate":{"type":"number"},"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"]},"passed":{"type":"number"},"failed":{"type":"number"},"skipped":{"type":"number"},"passRate":{"type":"number"}},"required":["name","family","severity","passed","failed","skipped","passRate"]}},"duration":{"type":"object","properties":{"totalMs":{"type":"number"},"minMs":{"type":"number"},"maxMs":{"type":"number"},"meanMs":{"type":"number"},"p50Ms":{"type":"number"},"p95Ms":{"type":"number"}},"required":["totalMs","minMs","maxMs","meanMs","p50Ms","p95Ms"]},"usage":{"type":"object","properties":{"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"billableInputTokens":{"type":"number"},"billableOutputTokens":{"type":"number"},"billableCacheCreationInputTokens":{"type":"number"},"billableCacheReadInputTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"cacheCreationInputTokens":{"type":"number"},"cacheReadInputTokens":{"type":"number"},"reasoningTokens":{"type":"number"},"costUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerOutputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCacheCreationInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCacheReadInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontOutputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontCacheCreationInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontCacheReadInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontBilledUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"costCredits":{"anyOf":[{"type":"string"},{"type":"number"}]},"costSource":{"type":"string","enum":["gateway","missing","partial"]},"billingMode":{"type":"string","enum":["direct","deferred"]},"usageCaptureStatus":{"type":"string","enum":["complete","partial","missing"]}}},"gateFailures":{"type":"array","items":{"type":"object","properties":{"recordId":{"type":"string"},"exampleId":{"type":"string"},"repetition":{"type":"number"},"name":{"type":"string"},"family":{"type":"string","enum":["answer","agent","ops","judge","knowledge","check"]},"severity":{"type":"string","enum":["gate","budget"]},"explanation":{"type":"string"},"evidence":{"type":"object","additionalProperties":{"nullable":true}}},"required":["recordId","exampleId","repetition","name","family","severity"]}},"failedExamples":{"type":"array","items":{"type":"object","properties":{"exampleId":{"type":"string"},"records":{"type":"number"},"passed":{"type":"number"},"failed":{"type":"number"},"passRate":{"type":"number"},"flaky":{"type":"boolean"}},"required":["exampleId","records","passed","failed","passRate","flaky"]}},"flakes":{"type":"object","properties":{"examples":{"type":"number"},"stablePassed":{"type":"number"},"stableFailed":{"type":"number"},"flaky":{"type":"number"}},"required":["examples","stablePassed","stableFailed","flaky"]}},"required":["records","passed","failed","passRate","metrics"]},"reportPath":{"type":"string","nullable":true},"error":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"},"startedAt":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true}},"required":["kind","runId","evalId","status","targetKind","target","summary","reportPath","metadata","createdAt","startedAt","completedAt"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Evals"],"summary":"Run Eval","description":"Starts an eval run for a source-backed eval definition. A JSON body is required — send `{}` when there is no input or config to pass — because the run guard rejects requests that do not declare the application/json content type.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"eval_id","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","additionalProperties":{"nullable":true}},"config":{"type":"object","additionalProperties":{"nullable":true}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Eval run","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["eval-run"]},"runId":{"type":"string"},"evalId":{"type":"string"},"status":{"type":"string","enum":["pending","running","waiting","completed","failed","cancelled"]},"targetKind":{"type":"string","enum":["agent"]},"target":{"type":"string"},"source":{"type":"object","properties":{"filePath":{"type":"string"},"exportName":{"type":"string"},"content":{"type":"string"}},"required":["filePath","exportName"]},"summary":{"type":"object","nullable":true,"properties":{"records":{"type":"number"},"passed":{"type":"number"},"failed":{"type":"number"},"skippedResults":{"type":"number"},"passRate":{"type":"number"},"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"]},"passed":{"type":"number"},"failed":{"type":"number"},"skipped":{"type":"number"},"passRate":{"type":"number"}},"required":["name","family","severity","passed","failed","skipped","passRate"]}},"duration":{"type":"object","properties":{"totalMs":{"type":"number"},"minMs":{"type":"number"},"maxMs":{"type":"number"},"meanMs":{"type":"number"},"p50Ms":{"type":"number"},"p95Ms":{"type":"number"}},"required":["totalMs","minMs","maxMs","meanMs","p50Ms","p95Ms"]},"usage":{"type":"object","properties":{"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"billableInputTokens":{"type":"number"},"billableOutputTokens":{"type":"number"},"billableCacheCreationInputTokens":{"type":"number"},"billableCacheReadInputTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"cacheCreationInputTokens":{"type":"number"},"cacheReadInputTokens":{"type":"number"},"reasoningTokens":{"type":"number"},"costUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerOutputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCacheCreationInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCacheReadInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontOutputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontCacheCreationInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontCacheReadInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontBilledUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"costCredits":{"anyOf":[{"type":"string"},{"type":"number"}]},"costSource":{"type":"string","enum":["gateway","missing","partial"]},"billingMode":{"type":"string","enum":["direct","deferred"]},"usageCaptureStatus":{"type":"string","enum":["complete","partial","missing"]}}},"gateFailures":{"type":"array","items":{"type":"object","properties":{"recordId":{"type":"string"},"exampleId":{"type":"string"},"repetition":{"type":"number"},"name":{"type":"string"},"family":{"type":"string","enum":["answer","agent","ops","judge","knowledge","check"]},"severity":{"type":"string","enum":["gate","budget"]},"explanation":{"type":"string"},"evidence":{"type":"object","additionalProperties":{"nullable":true}}},"required":["recordId","exampleId","repetition","name","family","severity"]}},"failedExamples":{"type":"array","items":{"type":"object","properties":{"exampleId":{"type":"string"},"records":{"type":"number"},"passed":{"type":"number"},"failed":{"type":"number"},"passRate":{"type":"number"},"flaky":{"type":"boolean"}},"required":["exampleId","records","passed","failed","passRate","flaky"]}},"flakes":{"type":"object","properties":{"examples":{"type":"number"},"stablePassed":{"type":"number"},"stableFailed":{"type":"number"},"flaky":{"type":"number"}},"required":["examples","stablePassed","stableFailed","flaky"]}},"required":["records","passed","failed","passRate","metrics"]},"reportPath":{"type":"string","nullable":true},"error":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"},"startedAt":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true}},"required":["kind","runId","evalId","status","targetKind","target","summary","reportPath","metadata","createdAt","startedAt","completedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/evals/{eval_id}/runs/{run_id}":{"get":{"tags":["Evals"],"summary":"Get Eval Run","description":"Returns a single eval run projection for an eval definition.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"eval_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"responses":{"200":{"description":"Eval run","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["eval-run"]},"runId":{"type":"string"},"evalId":{"type":"string"},"status":{"type":"string","enum":["pending","running","waiting","completed","failed","cancelled"]},"targetKind":{"type":"string","enum":["agent"]},"target":{"type":"string"},"source":{"type":"object","properties":{"filePath":{"type":"string"},"exportName":{"type":"string"},"content":{"type":"string"}},"required":["filePath","exportName"]},"summary":{"type":"object","nullable":true,"properties":{"records":{"type":"number"},"passed":{"type":"number"},"failed":{"type":"number"},"skippedResults":{"type":"number"},"passRate":{"type":"number"},"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"]},"passed":{"type":"number"},"failed":{"type":"number"},"skipped":{"type":"number"},"passRate":{"type":"number"}},"required":["name","family","severity","passed","failed","skipped","passRate"]}},"duration":{"type":"object","properties":{"totalMs":{"type":"number"},"minMs":{"type":"number"},"maxMs":{"type":"number"},"meanMs":{"type":"number"},"p50Ms":{"type":"number"},"p95Ms":{"type":"number"}},"required":["totalMs","minMs","maxMs","meanMs","p50Ms","p95Ms"]},"usage":{"type":"object","properties":{"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"billableInputTokens":{"type":"number"},"billableOutputTokens":{"type":"number"},"billableCacheCreationInputTokens":{"type":"number"},"billableCacheReadInputTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"cacheCreationInputTokens":{"type":"number"},"cacheReadInputTokens":{"type":"number"},"reasoningTokens":{"type":"number"},"costUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerOutputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCacheCreationInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCacheReadInputCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"providerCostUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontOutputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontCacheCreationInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontCacheReadInputChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontChargeUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"veryfrontBilledUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"costCredits":{"anyOf":[{"type":"string"},{"type":"number"}]},"costSource":{"type":"string","enum":["gateway","missing","partial"]},"billingMode":{"type":"string","enum":["direct","deferred"]},"usageCaptureStatus":{"type":"string","enum":["complete","partial","missing"]}}},"gateFailures":{"type":"array","items":{"type":"object","properties":{"recordId":{"type":"string"},"exampleId":{"type":"string"},"repetition":{"type":"number"},"name":{"type":"string"},"family":{"type":"string","enum":["answer","agent","ops","judge","knowledge","check"]},"severity":{"type":"string","enum":["gate","budget"]},"explanation":{"type":"string"},"evidence":{"type":"object","additionalProperties":{"nullable":true}}},"required":["recordId","exampleId","repetition","name","family","severity"]}},"failedExamples":{"type":"array","items":{"type":"object","properties":{"exampleId":{"type":"string"},"records":{"type":"number"},"passed":{"type":"number"},"failed":{"type":"number"},"passRate":{"type":"number"},"flaky":{"type":"boolean"}},"required":["exampleId","records","passed","failed","passRate","flaky"]}},"flakes":{"type":"object","properties":{"examples":{"type":"number"},"stablePassed":{"type":"number"},"stableFailed":{"type":"number"},"flaky":{"type":"number"}},"required":["examples","stablePassed","stableFailed","flaky"]}},"required":["records","passed","failed","passRate","metrics"]},"reportPath":{"type":"string","nullable":true},"error":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"},"startedAt":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true}},"required":["kind","runId","evalId","status","targetKind","target","summary","reportPath","metadata","createdAt","startedAt","completedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/evals/{eval_id}/runs/{run_id}/report":{"get":{"tags":["Evals"],"summary":"Get Eval Run Report","description":"Returns the persisted eval report artifact for an eval run.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"eval_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"responses":{"200":{"description":"Eval report","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["eval-report"]}},"required":["kind"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Report not ready","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/workflows":{"get":{"tags":["Workflows"],"summary":"List Workflows","description":"Lists workflows from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"version":{"type":"string","nullable":true},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Workflows"],"summary":"Create Workflow","description":"Creates a structured workflow source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true},"version":{"type":"string","nullable":true},"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"version":{"type":"string","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/workflows/{workflow_id}":{"get":{"tags":["Workflows"],"summary":"Get Workflow","description":"Returns a workflow from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Workflow identifier"},"required":true,"name":"workflow_id","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"edit_mode":{"type":"string","enum":["structured","source_only"]},"version":{"type":"string","nullable":true},"input_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"output_schema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"schedulable":{"type":"boolean"}},"required":["id","name","description","target","source_path","edit_mode","version","input_schema","output_schema","schedulable"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"put":{"tags":["Workflows"],"summary":"Update Workflow","description":"Updates a structured workflow source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"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","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"version":{"type":"string","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}},"delete":{"tags":["Workflows"],"summary":"Delete Workflow","description":"Deletes a structured workflow source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Workflow deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/workflows/{workflow_id}/source":{"get":{"tags":["Workflows"],"summary":"Get Workflow Source","description":"Returns the structured workflow document from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Workflow document","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"target":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string"},"version":{"type":"string","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/schedules":{"get":{"tags":["Schedules"],"summary":"List Project Schedules","description":"Lists recurring project schedules that trigger task, workflow, or agent runs.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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"}],"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","nullable":true,"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"config":{"type":"object","additionalProperties":{"nullable":true}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"last_scheduled_at":{"type":"string","nullable":true},"last_successful_at":{"type":"string","nullable":true},"health":{"type":"object","nullable":true,"properties":{"maxStalenessSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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","nullable":true,"minimum":0,"exclusiveMinimum":true},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":"string","nullable":true},"paused_reason":{"type":"string","nullable":true},"paused_at":{"type":"string","nullable":true},"last_failure_at":{"type":"string","nullable":true},"last_failure_code":{"type":"string","nullable":true},"last_failure_message":{"type":"string","nullable":true},"last_failure_run_id":{"type":"string","nullable":true,"format":"uuid"},"created_by":{"type":"string","nullable":true,"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}},"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","nullable":true,"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","nullable":true,"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","nullable":true,"format":"uuid","description":"The runtime target environment id associated with this record."},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid","description":"The runtime target branch id associated with this record."},"config":{"type":"object","additionalProperties":{"nullable":true,"description":"Additional structured values associated with this result."},"description":"Structured config details associated with this record."},"timeout_seconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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","nullable":true,"minimum":0,"exclusiveMinimum":true,"description":"The max runs associated with this record."},"health":{"type":"object","nullable":true,"properties":{"maxStalenessSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["schedules"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"post":{"tags":["Schedules"],"summary":"Create Project Schedule","description":"Creates a recurring project schedule, active by default. Materializing a source-defined schedule may instead return the row that already carries its source trigger id, keeping that row's status — so a paused schedule is returned still 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","nullable":true,"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"config":{"type":"object","additionalProperties":{"nullable":true}},"timeout_seconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"backoff_limit":{"type":"integer","minimum":0},"concurrency_policy":{"type":"string","enum":["Allow","Forbid","Replace"]},"max_runs":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"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","nullable":true,"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"config":{"type":"object","additionalProperties":{"nullable":true}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"last_scheduled_at":{"type":"string","nullable":true},"last_successful_at":{"type":"string","nullable":true},"health":{"type":"object","nullable":true,"properties":{"maxStalenessSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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","nullable":true,"minimum":0,"exclusiveMinimum":true},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":"string","nullable":true},"paused_reason":{"type":"string","nullable":true},"paused_at":{"type":"string","nullable":true},"last_failure_at":{"type":"string","nullable":true},"last_failure_code":{"type":"string","nullable":true},"last_failure_message":{"type":"string","nullable":true},"last_failure_run_id":{"type":"string","nullable":true,"format":"uuid"},"created_by":{"type":"string","nullable":true,"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":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/projects/{project_reference}/schedules/{schedule_id}":{"get":{"tags":["Schedules"],"summary":"Get Project Schedule","description":"Returns 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","nullable":true,"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"config":{"type":"object","additionalProperties":{"nullable":true}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"last_scheduled_at":{"type":"string","nullable":true},"last_successful_at":{"type":"string","nullable":true},"health":{"type":"object","nullable":true,"properties":{"maxStalenessSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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","nullable":true,"minimum":0,"exclusiveMinimum":true},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":"string","nullable":true},"paused_reason":{"type":"string","nullable":true},"paused_at":{"type":"string","nullable":true},"last_failure_at":{"type":"string","nullable":true},"last_failure_code":{"type":"string","nullable":true},"last_failure_message":{"type":"string","nullable":true},"last_failure_run_id":{"type":"string","nullable":true,"format":"uuid"},"created_by":{"type":"string","nullable":true,"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}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"patch":{"tags":["Schedules"],"summary":"Update Project Schedule","description":"Updates 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","nullable":true,"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"config":{"type":"object","additionalProperties":{"nullable":true}},"timeout_seconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"backoff_limit":{"type":"integer","minimum":0},"concurrency_policy":{"type":"string","enum":["Allow","Forbid","Replace"]},"max_runs":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"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","nullable":true,"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"config":{"type":"object","additionalProperties":{"nullable":true}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"last_scheduled_at":{"type":"string","nullable":true},"last_successful_at":{"type":"string","nullable":true},"health":{"type":"object","nullable":true,"properties":{"maxStalenessSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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","nullable":true,"minimum":0,"exclusiveMinimum":true},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":"string","nullable":true},"paused_reason":{"type":"string","nullable":true},"paused_at":{"type":"string","nullable":true},"last_failure_at":{"type":"string","nullable":true},"last_failure_code":{"type":"string","nullable":true},"last_failure_message":{"type":"string","nullable":true},"last_failure_run_id":{"type":"string","nullable":true,"format":"uuid"},"created_by":{"type":"string","nullable":true,"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":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"delete":{"tags":["Schedules"],"summary":"Delete Project Schedule","description":"Marks a schedule as deleting 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","nullable":true,"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","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"config":{"type":"object","additionalProperties":{"nullable":true}},"timeout_seconds":{"type":"integer"},"backoff_limit":{"type":"integer"},"concurrency_policy":{"type":"string"},"definition_source":{"type":"string","enum":["manual","source"]},"source_trigger_id":{"type":"string","nullable":true},"source_path":{"type":"string","nullable":true},"source_hash":{"type":"string","nullable":true},"last_scheduled_at":{"type":"string","nullable":true},"last_successful_at":{"type":"string","nullable":true},"health":{"type":"object","nullable":true,"properties":{"maxStalenessSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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","nullable":true,"minimum":0,"exclusiveMinimum":true},"run_count":{"type":"integer","minimum":0},"completed_at":{"type":"string","nullable":true},"paused_reason":{"type":"string","nullable":true},"paused_at":{"type":"string","nullable":true},"last_failure_at":{"type":"string","nullable":true},"last_failure_code":{"type":"string","nullable":true},"last_failure_message":{"type":"string","nullable":true},"last_failure_run_id":{"type":"string","nullable":true,"format":"uuid"},"created_by":{"type":"string","nullable":true,"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/webhooks/channels/{platform}":{"post":{"tags":["Channels"],"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":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]},{"type":"object","properties":{"challenge":{"type":"string"}},"required":["challenge"]}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"Invalid signature or stale timestamp","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/webhooks/{webhook_id}":{"post":{"tags":["Webhooks"],"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":{"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","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string","nullable":true},"canonical_run_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","nullable":true,"minimum":0},"status":{"type":"string"},"duplicate":{"type":"boolean"},"payload":{"nullable":true},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"invoked_by":{"type":"string","nullable":true},"manual_invoked_by_user_id":{"type":"string","nullable":true,"format":"uuid"},"received_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"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"]}}}},"202":{"description":"Webhook accepted","content":{"application/json":{"schema":{"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","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string","nullable":true},"canonical_run_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","nullable":true,"minimum":0},"status":{"type":"string"},"duplicate":{"type":"boolean"},"payload":{"nullable":true},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"invoked_by":{"type":"string","nullable":true},"manual_invoked_by_user_id":{"type":"string","nullable":true,"format":"uuid"},"received_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"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"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Dedupe conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"499":{"description":"Client closed the request before its body was read"}}}},"/account/users":{"get":{"tags":["Account"],"summary":"List Account Users","description":"Aggregate 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","nullable":true,"format":"uuid"},"invite_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"avatar_src":{"type":"string","nullable":true},"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","nullable":true}},"required":["id","status","user_id","invite_ids","email","name","avatar_src","role","seat_status","projects"]}},"page_info":{"type":"object","properties":{"start_cursor":{"type":"string","nullable":true},"end_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"prev_cursor":{"type":"string","nullable":true},"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/invites":{"get":{"tags":["Account"],"summary":"List Account Invites","description":"Aggregate 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","nullable":true,"format":"uuid"},"invite_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"avatar_src":{"type":"string","nullable":true},"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","nullable":true}},"required":["id","status","user_id","invite_ids","email","name","avatar_src","role","seat_status","projects"]}},"page_info":{"type":"object","properties":{"start_cursor":{"type":"string","nullable":true},"end_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"prev_cursor":{"type":"string","nullable":true},"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/usage":{"get":{"tags":["Account"],"summary":"Get account usage overview","description":"Returns 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/series":{"get":{"tags":["Account"],"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","nullable":true,"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":"string","nullable":true,"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/credits":{"get":{"tags":["Account"],"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","nullable":true,"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":"string","nullable":true,"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","enum":["anthropic","openai","google","mistral","moonshotai","unknown"],"description":"Model provider, such as Anthropic, OpenAI, Google, Mistral, or Moonshot."},"inference_provider":{"type":"string","enum":["veryfront-cloud","unknown"],"description":"Inference provider handling the request, such as 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"]}}},"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/analytics/conversations":{"get":{"tags":["Account"],"summary":"Get account conversation analytics","description":"Returns account-level conversation counts, recency, volume, statuses, model usage, and project breakdowns. 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":"array","nullable":true,"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","nullable":true,"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","nullable":true,"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":"string","nullable":true,"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","nullable":true,"description":"Conversation title, if available."},"status":{"type":"string","description":"Conversation status."},"project_id":{"type":"string","nullable":true,"format":"uuid","description":"Owning project ID, if scoped."},"project_name":{"type":"string","description":"Owning project display name."},"project_slug":{"type":"string","nullable":true,"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"}}}},"/account/analytics/runs":{"get":{"tags":["Account"],"summary":"Get account run analytics","description":"Returns account-level run counts, outcomes, duration, model usage, tool usage, and project breakdowns. 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":"array","nullable":true,"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 run analytics statistics","content":{"application/json":{"schema":{"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","nullable":true,"description":"Average completed run duration in milliseconds."},"p95_duration_ms":{"type":"number","nullable":true,"description":"95th percentile completed run duration in milliseconds."},"last_run_at":{"type":"string","nullable":true,"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":"Tool name."},"count":{"type":"number","description":"Number of uses."}},"required":["name","count"]}},"projects":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":"string","nullable":true,"format":"uuid","description":"Project ID, or null for unscoped usage."},"project_name":{"type":"string","description":"Project display name."},"project_slug":{"type":"string","nullable":true,"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":{"type":"object","properties":{"run_id":{"type":"string","description":"Run public ID that can be opened in Studio."},"status":{"type":"string","description":"Run status."},"project_id":{"type":"string","nullable":true,"format":"uuid","description":"Owning project ID, if scoped."},"project_name":{"type":"string","description":"Owning project display name."},"project_slug":{"type":"string","nullable":true,"description":"Owning project slug for Studio deep links, if available."},"created_at":{"type":"string","description":"Run creation timestamp."}},"required":["run_id","status","project_id","project_name","project_slug","created_at"]}}},"required":["summary","timeframe","series","statuses","models","tools","projects","recent_runs"]}}}},"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":{"tags":["Account"],"summary":"Get account usage warnings","description":"Returns 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"}}}},"/account/usage/limits":{"get":{"tags":["Account"],"summary":"Get account usage limits","description":"Returns 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/billing-details":{"get":{"tags":["Account"],"summary":"Get billing details","description":"Returns 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","nullable":true},"email":{"type":"string","nullable":true,"format":"email"},"phone":{"type":"string","nullable":true},"address":{"type":"object","nullable":true,"properties":{"line1":{"type":"string","nullable":true},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"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","nullable":true}},"required":["id","type","value"]}}},"required":["name","email","phone","address","tax_ids"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}},"patch":{"tags":["Account"],"summary":"Update billing details","description":"Updates Stripe customer name, email, phone, and/or address.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true,"format":"email"},"phone":{"type":"string","nullable":true},"address":{"type":"object","nullable":true,"properties":{"line1":{"type":"string","nullable":true},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}}}}}}}},"responses":{"200":{"description":"Updated billing details","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true,"format":"email"},"phone":{"type":"string","nullable":true},"address":{"type":"object","nullable":true,"properties":{"line1":{"type":"string","nullable":true},"line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"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","nullable":true}},"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":{"tags":["Account"],"summary":"List billing invoices","description":"Lists 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","nullable":true},"status":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"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","nullable":true,"format":"uri"},"pdf_url":{"type":"string","nullable":true,"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":{"tags":["Account"],"summary":"List upcoming billing invoices","description":"Lists 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","nullable":true},"status":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"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","nullable":true,"format":"uri"},"pdf_url":{"type":"string","nullable":true,"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/payments":{"get":{"tags":["Account"],"summary":"List billing payments","description":"Lists 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","nullable":true},"paid":{"type":"boolean"},"amount":{"type":"number"},"currency":{"type":"string"},"created_at":{"type":"string"},"description":{"type":"string","nullable":true},"receipt_url":{"type":"string","nullable":true,"format":"uri"},"invoice_id":{"type":"string","nullable":true},"payment_intent_id":{"type":"string","nullable":true}},"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"}}}},"/account/payment-methods":{"get":{"tags":["Account"],"summary":"List payment methods","description":"Lists 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","nullable":true},"last4":{"type":"string","nullable":true},"exp_month":{"type":"number","nullable":true},"exp_year":{"type":"number","nullable":true},"is_default":{"type":"boolean"}},"required":["id","brand","last4","exp_month","exp_year","is_default"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}},"post":{"tags":["Account"],"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","nullable":true},"last4":{"type":"string","nullable":true},"exp_month":{"type":"number","nullable":true},"exp_year":{"type":"number","nullable":true},"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":{"tags":["Account"],"summary":"Set default payment method","description":"Sets 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","nullable":true},"last4":{"type":"string","nullable":true},"exp_month":{"type":"number","nullable":true},"exp_year":{"type":"number","nullable":true},"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":{"tags":["Account"],"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/subscription":{"get":{"tags":["Subscriptions"],"summary":"Get subscription","description":"Returns the current authenticated user subscription.","responses":{"200":{"description":"Subscription details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Subscription ID"},"user_id":{"type":"string","format":"uuid","description":"User that owns the subscription"},"project_id":{"type":"string","nullable":true,"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","nullable":true,"enum":["monthly","yearly"],"description":"Line item billing interval when price-classifiable"},"unit_amount":{"type":"number","nullable":true,"description":"Line item unit amount in minor currency units"},"currency":{"type":"string","nullable":true,"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","nullable":true,"description":"Current billing period start timestamp"},"current_period_end":{"type":"string","nullable":true,"description":"Current billing period end timestamp"},"expires_at":{"type":"string","nullable":true,"description":"Subscription expiration timestamp"},"canceled_at":{"type":"string","nullable":true,"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/upgrade":{"post":{"tags":["Subscriptions"],"summary":"Upgrade subscription","description":"Creates 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","nullable":true,"minimum":0,"description":"Recurring server add-on quantity","example":2},"sandbox_quantity":{"type":"integer","nullable":true,"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 cancelled"}},"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","nullable":true,"description":"Formatted amount due, when available"},"checkout_url":{"type":"string","nullable":true,"description":"Checkout URL, when payment is required"},"error":{"type":"string","nullable":true,"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":{"tags":["Subscriptions"],"summary":"Cancel subscription","description":"Cancels the current authenticated user subscription.","responses":{"200":{"description":"Subscription cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether cancellation succeeded"},"subscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Subscription ID"},"user_id":{"type":"string","format":"uuid","description":"User that owns the subscription"},"project_id":{"type":"string","nullable":true,"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","nullable":true,"enum":["monthly","yearly"],"description":"Line item billing interval when price-classifiable"},"unit_amount":{"type":"number","nullable":true,"description":"Line item unit amount in minor currency units"},"currency":{"type":"string","nullable":true,"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","nullable":true,"description":"Current billing period start timestamp"},"current_period_end":{"type":"string","nullable":true,"description":"Current billing period end timestamp"},"expires_at":{"type":"string","nullable":true,"description":"Subscription expiration timestamp"},"canceled_at":{"type":"string","nullable":true,"description":"Subscription cancellation timestamp"},"created_at":{"type":"string","description":"Subscription creation timestamp"}}},"error":{"type":"string","nullable":true,"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/subscription/manage":{"get":{"tags":["Subscriptions"],"summary":"Get billing portal URL","description":"Returns 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/checkout":{"post":{"tags":["Subscriptions"],"summary":"Create checkout session","description":"Creates 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 cancelled"}},"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"}}}},"/api-keys":{"get":{"tags":["API Keys"],"summary":"List API Keys","description":"Lists API keys for the current user or a project.","parameters":[{"schema":{"type":"string"},"required":false,"name":"project_reference","in":"query"},{"schema":{"type":"string"},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string"},"required":false,"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"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"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","nullable":true,"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"status":{"type":"string","enum":["active","expired","revoked"]},"revoked_at":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["account","project"],"description":"Whether the key is bound to a single project or to the whole account. An account key acts as the owning user on every project that user can reach, at whatever relation that user holds on each one, bounded by the scopes on the key itself. Unlike a project-scoped key it is not capped at `PROJECT_TOKEN_MAX_RELATION`, so an account key with `write` scope can manage API keys, including minting new ones, and one with `delete` scope can delete projects."}},"required":["id","project_id","user_id","name","key_prefix","last_used_at","expires_at","created_at","updated_at","status","revoked_at","scopes","scope"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}},"post":{"tags":["API Keys"],"summary":"Create API Key","description":"Creates 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"},"projectId":{"type":"string"},"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","nullable":true,"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key":{"type":"string"},"key_prefix":{"type":"string"},"expires_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["account","project"],"description":"Whether the key is bound to a single project or to the whole account. An account key acts as the owning user on every project that user can reach, at whatever relation that user holds on each one, bounded by the scopes on the key itself. Unlike a project-scoped key it is not capped at `PROJECT_TOKEN_MAX_RELATION`, so an account key with `write` scope can manage API keys, including minting new ones, and one with `delete` scope can delete projects."}},"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":{"tags":["API Keys"],"summary":"Get API Key","description":"Returns 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","nullable":true,"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"status":{"type":"string","enum":["active","expired","revoked"]},"revoked_at":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["account","project"],"description":"Whether the key is bound to a single project or to the whole account. An account key acts as the owning user on every project that user can reach, at whatever relation that user holds on each one, bounded by the scopes on the key itself. Unlike a project-scoped key it is not capped at `PROJECT_TOKEN_MAX_RELATION`, so an account key with `write` scope can manage API keys, including minting new ones, and one with `delete` scope can delete projects."}},"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"}}},"patch":{"tags":["API Keys"],"summary":"Update API Key","description":"Updates 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","nullable":true}}}}}},"responses":{"200":{"description":"API key updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"status":{"type":"string","enum":["active","expired","revoked"]},"revoked_at":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["account","project"],"description":"Whether the key is bound to a single project or to the whole account. An account key acts as the owning user on every project that user can reach, at whatever relation that user holds on each one, bounded by the scopes on the key itself. Unlike a project-scoped key it is not capped at `PROJECT_TOKEN_MAX_RELATION`, so an account key with `write` scope can manage API keys, including minting new ones, and one with `delete` scope can delete projects."}},"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":{"tags":["API Keys"],"summary":"Delete API Key","description":"Deletes 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"}}}},"/integrations/tools/list":{"post":{"tags":["Integration Tools"],"summary":"List Integration Tools","description":"Lists integration tools available to the current user and project.","responses":{"200":{"description":"Available integration tools","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":{"nullable":true},"description":"JSON Schema for tool input"}},"required":["name","description","inputSchema"]}}},"required":["tools"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/integrations/tools/call":{"post":{"tags":["Integration Tools"],"summary":"Call Integration Tool","description":"Calls an integration tool.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Tool name","example":"github__list-repos"},"arguments":{"type":"object","additionalProperties":{"nullable":true},"default":{},"description":"Tool arguments"},"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"}},"required":["name"]}}}},"responses":{"200":{"description":"Tool execution result","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}},"required":["type","text"]}},"structuredContent":{"type":"object","additionalProperties":{"nullable":true}},"isError":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/integrations/{integration}/tools":{"get":{"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"}],"responses":{"200":{"description":"Available tools for the integration","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":{"nullable":true},"description":"JSON Schema for tool input"}},"required":["name","description","inputSchema"]}}},"required":["tools"]}}}},"400":{"description":"Invalid integration path parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/integrations/{integration}/tools/{tool}/call":{"post":{"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"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"arguments":{"type":"object","additionalProperties":{"nullable":true},"default":{},"description":"Tool arguments"},"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"}}}}}},"responses":{"200":{"description":"Tool execution result","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}},"required":["type","text"]}},"structuredContent":{"type":"object","additionalProperties":{"nullable":true}},"isError":{"type":"boolean"}}}}}},"400":{"description":"Invalid path parameters or request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/integrations/{name}/connections":{"get":{"tags":["Integrations"],"summary":"List Integration Connections","description":"Lists 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"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"connection_generation_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","nullable":true,"format":"uuid","description":"Veryfront user ID for a user-scoped connection; null for a shared project connection"},"integration":{"type":"string"},"scope":{"type":"string","enum":["user","project"]},"display_name":{"type":"string","nullable":true},"can_disconnect":{"type":"boolean"},"can_reconnect":{"type":"boolean"},"project":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"status":{"type":"string","enum":["connected","expired","disconnected"]}},"required":["id","connection_generation_id","user_id","integration","scope","display_name","can_disconnect","can_reconnect","project","created_at","updated_at","status"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"total":{"type":"integer","minimum":0}},"required":["data","page_info","total"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/integrations":{"get":{"tags":["Integrations"],"summary":"List Integrations","description":"Lists available integrations.","parameters":[{"schema":{"type":"string","description":"Deprecated. Version is now baked into the package."},"required":false,"name":"version","in":"query"},{"schema":{"type":"string","description":"Search query to filter integrations","example":"email"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","description":"Cursor.","example":"gmail"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["name"],"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 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"},"description":{"type":"string","description":"Brief description","example":"Read and send emails via Gmail API"},"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","auth_type","tool_count","prompt_count","project_connections","project_user_connections"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"total":{"type":"number"}},"required":["data","page_info","total"]}}}},"400":{"description":"Invalid query parameters","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/integrations/{name}":{"get":{"tags":["Integrations"],"summary":"Get Integration","description":"Returns an integration by name.","parameters":[{"schema":{"type":"string","description":"Integration name","example":"gmail"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string","description":"Deprecated. Version is now baked into the package."},"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"},"description":{"type":"string"},"auth":{"type":"object","properties":{"type":{"type":"string","enum":["oauth2","oauth1","api-key","basic"]},"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":"Env var names holding the credentials the integration expects; empty when none are declared","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","nullable":true},"client_secret_env_var":{"type":"string","nullable":true}},"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"}},"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":{"nullable":true},"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"]},"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","auth","credential_env_var_names","credential_requirement","env_vars","tools","project_connections","project_user_connections"]}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/integrations/{name}/icon":{"get":{"tags":["Integrations"],"summary":"Get Integration Icon","description":"Returns 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. Version is now baked into the package."},"required":false,"name":"version","in":"query"}],"responses":{"200":{"description":"SVG icon","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Icon not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/connections":{"get":{"tags":["Connections"],"summary":"List Connections","description":"Lists the current user's project-user connections and shared connections across accessible projects.","parameters":[{"schema":{"type":"string"},"required":false,"name":"integration","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"connection_generation_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","nullable":true,"format":"uuid","description":"Veryfront user ID for a user-scoped connection; null for a shared project connection"},"integration":{"type":"string"},"scope":{"type":"string","enum":["user","project"]},"display_name":{"type":"string","nullable":true},"can_disconnect":{"type":"boolean"},"can_reconnect":{"type":"boolean"},"project":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"status":{"type":"string","enum":["connected","expired","disconnected"]}},"required":["id","connection_generation_id","user_id","integration","scope","display_name","can_disconnect","can_reconnect","project","created_at","updated_at","status"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"total":{"type":"integer","minimum":0}},"required":["data","page_info","total"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/mcp/tools":{"get":{"tags":["MCP"],"summary":"List public MCP tools","description":"Lists public Veryfront MCP tool summaries for anonymous playground browsing.","parameters":[{"schema":{"type":"string","enum":["legacy","canonical"],"default":"canonical"},"required":false,"name":"tool_names","in":"query"}],"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","nullable":true,"enum":["tool_ids"]}},"required":["name","canonicalName","type","category","description","availability","riskLevel","href","hasOutputSchema","attachVia"]}},"generatedAt":{"type":"string"}},"required":["data","generatedAt"]}}}}}}},"/mcp/tools/{tool_name}":{"get":{"tags":["MCP"],"summary":"Get public MCP tool detail","description":"Returns public MCP metadata for one tool, including input and output schema when present.","parameters":[{"schema":{"type":"string"},"required":true,"name":"tool_name","in":"path"},{"schema":{"type":"string","enum":["legacy","canonical"],"default":"canonical"},"required":false,"name":"tool_names","in":"query"}],"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":{"nullable":true},"outputSchema":{"nullable":true},"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":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/mcp/catalog":{"get":{"tags":["MCP"],"summary":"List public MCP catalog (deprecated alias)","description":"Deprecated compatibility alias that returns the full public Veryfront MCP tool catalog.","parameters":[{"schema":{"type":"string","enum":["legacy","canonical"],"default":"canonical"},"required":false,"name":"tool_names","in":"query"}],"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":{"nullable":true},"outputSchema":{"nullable":true},"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"]}}}}}}},"/mcp/playground":{"get":{"tags":["MCP"],"summary":"Open MCP Playground","description":"Serves the browser-based Veryfront MCP tool playground.","responses":{"200":{"description":"MCP playground HTML.","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/me":{"get":{"tags":["User"],"summary":"Get profile","description":"Returns 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":{"type":"object","properties":{"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","description":"Current billing period end timestamp"},"created_at":{"type":"string","description":"Subscription creation timestamp"},"canceled_at":{"type":"string","nullable":true,"description":"Subscription cancellation timestamp"}},"required":["id","user_id","line_items","expires_at"]}},"required":["id"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environments":{"get":{"tags":["Environments"],"summary":"List Environments","description":"Returns all environments with their domains and environment variables.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":{"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","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"release":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"export_status":{"type":"string","nullable":true},"build_status":{"type":"string","nullable":true},"deploy_status":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"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"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"tags":["Environments"],"summary":"Create Environment","description":"Create a new private environment in the project","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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":{"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","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"release":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"export_status":{"type":"string","nullable":true},"build_status":{"type":"string","nullable":true},"deploy_status":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"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"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/environments/{environment_id}":{"get":{"tags":["Environments"],"summary":"Get Environment","description":"Get a specific environment by its ID","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"environment_id","in":"path"}],"responses":{"200":{"description":"Environment details","content":{"application/json":{"schema":{"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","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"release":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"export_status":{"type":"string","nullable":true},"build_status":{"type":"string","nullable":true},"deploy_status":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Environment or project not found"},"500":{"description":"Server error"}}},"patch":{"tags":["Environments"],"summary":"Update Environment","description":"Update an existing environment","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"environment_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"protected":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Environment updated successfully","content":{"application/json":{"schema":{"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","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"release":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"export_status":{"type":"string","nullable":true},"build_status":{"type":"string","nullable":true},"deploy_status":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Environment or project not found"},"500":{"description":"Server error"}}},"delete":{"tags":["Environments"],"summary":"Delete Environment","description":"Delete an environment from the project","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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}/domains":{"get":{"tags":["Domains"],"summary":"List Project Domains","description":"Returns all custom domains across all environments for a project. Includes environment information for each domain.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","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\"."},"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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches":{"get":{"tags":["Branches"],"summary":"List Branches","description":"Get all branches belonging to a project, with optional search and status filters.","parameters":[{"schema":{"type":"string","example":"my-project"},"required":true,"name":"project_reference","in":"path"},{"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","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","nullable":true,"format":"uuid"},"created_at":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"format":"uuid"},"merged_at":{"type":"string","nullable":true},"merged_by":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","name","project_id"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"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","nullable":true,"format":"uuid","description":"Base branch ID to create from (null for the default branch)"}},"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","nullable":true,"format":"uuid"},"created_at":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"format":"uuid"},"merged_at":{"type":"string","nullable":true},"merged_by":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","name","project_id"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchId}":{"get":{"tags":["Branches"],"summary":"Get Branch","description":"Get details for a specific branch.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"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","nullable":true,"format":"uuid"},"created_at":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"format":"uuid"},"merged_at":{"type":"string","nullable":true},"merged_by":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","name","project_id"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Branch or project not found"},"500":{"description":"Server error"}}},"delete":{"tags":["Branches"],"summary":"Delete Branch","description":"Delete a branch and all associated content.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"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"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Cannot delete default or protected branch"},"404":{"description":"Branch or project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchId}/merge":{"post":{"tags":["Branches"],"summary":"Merge Branch","description":"Merge a branch into the target branch (or main if not specified)","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"required":true,"name":"branchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target_branch_id":{"type":"string","nullable":true,"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","nullable":true,"format":"uuid"},"created_at":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"format":"uuid"},"merged_at":{"type":"string","nullable":true},"merged_by":{"type":"string","nullable":true,"format":"uuid"}},"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":"Branch already merged or invalid state"},"401":{"description":"Unauthorized"},"404":{"description":"Branch or project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchId}/merge-preview":{"get":{"tags":["Branches"],"summary":"Preview Branch Merge","description":"Preview what changes will be applied when merging a branch","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"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","nullable":true,"format":"uuid"},"created_at":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"format":"uuid"},"merged_at":{"type":"string","nullable":true},"merged_by":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","name","project_id"]},"target_branch_id":{"type":"string","nullable":true,"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":{"nullable":true}},"is_new":{"type":"boolean"},"is_deleted":{"type":"boolean"},"is_modified":{"type":"boolean"},"base_changed":{"type":"boolean"},"branch_changed":{"type":"boolean"},"base_content":{"type":"string","nullable":true},"target_content":{"type":"string","nullable":true},"source_content":{"type":"string","nullable":true},"original_content":{"type":"string","nullable":true},"modified_content":{"type":"string","nullable":true}},"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Branch or project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchId}/eligibility":{"get":{"tags":["Branches"],"summary":"Check Branch Eligibility","description":"Evaluates branch approvals, status checks, and policy requirements to determine whether the branch can merge.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"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"},"comment":{"type":"string","nullable":true},"dismissed_at":{"type":"string","nullable":true},"dismissed_by":{"type":"string","nullable":true,"format":"uuid"},"dismissed_reason":{"type":"string","nullable":true}},"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","nullable":true},"external_url":{"type":"string","nullable":true},"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":["approvalRequired","statusCheckFailed","selfApprovalNotAllowed","requiredReviewerMissing"]},"message":{"type":"string"},"details":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","message","details"]}}},"required":["can_merge","approvals","status_checks","blockers"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Branch not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/policies":{"get":{"tags":["Branches"],"summary":"List Branch Policies","description":"Lists branch protection policies configured for the project, optionally filtered by branch pattern.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"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","nullable":true},"required_approvals":{"type":"number"},"allow_self_approval":{"type":"boolean"},"required_reviewer_ids":{"type":"array","nullable":true,"items":{"type":"string"}},"required_reviewer_roles":{"type":"array","nullable":true,"items":{"type":"string"}},"block_direct_edits":{"type":"boolean"},"auto_merge_when_approved":{"type":"boolean"},"dismiss_approvals_on_change":{"type":"boolean"},"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","required_reviewer_roles","block_direct_edits","auto_merge_when_approved","dismiss_approvals_on_change","created_at","updated_at"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"tags":["Branches"],"summary":"Create Branch Policy","description":"Creates a branch protection policy for a project, including required approvals and status checks.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"is_enabled":{"type":"boolean"},"target_branch_pattern":{"type":"string"},"required_approvals":{"type":"number"},"allow_self_approval":{"type":"boolean"},"required_reviewer_ids":{"type":"array","items":{"type":"string"}},"required_reviewer_roles":{"type":"array","items":{"type":"string"}},"block_direct_edits":{"type":"boolean"},"auto_merge_when_approved":{"type":"boolean"},"dismiss_approvals_on_change":{"type":"boolean"}},"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","nullable":true},"required_approvals":{"type":"number"},"allow_self_approval":{"type":"boolean"},"required_reviewer_ids":{"type":"array","nullable":true,"items":{"type":"string"}},"required_reviewer_roles":{"type":"array","nullable":true,"items":{"type":"string"}},"block_direct_edits":{"type":"boolean"},"auto_merge_when_approved":{"type":"boolean"},"dismiss_approvals_on_change":{"type":"boolean"},"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","required_reviewer_roles","block_direct_edits","auto_merge_when_approved","dismiss_approvals_on_change","created_at","updated_at"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/policies/{policyId}":{"delete":{"tags":["Branches"],"summary":"Delete Branch Policy","description":"Deletes a branch protection policy from the project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"policyId","in":"path"}],"responses":{"200":{"description":"Policy deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Policy not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchId}/approvals":{"get":{"tags":["Branches"],"summary":"List Branch Approvals","description":"Lists approvals recorded for a branch in the project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"required":true,"name":"branchId","in":"path"}],"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"},"comment":{"type":"string","nullable":true},"dismissed_at":{"type":"string","nullable":true},"dismissed_by":{"type":"string","nullable":true,"format":"uuid"},"dismissed_reason":{"type":"string","nullable":true}},"required":["id","branch_id","approved_by","approved_at","comment","dismissed_at","dismissed_by","dismissed_reason"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Branch not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchId}/approve":{"post":{"tags":["Branches"],"summary":"Approve Branch","description":"Creates or updates the caller approval for a branch so the branch can satisfy merge policy requirements.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"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"},"comment":{"type":"string","nullable":true},"dismissed_at":{"type":"string","nullable":true},"dismissed_by":{"type":"string","nullable":true,"format":"uuid"},"dismissed_reason":{"type":"string","nullable":true}},"required":["id","branch_id","approved_by","approved_at","comment","dismissed_at","dismissed_by","dismissed_reason"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Branch not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchId}/approvals/{approvalId}":{"delete":{"tags":["Branches"],"summary":"Dismiss Branch Approval","description":"Dismisses an existing branch approval so merge eligibility can be recalculated from the remaining approvals.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"required":true,"name":"branchId","in":"path"},{"schema":{"type":"string","format":"uuid"},"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","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"approved_by":{"type":"string","format":"uuid"},"approved_at":{"type":"string"},"comment":{"type":"string","nullable":true},"dismissed_at":{"type":"string","nullable":true},"dismissed_by":{"type":"string","nullable":true,"format":"uuid"},"dismissed_reason":{"type":"string","nullable":true}},"required":["id","branch_id","approved_by","approved_at","comment","dismissed_at","dismissed_by","dismissed_reason"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Approval not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchId}/status-checks":{"get":{"tags":["Branches"],"summary":"List Branch Status Checks","description":"Lists status checks reported for a branch so clients can inspect merge-blocking checks.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"required":true,"name":"branchId","in":"path"}],"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","nullable":true},"external_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","branch_id","check_name","status","description","external_url","created_at","updated_at"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Branch not found"},"500":{"description":"Server error"}}},"post":{"tags":["Branches"],"summary":"Upsert Branch Status Check","description":"Creates or updates a named status check result for a branch.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Branch ID (UUID)"},"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","nullable":true},"external_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","branch_id","check_name","status","description","external_url","created_at","updated_at"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Branch not found"},"500":{"description":"Server error"}}}},"/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. Use ?fields=(id,path,size) to filter response fields per Zalando #157.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"pattern","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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":"Sparse fieldset filter per Zalando #157. Examples: (id,name), (id,files(path)), !(content)","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"Files from the branch (supports sparse fieldsets per Zalando #157)","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":{"nullable":true}}},"required":["path","content","type","size","updated_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"_links":{"type":"object","additionalProperties":{"nullable":true}}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/versions":{"get":{"operationId":"listBranchFileVersions","tags":["Branch Files"],"summary":"List Branch File Versions","description":"Returns branch-aware file history bounded by the branch snapshot. The filePath should be URL-encoded if it contains special characters.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., pages%2Findex.mdx)"},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"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","nullable":true}},"required":["id","path","type","created_at","created_by"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/versions/{version_id}":{"get":{"operationId":"getBranchFileVersion","tags":["Branch Files"],"summary":"Get Branch File Version","description":"Returns content for a specific branch-aware file version. The filePath should be URL-encoded if it contains special characters.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., pages%2Findex.mdx)"},"required":true,"name":"filePath","in":"path"},{"schema":{"type":"string","description":"Version UUID or numeric index (0 = current in branch history)"},"required":true,"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"},"type":{"type":"string","enum":["page","function","component","file"]},"updated_at":{"type":"string"}},"required":["id","path","content","size","type","updated_at"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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. Use ?fields=(id,path,size) to filter response fields per Zalando #157. The filePath should be URL-encoded if it contains special characters (e.g., pages%2Findex.mdx for pages/index.mdx).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., 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":"Sparse fieldset filter per Zalando #157. Examples: (id,name), (id,files(path)), !(content)","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"File from the branch (supports sparse fieldsets per Zalando #157)","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"}},"required":["path","content","size","type","updated_at"]}}}},"400":{"description":"Missing file path"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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. The filePath should be URL-encoded if it contains special characters (e.g., pages%2Findex.mdx for pages/index.mdx).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., 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":"number","nullable":true,"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":"Missing file path"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/draft":{"get":{"operationId":"getBranchFileDraft","tags":["Branch Files"],"summary":"Get Branch File Draft","description":"The filePath should be URL-encoded if it contains special characters (e.g., pages%2Findex.mdx for pages/index.mdx).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., pages%2Findex.mdx)"},"required":true,"name":"filePath","in":"path"}],"responses":{"200":{"description":"Draft content","content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"updated_at":{"type":"string"}},"required":["path","content","updated_at"]}}}},"400":{"description":"Missing file path"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}},"delete":{"operationId":"deleteBranchFileDraft","tags":["Branch Files"],"summary":"Delete Branch File Draft","description":"The filePath should be URL-encoded if it contains special characters (e.g., pages%2Findex.mdx for pages/index.mdx).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Branch name"},"required":true,"name":"branchName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., pages%2Findex.mdx)"},"required":true,"name":"filePath","in":"path"}],"responses":{"204":{"description":"Draft discarded"},"400":{"description":"Missing file path"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/branches/{branchName}/files/search":{"post":{"operationId":"searchBranchFiles","tags":["Search"],"summary":"Search Branch Files (Text)","description":"Grep-like text search across branch files with regex support","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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 (e.g., *.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":"number","description":"Maximum results (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 or regex"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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. Use ?fields=(id,path,size) to filter response fields per Zalando #157.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version (e.g., \"1.2.3\" or \"latest\")"},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"pattern","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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":"Sparse fieldset filter per Zalando #157. Examples: (id,name), (id,files(path)), !(content)","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"Files from the release (supports sparse fieldsets per Zalando #157)","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":{"nullable":true}}},"required":["id","version_id","path","content","type","size","updated_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"release_id":{"type":"string"},"release_version":{"type":"string","nullable":true},"_links":{"type":"object","additionalProperties":{"nullable":true}}},"required":["data","page_info","release_id","release_version"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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. Use ?fields=(id,path,size) to filter response fields per Zalando #157. The filePath should be URL-encoded if it contains special characters (e.g., pages%2Findex.mdx for pages/index.mdx).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version (e.g., \"1.2.3\" or \"latest\")"},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., 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":"Sparse fieldset filter per Zalando #157. Examples: (id,name), (id,files(path)), !(content)","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"File from the release (supports sparse fieldsets per Zalando #157)","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","nullable":true},"_links":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","version_id","path","content","size","type","updated_at","release_id","release_version"]}}}},"400":{"description":"Missing file path"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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. The filePath should be URL-encoded if it contains special characters (e.g., pages%2Findex.mdx for pages/index.mdx).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Release version (e.g., \"1.2.3\" or \"latest\")"},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., 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":"number","nullable":true,"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":"Missing file path"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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. Use ?fields=(id,path,size) to filter response fields per Zalando #157.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Environment name (e.g., production, preview)"},"required":true,"name":"environmentName","in":"path"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"pattern","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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":"Sparse fieldset filter per Zalando #157. Examples: (id,name), (id,files(path)), !(content)","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"Files from the environment (supports sparse fieldsets per Zalando #157)","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":{"nullable":true}}},"required":["id","version_id","path","content","type","size","updated_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"environment_id":{"type":"string"},"environment_name":{"type":"string"},"release_id":{"type":"string"},"release_version":{"type":"string","nullable":true},"_links":{"type":"object","additionalProperties":{"nullable":true}}},"required":["data","page_info","environment_id","environment_name","release_id","release_version"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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. Use ?fields=(id,path,size) to filter response fields per Zalando #157. The filePath should be URL-encoded if it contains special characters (e.g., pages%2Findex.mdx for pages/index.mdx).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Environment name (e.g., production, preview)"},"required":true,"name":"environmentName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., 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":"Sparse fieldset filter per Zalando #157. Examples: (id,name), (id,files(path)), !(content)","example":"(id,path,type,size)"},"required":false,"name":"fields","in":"query"}],"responses":{"200":{"description":"File from the environment (supports sparse fieldsets per Zalando #157)","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","nullable":true},"_links":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","version_id","path","content","size","type","updated_at","environment_id","environment_name","release_id","release_version"]}}}},"400":{"description":"Missing file path"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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. The filePath should be URL-encoded if it contains special characters (e.g., pages%2Findex.mdx for pages/index.mdx).","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Environment name (e.g., production, preview)"},"required":true,"name":"environmentName","in":"path"},{"schema":{"type":"string","description":"File path (URL-encoded, e.g., 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":"number","nullable":true,"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":"Missing file path"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/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 before 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},"required":false,"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","nullable":true},"entries":{"type":"array","items":{"type":"object","properties":{"dependencies":{"type":"object","additionalProperties":{"type":"string"}},"expires_at":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["dependencies","expires_at"]},"maxItems":16}},"required":["version","project_id","branch","entries"]}}}},"400":{"description":"Invalid branch reference"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — project.files.read capability required"},"404":{"description":"Project or branch not found"},"500":{"description":"Server error"}}}},"/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 (e.g. \"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":"Preview branch name or ID whose package.json receives the resolved pins.","example":"feature-a"},"expected_declarations":{"type":"object","additionalProperties":{"type":"string","nullable":true,"maxLength":200},"description":"Package declarations observed by the caller. 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":"Whether the resolved pins were successfully written to the project's package.json. A false value means resolution succeeded but the write failed; pins still reflect the 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"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — project.files.write capability required"},"404":{"description":"Project or branch not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/integrations":{"get":{"operationId":"listProjectIntegrations","tags":["Project Integrations"],"summary":"List Project Integrations","description":"Lists the integration catalog with project enablement and connection overlay.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"icon":{"type":"string"},"description":{"type":"string"},"auth_type":{"type":"string"},"tool_count":{"type":"number"},"prompt_count":{"type":"number"},"connected_for_project":{"type":"boolean"},"scope":{"type":"string","enum":["project","user"]},"allowed_tools":{"type":"array","nullable":true,"items":{"type":"string"}},"config":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"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"]},"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","nullable":true,"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","nullable":true},"client_secret_env_var":{"type":"string","nullable":true}},"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","nullable":true,"enum":["project","user"]},"connected_count":{"type":"integer","nullable":true,"minimum":0}},"required":["status","scope","connected_count"]}},"required":["catalog_available","catalog_state","policy","credential_requirement","connection_readiness"]}},"required":["name","display_name","icon","description","auth_type","tool_count","prompt_count","connected_for_project","scope","allowed_tools","execution_mode","project_connections","project_user_connections","resolution"]}}},"required":["data"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/integrations/{name}/connections":{"get":{"operationId":"listProjectIntegrationConnections","tags":["Project Integrations"],"summary":"List Project Integration Connections","description":"Lists shared project connections and the authenticated viewer's private project-user connections.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"connection_generation_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","nullable":true,"format":"uuid","description":"Veryfront user ID for a user-scoped connection; null for a shared project connection"},"integration":{"type":"string"},"scope":{"type":"string","enum":["user","project"]},"display_name":{"type":"string","nullable":true},"can_disconnect":{"type":"boolean"},"can_reconnect":{"type":"boolean"},"project":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"status":{"type":"string","enum":["connected","expired","disconnected"]}},"required":["id","connection_generation_id","user_id","integration","scope","display_name","can_disconnect","can_reconnect","project","created_at","updated_at","status"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"total":{"type":"integer","minimum":0}},"required":["data","page_info","total"]}}}},"404":{"description":"Project or integration not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/connections":{"get":{"operationId":"listProjectConnections","tags":["Project Integrations"],"summary":"List Project Connections","description":"Lists shared project connections and the authenticated viewer's private project-user connections.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"integration","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"connection_generation_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","nullable":true,"format":"uuid","description":"Veryfront user ID for a user-scoped connection; null for a shared project connection"},"integration":{"type":"string"},"scope":{"type":"string","enum":["user","project"]},"display_name":{"type":"string","nullable":true},"can_disconnect":{"type":"boolean"},"can_reconnect":{"type":"boolean"},"project":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"status":{"type":"string","enum":["connected","expired","disconnected"]}},"required":["id","connection_generation_id","user_id","integration","scope","display_name","can_disconnect","can_reconnect","project","created_at","updated_at","status"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"total":{"type":"integer","minimum":0}},"required":["data","page_info","total"]}}}},"404":{"description":"Project or integration not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/integrations/salesforce/objects":{"get":{"operationId":"listSalesforceObjects","tags":["Project Integrations"],"summary":"List Salesforce Objects","description":"Lists Salesforce sObjects visible to the connected Salesforce user for project data access configuration.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Salesforce object metadata","content":{"application/json":{"schema":{"type":"object","properties":{"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/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/integrations/salesforce/objects/{object_name}/fields":{"get":{"operationId":"listSalesforceObjectFields","tags":["Project Integrations"],"summary":"List Salesforce Object Fields","description":"Lists fields for a Salesforce sObject visible to the connected Salesforce user.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"object_name","in":"path"}],"responses":{"200":{"description":"Salesforce object field metadata","content":{"application/json":{"schema":{"type":"object","properties":{"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","nullable":true},"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/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"Project or Salesforce object not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/integrations/{name}":{"get":{"operationId":"getProjectIntegration","tags":["Project Integrations"],"summary":"Get Project Integration","description":"Gets a single integration card with project enablement and connection overlay.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Project integration card","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"icon":{"type":"string"},"description":{"type":"string"},"auth_type":{"type":"string"},"tool_count":{"type":"number"},"prompt_count":{"type":"number"},"connected_for_project":{"type":"boolean"},"scope":{"type":"string","enum":["project","user"]},"allowed_tools":{"type":"array","nullable":true,"items":{"type":"string"}},"config":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"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"]},"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","nullable":true,"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","nullable":true},"client_secret_env_var":{"type":"string","nullable":true}},"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","nullable":true,"enum":["project","user"]},"connected_count":{"type":"integer","nullable":true,"minimum":0}},"required":["status","scope","connected_count"]}},"required":["catalog_available","catalog_state","policy","credential_requirement","connection_readiness"]}},"required":["name","display_name","icon","description","auth_type","tool_count","prompt_count","connected_for_project","scope","allowed_tools","execution_mode","project_connections","project_user_connections","resolution"]}}}},"404":{"description":"Project or integration not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}},"put":{"operationId":"putProjectIntegration","tags":["Project Integrations"],"summary":"Upsert Project Integration","description":"Upserts project integration config for a single integration.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"items":{"type":"string"}},"config":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"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/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}},"delete":{"operationId":"deleteProjectIntegration","tags":["Project Integrations"],"summary":"Delete Project Integration Policy","description":"Deletes project integration policy without revoking OAuth credentials.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"204":{"description":"Project integration policy deleted"},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/integrations/{name}/mock/preflight":{"get":{"operationId":"preflightProjectIntegrationMock","tags":["Project Integrations"],"summary":"Preflight Project Integration Mock","description":"Proxies a staging mock-integration control command through Veryfront API.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Mock integration control response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true}}}}}},"400":{"description":"Integration is not configured for mock execution","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/integrations/{name}/mock/state":{"get":{"operationId":"getProjectIntegrationMockState","tags":["Project Integrations"],"summary":"Get Project Integration Mock State","description":"Proxies a staging mock-integration control command through Veryfront API.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Mock integration control response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true}}}}}},"400":{"description":"Integration is not configured for mock execution","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/integrations/{name}/mock/reset":{"post":{"operationId":"resetProjectIntegrationMockState","tags":["Project Integrations"],"summary":"Reset Project Integration Mock State","description":"Proxies a staging mock-integration control command through Veryfront API.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Mock integration control response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true}}}}}},"400":{"description":"Integration is not configured for mock execution","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/integrations/{name}/mock/audit-events":{"get":{"operationId":"listProjectIntegrationMockAuditEvents","tags":["Project Integrations"],"summary":"List Project Integration Mock Audit Events","description":"Proxies a staging mock-integration control command through Veryfront API.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"Mock integration control response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true}}}}}},"400":{"description":"Integration is not configured for mock execution","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/projects/{project_reference}/branches/{branchName}/search":{"post":{"operationId":"searchBranchContent","tags":["Search"],"summary":"Search branch files with a vector","description":"Search branch content using a pre-computed embedding vector. Generate embeddings client-side using OpenAI, Anthropic, or another embedding provider.","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":{"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"]}}}},"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"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":{"nullable":true}}},"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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"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"]}}}},"404":{"description":"Project or branch not found"}}}},"/projects/{project_reference}/environments/{environmentName}/search":{"post":{"operationId":"searchEnvironmentContent","tags":["Search"],"summary":"Search environment files with a vector","description":"Search the named environment deployment using a pre-computed 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","minLength":1,"description":"Exact environment name from the route."},"required":true,"name":"environmentName","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"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"]}}}},"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"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":{"nullable":true}}},"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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"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"]}}}},"404":{"description":"Project not found"}}}},"/projects/{project_reference}/releases/{version}/search":{"post":{"operationId":"searchReleaseContent","tags":["Search"],"summary":"Search release files with a vector","description":"Search release content using a pre-computed 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":{"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"]}}}},"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"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":{"nullable":true}}},"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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."},"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"]}}}},"404":{"description":"Project not found"}}}},"/projects/{project_reference}/branches/{branchName}/files/{filePath}/chunks":{"get":{"operationId":"listBranchFileChunks","tags":["Chunks"],"summary":"List Branch File Chunks","description":"Lists 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":"number","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"}],"responses":{"200":{"description":"File chunks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"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":{"nullable":true}},"created_at":{"type":"string"},"embedding":{"type":"object","properties":{"id":{"type":"string"},"model":{"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"]},"description":"File chunks in the requested branch, environment, or release context."},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found"}}},"post":{"operationId":"upsertBranchFileChunks","tags":["Chunks"],"summary":"Upsert Branch File Chunks","description":"Creates 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":{"nullable":true},"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":["Chunks"],"summary":"Delete Branch File Chunks","description":"Deletes 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":["Chunks"],"summary":"Get Branch File Chunk","description":"Returns 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"}],"responses":{"200":{"description":"Chunk","content":{"application/json":{"schema":{"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":{"nullable":true}},"created_at":{"type":"string"},"embedding":{"type":"object","properties":{"id":{"type":"string"},"model":{"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"]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found"}}}},"/projects/{project_reference}/environments/{environmentName}/files/{filePath}/chunks":{"get":{"operationId":"listEnvironmentFileChunks","tags":["Chunks"],"summary":"List Environment File Chunks","description":"Lists 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":"number","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"}],"responses":{"200":{"description":"File chunks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"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":{"nullable":true}},"created_at":{"type":"string"},"embedding":{"type":"object","properties":{"id":{"type":"string"},"model":{"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"]},"description":"File chunks in the requested branch, environment, or release context."},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found"}}}},"/projects/{project_reference}/environments/{environmentName}/files/{filePath}/chunks/{chunkId}":{"get":{"operationId":"getEnvironmentFileChunk","tags":["Chunks"],"summary":"Get Environment File Chunk","description":"Returns 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"}],"responses":{"200":{"description":"Chunk","content":{"application/json":{"schema":{"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":{"nullable":true}},"created_at":{"type":"string"},"embedding":{"type":"object","properties":{"id":{"type":"string"},"model":{"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"]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found"}}}},"/projects/{project_reference}/releases/{version}/files/{filePath}/chunks":{"get":{"operationId":"listReleaseFileChunks","tags":["Chunks"],"summary":"List Release File Chunks","description":"Lists 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":"number","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"}],"responses":{"200":{"description":"File chunks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"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":{"nullable":true}},"created_at":{"type":"string"},"embedding":{"type":"object","properties":{"id":{"type":"string"},"model":{"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"]},"description":"File chunks in the requested branch, environment, or release context."},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found"}}}},"/projects/{project_reference}/releases/{version}/files/{filePath}/chunks/{chunkId}":{"get":{"operationId":"getReleaseFileChunk","tags":["Chunks"],"summary":"Get Release File Chunk","description":"Returns 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"}],"responses":{"200":{"description":"Chunk","content":{"application/json":{"schema":{"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":{"nullable":true}},"created_at":{"type":"string"},"embedding":{"type":"object","properties":{"id":{"type":"string"},"model":{"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"]}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found"}}}},"/projects/{project_reference}/embeddings":{"get":{"operationId":"listEmbeddings","tags":["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","nullable":true,"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","nullable":true,"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":["Embeddings"],"summary":"Upsert embeddings","description":"Store 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"}},"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","nullable":true,"description":"Vector dimension; usecase validation enforces supported dimensions."}},"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":["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":["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}/knowledge/lookup":{"post":{"operationId":"lookupProjectKnowledge","tags":["Knowledge"],"summary":"Lookup project knowledge","description":"Search compact knowledge frontmatter across knowledge markdown files with cursor pagination, optional sharding, and explicit preview/environment/release targeting.","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 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, repeat the same original query and 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","nullable":true,"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 current branch (the default). Only set this to target a specific deployed environment or release."},"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":"Query string associated with this result."},"mode":{"type":"string","enum":["search","browse"],"description":"The mode associated with this tool result."},"data":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"The path associated with this tool result."},"matched_fields":{"type":"array","items":{"type":"string","description":"One matched field item associated with this tool result."},"description":"List of matched fields associated with this tool result."},"frontmatter":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The key associated with this tool result."},"value":{"type":"string","description":"The value associated with this tool result."}},"required":["key","value"],"description":"One frontmatter item associated with this tool result."},"description":"List of frontmatter associated with this tool result."}},"required":["path","matched_fields","frontmatter"],"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","nullable":true,"description":"Cursor that refers to the current page."},"first":{"type":"object","nullable":true,"enum":[null],"description":"The first associated with this tool result."},"next":{"type":"string","nullable":true,"description":"Cursor for the next page when pagination is available."},"prev":{"type":"string","nullable":true,"description":"Cursor for the previous page when pagination is available."}},"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 branch not found"}}}},"/projects/{project_reference}/style-artifacts/current":{"get":{"operationId":"resolveProjectStyleArtifact","tags":["Style Artifacts"],"summary":"Resolve Current Project Style Artifact","description":"Resolve metadata for the latest ready CSS artifact for a project selector and style profile.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"style_profile_hash","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"branch","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"environment_name","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"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"]},"artifact_hash":{"type":"string"},"asset_path":{"type":"string"},"etag":{"type":"string"},"content_type":{"type":"string"},"build_run_id":{"type":"string","minLength":1},"failure_reason":{"type":"string"},"updated_at":{"type":"string"}},"required":["status"]}}}},"400":{"description":"Invalid selector or request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Project not found"}}},"put":{"operationId":"upsertProjectStyleArtifact","tags":["Style Artifacts"],"summary":"Register Current Project Style Artifact","description":"Store metadata for the latest ready CSS artifact for a project selector and style profile.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"style_profile_hash":{"type":"string","minLength":1},"branch":{"type":"string","minLength":1},"environment_name":{"type":"string","minLength":1},"release_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["building","ready","failed"],"default":"ready"},"artifact_hash":{"type":"string","minLength":1},"asset_path":{"type":"string","minLength":1},"content_type":{"type":"string","minLength":1},"etag":{"type":"string","minLength":1},"build_run_id":{"type":"string","minLength":1},"failure_reason":{"type":"string","minLength":1}},"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"]},"artifact_hash":{"type":"string"},"asset_path":{"type":"string"},"etag":{"type":"string"},"content_type":{"type":"string"},"build_run_id":{"type":"string","minLength":1},"failure_reason":{"type":"string"},"updated_at":{"type":"string"}},"required":["status"]}}}},"400":{"description":"Invalid selector or request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Project not found"}}}},"/projects/{project_reference}/style-artifacts/current/builds":{"post":{"operationId":"ensureProjectStyleArtifactBuild","tags":["Style Artifacts"],"summary":"Ensure Current Project Style Artifact Build","description":"Ensure there is a background build in progress for the current style artifact selector and profile.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"style_profile_hash":{"type":"string","minLength":1},"branch":{"type":"string","minLength":1},"environment_name":{"type":"string","minLength":1},"release_id":{"type":"string","format":"uuid"},"force":{"type":"boolean","default":false}},"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"]},"artifact_hash":{"type":"string"},"asset_path":{"type":"string"},"etag":{"type":"string"},"content_type":{"type":"string"},"build_run_id":{"type":"string","minLength":1},"failure_reason":{"type":"string"},"updated_at":{"type":"string"}},"required":["status"]}}}},"400":{"description":"Invalid selector or request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Project not found"}}}},"/projects/{project_reference}/rag/documents":{"get":{"operationId":"listRagDocuments","tags":["RAG 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":{"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":{"nullable":true},"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":["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":["RAG Documents"],"summary":"Upsert a RAG document","description":"Create a new project RAG document record or update an existing one 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":{"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":{"nullable":true},"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":{"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":{"nullable":true},"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":["id","title","source","type","metadata","created_at","updated_at"],"description":"Created or updated RAG document."}},"required":["document"]}}}},"404":{"description":"Project not found"}}}},"/projects/{project_reference}/rag/documents/{documentId}":{"delete":{"operationId":"deleteRagDocument","tags":["RAG 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"}],"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"}}}},"/projects/{project_reference}/chunks":{"get":{"operationId":"listProjectChunks","tags":["Chunks"],"summary":"List project chunks","description":"Lists 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":"number","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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/resources":{"get":{"tags":["Resources"],"summary":"List Project Resources","description":"Lists project-defined resource documents from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"required":false,"description":"Provide the runtime target kind.","name":"runtime_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true,"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","nullable":true},"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":{"nullable":true}}},"required":["kind","source_kind","source_path","code","message"]}}},"required":["data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"post":{"tags":["Resources"],"summary":"Create Project Resource","description":"Creates a structured project resource source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string"},"required":false,"name":"source_target_kind","in":"query"},{"schema":{"type":"string","nullable":true,"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","nullable":true}},"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/resources/{resource_id}":{"get":{"tags":["Resources"],"summary":"Get Project Resource","description":"Returns the structured project resource document from the selected source target.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}}}},"put":{"tags":["Resources"],"summary":"Update Project Resource","description":"Updates a structured project resource source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"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","nullable":true}}}}}},"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","nullable":true},"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/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}},"delete":{"tags":["Resources"],"summary":"Delete Project Resource","description":"Deletes a structured project resource source file.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true,"format":"uuid"},"required":false,"name":"target_branch_id","in":"query"}],"responses":{"200":{"description":"Resource deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"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"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"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"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"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"}}}}}}}}},"/projects/{project_reference}/commit":{"post":{"operationId":"commit","tags":["Branches"],"summary":"Commit Project Files","description":"Commits pending project file changes.","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","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":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"409":{"description":"File has been modified since it was read"},"500":{"description":"Server error"}}}},"/projects/{project_reference}/cache/get":{"get":{"operationId":"cacheGet","tags":["Project Cache"],"summary":"Get Cache Entry","description":"Retrieve a value from the project-scoped cache.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"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","nullable":true}},"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":"Retrieve multiple values from the project-scoped cache in a single request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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","nullable":true}},"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":"List cache keys for a project with optional pattern filtering and pagination.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9_:.*\\-/]+$","description":"Optional key pattern filter such as \"transform:*\"."},"required":false,"description":"Provide the pattern.","name":"pattern","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from a previous response."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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"}},"count":{"type":"number"},"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}},"required":["keys","count","cursor","has_more"]}}}},"400":{"description":"Invalid pattern or limit."},"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":"Get cache statistics including total keys, keys by prefix, and sample keys.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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":"Store a value in the project-scoped cache with optional TTL.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"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":"Store multiple values in the project-scoped cache in a single request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"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":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"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":"number"}},"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":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"}],"responses":{"200":{"description":"Number of keys deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"number"}},"required":["deleted"]}}}},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden."},"500":{"description":"Server error."}}}},"/projects/{project_reference}/environments/{environment_id}/servers":{"post":{"operationId":"createServer","tags":["Project Servers"],"summary":"Create Project Server","description":"Creates a server for an environment.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","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":{"201":{"description":"Server created.","content":{"application/json":{"schema":{"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"]}}}},"400":{"description":"Invalid input."},"401":{"description":"Unauthorized."},"404":{"description":"Environment not found."}}}},"/projects/{project_reference}/servers":{"get":{"operationId":"listProjectServers","tags":["Project Servers"],"summary":"List Project Servers","description":"Lists servers for a project.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","description":"Cursor for pagination (server ID)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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":{"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"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized."}}}},"/projects/{project_reference}/servers/{server_id}":{"get":{"operationId":"getServer","tags":["Project Servers"],"summary":"Get Project Server","description":"Returns a project server by ID.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"server_id","in":"path"}],"responses":{"200":{"description":"Server details.","content":{"application/json":{"schema":{"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"]}}}},"401":{"description":"Unauthorized."},"404":{"description":"Server not found."}}},"delete":{"operationId":"deleteServer","tags":["Project Servers"],"summary":"Delete Project Server","description":"Marks a project server for deletion.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"server_id","in":"path"}],"responses":{"200":{"description":"Server marked for deletion.","content":{"application/json":{"schema":{"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"]}}}},"401":{"description":"Unauthorized."},"404":{"description":"Server not found."}}}},"/servers":{"post":{"operationId":"createRootServer","tags":["Root Servers"],"summary":"Create Server","description":"Creates 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":{"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"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Environment not found"}}},"get":{"operationId":"listUserServers","tags":["Root 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":{"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"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized"}}}},"/servers/{server_id}":{"get":{"operationId":"getRootServer","tags":["Root Servers"],"summary":"Get My Server","description":"Returns 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":{"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Server not found"}}},"delete":{"operationId":"deleteRootServer","tags":["Root 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":{"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Server not found"}}}},"/servers/{server_id}/environments/{environment_id}":{"post":{"operationId":"addServerEnvironment","tags":["Root Servers"],"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":{"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"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Server or environment not found"}}},"delete":{"operationId":"removeServerEnvironment","tags":["Root Servers"],"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":{"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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Server not found"}}}},"/projects/{project_reference}/logs":{"get":{"operationId":"getProjectLogs","tags":["Logs"],"summary":"Query Project Logs","description":"Query recent server logs for a project. Supports filtering by level, service, trace_id, request_id, and free-text search. Use next_cursor from the response to paginate.","parameters":[{"schema":{"type":"string"},"required":true,"name":"project_reference","in":"path"},{"schema":{"type":"string","format":"date-time","description":"Start time (ISO 8601). Defaults to 1 hour ago."},"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 within log messages"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._-]+$","description":"Filter by exact service name (e.g. \"veryfront-server\")"},"required":false,"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,"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,"name":"request_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."},"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","nullable":true,"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"]}}}},"401":{"description":"Unauthorized"},"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":["Metrics"],"summary":"Query Project Metrics","description":"Query 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."},"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 service_name or status_code."}},"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"},"401":{"description":"Unauthorized"},"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":["Traces"],"summary":"Query Project Traces","description":"Query 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."},"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."},"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."},"required":false,"name":"status","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Optional minimum trace duration in milliseconds."},"required":false,"name":"min_duration_ms","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"},"401":{"description":"Unauthorized"},"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":["Traces"],"summary":"Get Project Trace","description":"Get a compact project-scoped trace detail by trace ID from Grafana Cloud Tempo.","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","nullable":true,"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","nullable":true,"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","nullable":true,"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."},"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","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"},"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."}}}},"/sandbox-sessions":{"get":{"operationId":"listSandboxSessions","tags":["Sandboxes"],"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":{"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","nullable":true,"format":"uuid"},"ttl_mode":{"type":"string","enum":["default","duration","always_on"]},"ttl_hours":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"expires_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"last_activity_at":{"type":"string","nullable":true}},"required":["id","short_id","endpoint","status","project_id","ttl_mode","ttl_hours","expires_at","created_at","last_activity_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"400":{"description":"Validation failed."},"401":{"description":"Unauthorized."}}},"post":{"operationId":"createSandboxSession","tags":["Sandboxes"],"summary":"Create Sandbox Session","description":"Claim a warm sandbox pod or create a new one. Requires project_reference (or environment_id) — the sandbox is billed to that project.","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 platform idle/max lifetime cleanup."},"ttl_hours":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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":{"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","nullable":true,"format":"uuid"},"ttl_mode":{"type":"string","enum":["default","duration","always_on"]},"ttl_hours":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"expires_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"last_activity_at":{"type":"string","nullable":true}},"required":["id","short_id","endpoint","status","project_id","ttl_mode","ttl_hours","expires_at","created_at","last_activity_at"]}}}},"401":{"description":"Unauthorized."},"402":{"description":"Insufficient credits."}}}},"/sandbox-sessions/{session_id}":{"get":{"operationId":"getSandboxSession","tags":["Sandboxes"],"summary":"Get Sandbox Session","description":"Get 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":{"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","nullable":true,"format":"uuid"},"ttl_mode":{"type":"string","enum":["default","duration","always_on"]},"ttl_hours":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"expires_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"last_activity_at":{"type":"string","nullable":true}},"required":["id","short_id","endpoint","status","project_id","ttl_mode","ttl_hours","expires_at","created_at","last_activity_at"]}}}},"404":{"description":"Session not found."}}},"patch":{"operationId":"updateSandboxSessionLifetime","tags":["Sandboxes"],"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 platform idle/max lifetime cleanup."},"ttl_hours":{"type":"integer","minimum":0,"exclusiveMinimum":true,"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":{"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","nullable":true,"format":"uuid"},"ttl_mode":{"type":"string","enum":["default","duration","always_on"]},"ttl_hours":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"expires_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"last_activity_at":{"type":"string","nullable":true}},"required":["id","short_id","endpoint","status","project_id","ttl_mode","ttl_hours","expires_at","created_at","last_activity_at"]}}}},"404":{"description":"Session not found."}}},"delete":{"operationId":"deleteSandboxSession","tags":["Sandboxes"],"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":["Sandboxes"],"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}/heartbeat":{"post":{"operationId":"sandboxSessionHeartbeat","tags":["Sandboxes"],"summary":"Sandbox Session Heartbeat","description":"Update the sandbox session last activity timestamp to prevent 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":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"404":{"description":"Session not found."}}}},"/sandbox-sessions/{session_id}/healthz":{"get":{"operationId":"checkSandboxSessionHealth","tags":["Sandboxes"],"summary":"Check Sandbox Health","description":"Read sandbox health through the authenticated API proxy.","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":["Sandboxes"],"summary":"Check Sandbox Readiness","description":"Read sandbox readiness through the authenticated API proxy.","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}/commands/run":{"post":{"operationId":"runSandboxSessionCommand","tags":["Sandboxes"],"summary":"Run Sandbox Command","description":"Run a short-lived command in a sandbox session through the authenticated API proxy.","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":["Sandboxes"],"summary":"Stream Sandbox Command","description":"Run a command in a sandbox session and preserve the upstream NDJSON stream through the authenticated API proxy.","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}/terminal":{"get":{"operationId":"openSandboxSessionTerminal","tags":["Sandboxes"],"summary":"Open Sandbox Terminal","description":"Serve the authenticated terminal page. The browser websocket upgrades on the same API path and the API bridges it 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}/commands":{"get":{"operationId":"listSandboxSessionBackgroundCommands","tags":["Sandboxes"],"summary":"List Sandbox Background Commands","description":"List background commands for a sandbox session through the authenticated API proxy.","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":["Sandboxes"],"summary":"Start Sandbox Background Command","description":"Start a background command in a sandbox session through the authenticated API proxy.","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":["Sandboxes"],"summary":"Get Sandbox Background Command","description":"Read background command status for a sandbox session through the authenticated API proxy.","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":["Sandboxes"],"summary":"Get Sandbox Background Command Output","description":"Read background command output for a sandbox session through the authenticated API proxy.","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":["Sandboxes"],"summary":"Cancel Sandbox Background Command","description":"Cancel a background command in a sandbox session through the authenticated API proxy.","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}/file":{"get":{"operationId":"readSandboxSessionFile","tags":["Sandboxes"],"summary":"Read Sandbox File","description":"Read a file from a sandbox session through the authenticated API proxy.","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}/files":{"get":{"operationId":"listSandboxSessionFiles","tags":["Sandboxes"],"summary":"List Sandbox Files","description":"List files in a sandbox session directory through the authenticated API proxy.","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":["Sandboxes"],"summary":"Write Sandbox Files","description":"Write one or more files into a sandbox session through the authenticated API proxy.","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."}}}},"/ai/models":{"get":{"tags":["AI"],"summary":"List Models","description":"Returns available AI models and providers.","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"},"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"}},"required":["webResearch","streaming","tools","vision"],"description":"Model capability flags"},"temperature":{"type":"object","nullable":true,"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 by this model","example":["web_search","web_fetch"]},"pricing":{"type":"object","properties":{"inputUsdPer1M":{"type":"number","minimum":0,"description":"Input-token price per 1M tokens"},"outputUsdPer1M":{"type":"number","minimum":0,"description":"Output-token price per 1M tokens"},"cacheCreationInputUsdPer1M":{"type":"number","minimum":0,"description":"Cache-write input-token price per 1M tokens when the provider bills it separately"},"cacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price per 1M tokens when the provider bills it separately"},"audioInputUsdPer1M":{"type":"number","minimum":0,"description":"Audio input-token price per 1M tokens when the provider bills it separately"},"audioOutputUsdPer1M":{"type":"number","minimum":0,"description":"Audio output-token price per 1M tokens when the provider bills it separately"},"audioCacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price per 1M tokens when the provider bills it separately"}},"required":["inputUsdPer1M","outputUsdPer1M"],"description":"Public Veryfront customer pricing after markup, used for client-side customer cost estimates"},"providerPricing":{"type":"object","properties":{"inputUsdPer1M":{"type":"number","minimum":0,"description":"Input-token price per 1M tokens"},"outputUsdPer1M":{"type":"number","minimum":0,"description":"Output-token price per 1M tokens"},"cacheCreationInputUsdPer1M":{"type":"number","minimum":0,"description":"Cache-write input-token price per 1M tokens when the provider bills it separately"},"cacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price per 1M tokens when the provider bills it separately"},"audioInputUsdPer1M":{"type":"number","minimum":0,"description":"Audio input-token price per 1M tokens when the provider bills it separately"},"audioOutputUsdPer1M":{"type":"number","minimum":0,"description":"Audio output-token price per 1M tokens when the provider bills it separately"},"audioCacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price per 1M tokens when the provider bills it separately"},"tiers":{"type":"array","items":{"type":"object","properties":{"inputUsdPer1M":{"type":"number","minimum":0,"description":"Input-token price per 1M tokens"},"outputUsdPer1M":{"type":"number","minimum":0,"description":"Output-token price per 1M tokens"},"cacheCreationInputUsdPer1M":{"type":"number","minimum":0,"description":"Cache-write input-token price per 1M tokens when the provider bills it separately"},"cacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Cache-read input-token price per 1M tokens when the provider bills it separately"},"audioInputUsdPer1M":{"type":"number","minimum":0,"description":"Audio input-token price per 1M tokens when the provider bills it separately"},"audioOutputUsdPer1M":{"type":"number","minimum":0,"description":"Audio output-token price per 1M tokens when the provider bills it separately"},"audioCacheReadInputUsdPer1M":{"type":"number","minimum":0,"description":"Audio cache-read token price per 1M tokens when the provider bills it separately"},"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","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"],"description":"Raw provider token pricing before Veryfront markup"},"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"}},"required":["id","modelId","provider","providerLabel","providerLogoKey","name","aliases","capabilities","temperature","supportedProviderTools","pricing","providerPricing","pricingSources"]},"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":"openai/gpt-5.4-nano"}},"required":["models","providers","defaultModelId"]}}}}}}},"/ai/gateway/billing/finalize":{"post":{"tags":["AI"],"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":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"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":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"404":{"description":"Billing group not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"409":{"description":"Billing group usage is not ready to finalize","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}}}}},"/ai/gateway/{provider}/{path}":{"post":{"tags":["AI"],"summary":"Proxy AI Request","description":"Proxies an AI request to the selected provider.","parameters":[{"schema":{"type":"string","enum":["anthropic","openai","google","mistral","moonshotai"],"description":"Provider.","example":"anthropic"},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Provider path.","example":"v1/messages"},"required":true,"name":"path","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":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true},"description":"Provider-specific request body (forwarded as-is to upstream)"}}}},"responses":{"200":{"description":"Upstream provider response (forwarded as-is)"},"400":{"description":"Invalid provider, request, or agent-run context","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"402":{"description":"Insufficient AI credits","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":"Agent run attribution does not match the durable run","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"500":{"description":"Gateway admission or durable accounting failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"502":{"description":"Gateway proxy error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable error code"}},"required":["error"]}}}}}}},"/agent-workers/projects/{project_reference}/workers":{"get":{"tags":["Agent Workers"],"summary":"List connected agent workers","description":"Lists the agent workers connected to a project, with cursor-based pagination.","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":"Agent workers connected to the project","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","nullable":true},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"],"description":"The connection status associated with this tool result."},"metadata":{"nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}},"post":{"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","nullable":true,"minLength":1,"maxLength":128},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"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","nullable":true},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"],"description":"The connection status associated with this tool result."},"metadata":{"nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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","nullable":true}},"required":["worker"]}}}}}}},"/agent-workers/workers/{worker_id}/heartbeat":{"post":{"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","nullable":true},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"],"description":"The connection status associated with this tool result."},"metadata":{"nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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","nullable":true}},"required":["worker"]}}}}}}},"/agent-workers/workers/{worker_id}":{"delete":{"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"}}}},"/agent-workers/workers/{worker_id}/claim":{"post":{"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","nullable":true,"properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"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","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"request_snapshot":{"type":"object","nullable":true,"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":{"nullable":true}},"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"]}]},"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":{"nullable":true}},"inputSchema":{"type":"object","additionalProperties":{"nullable":true}},"outputSchema":{"type":"object","additionalProperties":{"nullable":true}}},"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":{"nullable":true}}},"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","minimum":0,"exclusiveMinimum":true}},"required":["enabled"],"additionalProperties":false},"model":{"type":"string","minLength":1,"maxLength":256},"temperature":{"type":"number","minimum":0,"maximum":2},"maxSteps":{"type":"integer","minimum":0,"exclusiveMinimum":true},"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}]},"delegates":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500}},"required":["id","name","instructions"]},"forwardedProps":{"type":"object","additionalProperties":{"nullable":true}},"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","nullable":true,"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","nullable":true,"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","nullable":true,"minLength":1},"policyGenerationId":{"type":"string","nullable":true,"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":{"nullable":true}}},"required":["messages","agentSource"]},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"lease_owner":{"type":"string","nullable":true},"lease_expires_at":{"type":"string","nullable":true},"worker_session":{"type":"object","nullable":true,"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","nullable":true,"format":"uuid"},"session_key":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","completed","failed","cancelled"]},"metadata":{"nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"ended_at":{"type":"string","nullable":true}},"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"]}},"required":["run"]}}}}}}},"/agent-workers/workers/{worker_id}/runs/{run_id}/lease":{"post":{"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","nullable":true,"properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"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","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"request_snapshot":{"type":"object","nullable":true,"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":{"nullable":true}},"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"]}]},"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":{"nullable":true}},"inputSchema":{"type":"object","additionalProperties":{"nullable":true}},"outputSchema":{"type":"object","additionalProperties":{"nullable":true}}},"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":{"nullable":true}}},"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","minimum":0,"exclusiveMinimum":true}},"required":["enabled"],"additionalProperties":false},"model":{"type":"string","minLength":1,"maxLength":256},"temperature":{"type":"number","minimum":0,"maximum":2},"maxSteps":{"type":"integer","minimum":0,"exclusiveMinimum":true},"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}]},"delegates":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":500}},"required":["id","name","instructions"]},"forwardedProps":{"type":"object","additionalProperties":{"nullable":true}},"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","nullable":true,"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","nullable":true,"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","nullable":true,"minLength":1},"policyGenerationId":{"type":"string","nullable":true,"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":{"nullable":true}}},"required":["messages","agentSource"]},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"lease_owner":{"type":"string","nullable":true},"lease_expires_at":{"type":"string","nullable":true},"worker_session":{"type":"object","nullable":true,"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","nullable":true,"format":"uuid"},"session_key":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","completed","failed","cancelled"]},"metadata":{"nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"ended_at":{"type":"string","nullable":true}},"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"]}},"required":["run"]}}}}}}},"/agent-workers/workers/{worker_id}/runs/{run_id}/session":{"put":{"tags":["Agent Workers"],"summary":"Record agent worker session state for a run","description":"Creates 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","nullable":true,"additionalProperties":{"nullable":true}}},"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","nullable":true,"format":"uuid"},"session_key":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","completed","failed","cancelled"]},"metadata":{"nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"ended_at":{"type":"string","nullable":true}},"required":["id","run_id","implementation_kind","worker_id","session_key","status","created_at","updated_at","ended_at"]}},"required":["session"]}}}}}}},"/agent-runtimes/push-services":{"get":{"tags":["Agent Runtimes"],"summary":"List global agent push runtime services","description":"Lists globally registered push-based agent runtime services for operational visibility. Requires platform admin 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","nullable":true,"format":"uuid"},"agent_id":{"type":"string","nullable":true},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{"nullable":true},"metadata":{"nullable":true},"version":{"type":"string","nullable":true},"runtime":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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","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","nullable":true},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"]},"metadata":{"nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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"]}}}}}},"post":{"tags":["Agent Runtimes"],"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 admin 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","nullable":true},"project_id":{"type":"string","nullable":true},"projectId":{"type":"string","nullable":true},"agent_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"capabilities":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"region":{"type":"string","nullable":true,"minLength":1,"maxLength":128}},"required":["service_name","base_url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Agent push runtime service registered","content":{"application/json":{"schema":{"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","nullable":true,"format":"uuid"},"agent_id":{"type":"string","nullable":true},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{"nullable":true},"metadata":{"nullable":true},"version":{"type":"string","nullable":true},"runtime":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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","version","runtime","region","last_heartbeat_at","created_at","updated_at"]}},"required":["service"]}}}}}}},"/agent-runtimes/projects/{project_reference}/targets":{"get":{"tags":["Agent Runtimes"],"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","nullable":true,"format":"uuid"},"agent_id":{"type":"string","nullable":true},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{"nullable":true},"metadata":{"nullable":true},"version":{"type":"string","nullable":true},"runtime":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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","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","nullable":true},"status":{"type":"string","enum":["active","disabled"]},"connection_status":{"type":"string","enum":["online","offline","disabled"]},"metadata":{"nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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"]}}}}}}},"/agent-runtimes/push-services/{service_id}/heartbeat":{"post":{"tags":["Agent Runtimes"],"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":{"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","nullable":true,"format":"uuid"},"agent_id":{"type":"string","nullable":true},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{"nullable":true},"metadata":{"nullable":true},"version":{"type":"string","nullable":true},"runtime":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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","version","runtime","region","last_heartbeat_at","created_at","updated_at"]}},"required":["service"]}}}}}}},"/agent-runtimes/push-services/{service_id}/drain":{"post":{"tags":["Agent Runtimes"],"summary":"Drain an agent push runtime service","description":"Disables new runtime selection while preserving the registered endpoint and heartbeats for a safe deployment drain.","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":{"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","nullable":true,"format":"uuid"},"agent_id":{"type":"string","nullable":true},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{"nullable":true},"metadata":{"nullable":true},"version":{"type":"string","nullable":true},"runtime":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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","version","runtime","region","last_heartbeat_at","created_at","updated_at"]}},"required":["service"]}}}}}}},"/agent-runtimes/push-services/{service_id}/resume":{"post":{"tags":["Agent Runtimes"],"summary":"Resume an agent push runtime service","description":"Re-enables runtime selection after a deployment drain. Requires access to the service scope.","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":{"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","nullable":true,"format":"uuid"},"agent_id":{"type":"string","nullable":true},"base_url":{"type":"string","format":"uri"},"invoke_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"capabilities":{"nullable":true},"metadata":{"nullable":true},"version":{"type":"string","nullable":true},"runtime":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"last_heartbeat_at":{"type":"string","nullable":true},"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","version","runtime","region","last_heartbeat_at","created_at","updated_at"]}},"required":["service"]}}}}}}},"/cache/get":{"get":{"operationId":"userCacheGet","tags":["User Cache"],"summary":"Get User Cache Entry","description":"Retrieves 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","nullable":true}},"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":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"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":"Deletes 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":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Invalid cache key."},"401":{"description":"Unauthorized."},"500":{"description":"Server error."}}}},"/runs":{"post":{"tags":["Runs"],"summary":"Create a canonical durable run","description":"Creates a canonical durable run for an owner scope and returns the accepted run envelope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"public_id":{"type":"string","minLength":1,"maxLength":128},"parent_run_id":{"type":"string","minLength":1,"maxLength":128},"trigger":{"type":"object","properties":{"conversation_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"tool_call_id":{"type":"string","minLength":1,"maxLength":128}},"additionalProperties":false},"kind":{"type":"string","enum":["agent"]},"owner":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["conversation"]},"id":{"type":"string","format":"uuid"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["project"]},"id":{"type":"string","format":"uuid"}},"required":["kind","id"],"additionalProperties":false}]},"composing_user_id":{"type":"string","format":"uuid","description":"Account that composed a conversation-owned agent run. The API rejects the run if the authenticated account changed before creation."},"conversation_mode":{"type":"string","enum":["create_new","existing","none"],"default":"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","format":"uuid","description":"Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."},"request":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["agent"]},"agent_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Unique identifier for the record."},"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."},"initial_status":{"type":"string","enum":["pending","running"]},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["mode","agent_id","implementation_kind"],"additionalProperties":false,"title":"RuntimeAgentRequest"},{"type":"object","properties":{"mode":{"type":"string","enum":["agent"]},"agent_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Unique identifier for the record."},"initial_status":{"type":"string","enum":["pending","running"]},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{}}},"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":{"nullable":true}},"inputSchema":{"type":"object","additionalProperties":{"nullable":true}},"outputSchema":{"type":"object","additionalProperties":{"nullable":true}}},"required":["name"]},"maxItems":50},"context":{"type":"object","properties":{"conversation_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"project_reference":{"type":"string","nullable":true,"minLength":1},"branch_id":{"type":"string","nullable":true,"format":"uuid"},"environment_context":{"type":"string"}},"required":["project_id","branch_id"],"additionalProperties":false},"model":{"type":"string"},"active_chat_id":{"type":"string"},"allow_delegation":{"type":"boolean"},"forwarded_props":{"type":"object","additionalProperties":{"nullable":true}},"runtime_overrides":{"type":"object","properties":{"allowed_tools":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"thinking":{"anyOf":[{"type":"boolean","enum":[false]},{"type":"integer","minimum":0,"exclusiveMinimum":true}]},"max_steps":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"additionalProperties":false},"durable_root_run":{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"maxLength":128},"message_id":{"type":"string","format":"uuid"}},"required":["run_id","message_id"],"additionalProperties":false}},"required":["messages","context"],"additionalProperties":false}},"required":["mode","agent_id"],"additionalProperties":false,"title":"HostedDefaultChatAgentRequest"},{"type":"object","properties":{"mode":{"type":"string","enum":["agent"]},"input":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Unique identifier for the record."},"task_id":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]*$","description":"Provide the task id."},"source_target_kind":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"allow_delegation":{"type":"boolean","default":true},"messages":{"type":"array","items":{"nullable":true},"maxItems":0,"default":[]},"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":{"nullable":true}},"inputSchema":{"type":"object","additionalProperties":{"nullable":true}},"outputSchema":{"type":"object","additionalProperties":{"nullable":true}}},"required":["name"]},"maxItems":50,"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":{"nullable":true}}},"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"]}]},"maxItems":10,"default":[]},"forwarded_props":{"type":"object","additionalProperties":{"nullable":true}},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"target_branch_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["agent_id"],"additionalProperties":false},"timeout_seconds":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["mode","input"],"additionalProperties":false,"title":"ProjectAgentStreamAgentRequest"}]}},"required":["kind","owner","request"],"additionalProperties":false,"title":"agent"},{"type":"object","properties":{"public_id":{"type":"string","minLength":1,"maxLength":128},"parent_run_id":{"type":"string","minLength":1,"maxLength":128},"trigger":{"type":"object","properties":{"conversation_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"tool_call_id":{"type":"string","minLength":1,"maxLength":128}},"additionalProperties":false},"kind":{"type":"string","enum":["workflow"]},"owner":{"type":"object","properties":{"kind":{"type":"string","enum":["project"]},"id":{"type":"string","format":"uuid"}},"required":["kind","id"],"additionalProperties":false},"request":{"type":"object","properties":{"workflow_id":{"type":"string","minLength":1,"maxLength":255},"target":{"type":"string","minLength":1,"maxLength":512},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"type":"object","additionalProperties":{"nullable":true}},"start_mode":{"type":"string","minLength":1,"maxLength":64}},"required":["workflow_id","target"],"additionalProperties":false}},"required":["kind","owner","request"],"additionalProperties":false,"title":"workflow"},{"type":"object","properties":{"public_id":{"type":"string","minLength":1,"maxLength":128},"parent_run_id":{"type":"string","minLength":1,"maxLength":128},"trigger":{"type":"object","properties":{"conversation_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"tool_call_id":{"type":"string","minLength":1,"maxLength":128}},"additionalProperties":false},"kind":{"type":"string","enum":["task"]},"owner":{"type":"object","properties":{"kind":{"type":"string","enum":["project"]},"id":{"type":"string","format":"uuid"}},"required":["kind","id"],"additionalProperties":false},"request":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable task run name."},"target":{"type":"string","minLength":1,"maxLength":512},"batch_id":{"type":"string","format":"uuid","description":"Batch UUID to group related task runs."},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"config":{"type":"object","additionalProperties":{"nullable":true}},"timeout_seconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"backoff_limit":{"type":"integer","minimum":0}},"required":["target"],"additionalProperties":false}},"required":["kind","owner","request"],"additionalProperties":false,"title":"task"},{"type":"object","properties":{"public_id":{"type":"string","minLength":1,"maxLength":128},"parent_run_id":{"type":"string","minLength":1,"maxLength":128},"trigger":{"type":"object","properties":{"conversation_id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"tool_call_id":{"type":"string","minLength":1,"maxLength":128}},"additionalProperties":false},"kind":{"type":"string","enum":["eval"]},"owner":{"type":"object","properties":{"kind":{"type":"string","enum":["project"]},"id":{"type":"string","format":"uuid"}},"required":["kind","id"],"additionalProperties":false},"request":{"type":"object","properties":{"target":{"type":"string","minLength":1,"maxLength":512},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"type":"object","additionalProperties":{"nullable":true}},"config":{"type":"object","additionalProperties":{"nullable":true}},"start_mode":{"type":"string","minLength":1,"maxLength":64}},"required":["target"],"additionalProperties":false}},"required":["kind","owner","request"],"additionalProperties":false,"title":"eval"}]}}}},"responses":{"202":{"description":"Run accepted","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"},"run":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"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},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"usage":{"type":"object","nullable":true,"properties":{"requests":{"type":"integer","minimum":0},"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"cache_creation_input_tokens":{"type":"integer","minimum":0},"cache_read_input_tokens":{"type":"integer","minimum":0},"reasoning_tokens":{"type":"integer","minimum":0},"cost_credits":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]}},"required":["requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","reasoning_tokens","cost_credits"]},"tool_error_count":{"type":"integer","minimum":0},"children_failed":{"type":"boolean"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"root_run_id":{"type":"string","minLength":1},"waiting_reason":{"type":"string","nullable":true,"enum":["tool","approval","event","input"]},"metadata":{"nullable":true},"target":{"type":"string","nullable":true},"workflow_id":{"type":"string","nullable":true},"schedule_id":{"type":"string","nullable":true,"format":"uuid"},"batch_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"nullable":true},"config":{"nullable":true},"output":{"nullable":true},"error":{"type":"object","nullable":true,"properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]},"logs":{"type":"string","nullable":true},"artifacts":{"type":"array","items":{"nullable":true}},"duration_ms":{"type":"integer","nullable":true},"exit_code":{"type":"integer","nullable":true},"start_mode":{"type":"string","nullable":true},"timeout_seconds":{"type":"integer","nullable":true},"backoff_limit":{"type":"integer","nullable":true},"trigger_kind":{"type":"string","nullable":true,"enum":["manual","schedule","webhook","api"]},"trigger_id":{"type":"string","nullable":true},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"updated_at":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"required":["run_id","kind","status","owner","conversation_id","message_id","usage","tool_error_count","children_failed","parent_run_id","root_run_id","waiting_reason","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","trigger_kind","trigger_id","created_by","updated_at","created_at","started_at","completed_at"]},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["accepted","run"]}}}}}}},"/runs/event-types":{"get":{"tags":["Runs"],"summary":"List canonical run event types","description":"Returns the canonical uppercase run event vocabulary: AG-UI types, control-plane types with legacy aliases, and the extension-scoped typed events that replace CUSTOM names under format=typed. Each entry carries its event class, lifecycle status, what a viewer-access caller sees of its payload, and its declared payload fields.","responses":{"200":{"description":"Run event type overview","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","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}},"renames_to":{"type":"string","minLength":1},"custom_names":{"type":"array","items":{"type":"string","minLength":1}}},"required":["type","scope","event_class","status","viewer_visibility","description","fields"],"additionalProperties":false}}},"required":["data"]}}}}}}},"/runs/{run_id}":{"get":{"tags":["Runs"],"summary":"Get a canonical durable run","description":"Fetches a canonical durable run after verifying viewer access to the run owner scope.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"responses":{"200":{"description":"Run summary","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"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},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"usage":{"type":"object","nullable":true,"properties":{"requests":{"type":"integer","minimum":0},"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"cache_creation_input_tokens":{"type":"integer","minimum":0},"cache_read_input_tokens":{"type":"integer","minimum":0},"reasoning_tokens":{"type":"integer","minimum":0},"cost_credits":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]}},"required":["requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","reasoning_tokens","cost_credits"]},"tool_error_count":{"type":"integer","minimum":0},"children_failed":{"type":"boolean"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"root_run_id":{"type":"string","minLength":1},"waiting_reason":{"type":"string","nullable":true,"enum":["tool","approval","event","input"]},"metadata":{"nullable":true},"target":{"type":"string","nullable":true},"workflow_id":{"type":"string","nullable":true},"schedule_id":{"type":"string","nullable":true,"format":"uuid"},"batch_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"nullable":true},"config":{"nullable":true},"output":{"nullable":true},"error":{"type":"object","nullable":true,"properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]},"logs":{"type":"string","nullable":true},"artifacts":{"type":"array","items":{"nullable":true}},"duration_ms":{"type":"integer","nullable":true},"exit_code":{"type":"integer","nullable":true},"start_mode":{"type":"string","nullable":true},"timeout_seconds":{"type":"integer","nullable":true},"backoff_limit":{"type":"integer","nullable":true},"trigger_kind":{"type":"string","nullable":true,"enum":["manual","schedule","webhook","api"]},"trigger_id":{"type":"string","nullable":true},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"updated_at":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"required":["run_id","kind","status","owner","conversation_id","message_id","usage","tool_error_count","children_failed","parent_run_id","root_run_id","waiting_reason","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","trigger_kind","trigger_id","created_by","updated_at","created_at","started_at","completed_at"]}}}}}}},"/projects/{project_reference}/runs":{"get":{"tags":["Runs"],"summary":"List project runs","description":"Lists canonical durable runs owned by a project for callers with project run read access.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"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":"Provide the task id.","name":"task_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at","status","duration"],"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":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Project runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"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},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"usage":{"type":"object","nullable":true,"properties":{"requests":{"type":"integer","minimum":0},"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"cache_creation_input_tokens":{"type":"integer","minimum":0},"cache_read_input_tokens":{"type":"integer","minimum":0},"reasoning_tokens":{"type":"integer","minimum":0},"cost_credits":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]}},"required":["requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","reasoning_tokens","cost_credits"]},"tool_error_count":{"type":"integer","minimum":0},"children_failed":{"type":"boolean"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"root_run_id":{"type":"string","minLength":1},"waiting_reason":{"type":"string","nullable":true,"enum":["tool","approval","event","input"]},"metadata":{"nullable":true},"target":{"type":"string","nullable":true},"workflow_id":{"type":"string","nullable":true},"schedule_id":{"type":"string","nullable":true,"format":"uuid"},"batch_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"nullable":true},"config":{"nullable":true},"output":{"nullable":true},"error":{"type":"object","nullable":true,"properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]},"logs":{"type":"string","nullable":true},"artifacts":{"type":"array","items":{"nullable":true}},"duration_ms":{"type":"integer","nullable":true},"exit_code":{"type":"integer","nullable":true},"start_mode":{"type":"string","nullable":true},"timeout_seconds":{"type":"integer","nullable":true},"backoff_limit":{"type":"integer","nullable":true},"trigger_kind":{"type":"string","nullable":true,"enum":["manual","schedule","webhook","api"]},"trigger_id":{"type":"string","nullable":true},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"updated_at":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"required":["run_id","kind","status","owner","conversation_id","message_id","usage","tool_error_count","children_failed","parent_run_id","root_run_id","waiting_reason","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","trigger_kind","trigger_id","created_by","updated_at","created_at","started_at","completed_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}}},"/projects/{project_reference}/schedules/{schedule_id}/runs":{"post":{"tags":["Runs"],"summary":"Create a run from a schedule","description":"Creates a canonical run from a project schedule. The run kind is derived from the schedule target: task, workflow, or agent. Manual agent runs use the authenticated caller identity; background scheduler triggers remain automation. Execution continues through the runtime target selected for the run.","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":{"run_name":{"type":"string","minLength":1,"maxLength":255},"idempotency_key":{"type":"string","minLength":1,"maxLength":255}},"additionalProperties":false}}}},"responses":{"201":{"description":"Scheduled run accepted","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"run_execution_id":{"type":"string","minLength":1},"schedule_id":{"type":"string","format":"uuid"}},"required":["run_id","run_execution_id","schedule_id"],"additionalProperties":false}}}}}}},"/runs/{run_id}/children":{"get":{"tags":["Runs"],"summary":"List child runs for a canonical durable run","description":"Lists child runs spawned from a parent canonical run for callers with viewer access.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"responses":{"200":{"description":"Child runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"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},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"usage":{"type":"object","nullable":true,"properties":{"requests":{"type":"integer","minimum":0},"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"cache_creation_input_tokens":{"type":"integer","minimum":0},"cache_read_input_tokens":{"type":"integer","minimum":0},"reasoning_tokens":{"type":"integer","minimum":0},"cost_credits":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]}},"required":["requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","reasoning_tokens","cost_credits"]},"tool_error_count":{"type":"integer","minimum":0},"children_failed":{"type":"boolean"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"root_run_id":{"type":"string","minLength":1},"waiting_reason":{"type":"string","nullable":true,"enum":["tool","approval","event","input"]},"metadata":{"nullable":true},"target":{"type":"string","nullable":true},"workflow_id":{"type":"string","nullable":true},"schedule_id":{"type":"string","nullable":true,"format":"uuid"},"batch_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"nullable":true},"config":{"nullable":true},"output":{"nullable":true},"error":{"type":"object","nullable":true,"properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]},"logs":{"type":"string","nullable":true},"artifacts":{"type":"array","items":{"nullable":true}},"duration_ms":{"type":"integer","nullable":true},"exit_code":{"type":"integer","nullable":true},"start_mode":{"type":"string","nullable":true},"timeout_seconds":{"type":"integer","nullable":true},"backoff_limit":{"type":"integer","nullable":true},"trigger_kind":{"type":"string","nullable":true,"enum":["manual","schedule","webhook","api"]},"trigger_id":{"type":"string","nullable":true},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"updated_at":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"required":["run_id","kind","status","owner","conversation_id","message_id","usage","tool_error_count","children_failed","parent_run_id","root_run_id","waiting_reason","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","trigger_kind","trigger_id","created_by","updated_at","created_at","started_at","completed_at"]}}},"required":["data"]}}}}}},"post":{"tags":["Runs"],"summary":"Ensure an idempotent child agent run","description":"Creates one child agent run per parent run and tool-call identity. Exact retries return the existing child, while later parent retry runs reuse the task conversation. When request.idempotency_scope is durable_task, the same durable task and tool-call identity replays the original child run across parent runs.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tool_call_id":{"type":"string","minLength":1,"maxLength":128},"request":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"description":"Provide the prompt."},"task_id":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]*$","description":"Provide the task id."},"context_mode":{"type":"string","enum":["continue","fresh"],"description":"Provide the context mode."},"idempotency_scope":{"type":"string","enum":["durable_task"],"description":"Provide the idempotency scope."},"context":{"type":"object","additionalProperties":{"nullable":true,"description":"Additional structured values supplied to the tool."},"default":{},"description":"Provide the context."},"evidence_refs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Unique identifier for the target record."},"run_id":{"type":"string","minLength":1,"description":"Run identifier that scopes the request."},"message_id":{"type":"string","minLength":1,"description":"Provide the message id."},"tool_call_id":{"type":"string","minLength":1,"description":"Tool call identifier that links this request to a prior tool invocation."},"result_path":{"type":"string","minLength":1,"description":"Provide the result path."},"label":{"type":"string","minLength":1,"description":"Provide the label."},"summary":{"type":"string","minLength":1,"description":"Provide the summary."}},"description":"One evidence ref item supplied to the tool."},"maxItems":50,"description":"Provide the evidence refs."},"description":{"type":"string","minLength":1,"description":"Human-readable description that clarifies the request."},"agent_id":{"type":"string","minLength":1,"description":"Provide the agent id."},"project_id":{"type":"string","format":"uuid","description":"Project identifier for the target project."},"runtime_target_kind":{"type":"string","enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"target_environment_id":{"type":"string","nullable":true,"format":"uuid","description":"Provide the target environment id."},"target_branch_id":{"type":"string","nullable":true,"format":"uuid","description":"Provide the target branch id."},"source_target_kind":{"type":"string","enum":["project","main_branch","environment","preview_branch"],"description":"Provide the source target kind."},"allow_delegation":{"type":"boolean","description":"Provide the allow delegation."},"tools":{"type":"array","items":{"type":"string","minLength":1,"description":"One tool item supplied to the tool."},"maxItems":500,"description":"Provide the tools."},"model":{"type":"string","minLength":1,"description":"AI model id or alias. Call list_models for the ids this deployment serves; never invent a version suffix."},"thinking":{"anyOf":[{"type":"boolean","enum":[false],"description":"Provide the option 1."},{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Provide the option 2."}],"description":"Provide the thinking."},"max_steps":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Provide the max steps."}},"description":"Structured request details used by the tool."}},"required":["tool_call_id","request"],"additionalProperties":false}}}},"responses":{"200":{"description":"Child run ensured","content":{"application/json":{"schema":{"type":"object","properties":{"child_conversation_id":{"type":"string","format":"uuid"},"child_run_id":{"type":"string","minLength":1},"child_message_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1},"duplicate":{"type":"boolean"}},"required":["child_conversation_id","child_run_id","child_message_id","agent_id","duplicate"],"additionalProperties":false}}}},"403":{"description":"The caller may not create a child from this run or in the target project"},"404":{"description":"Parent run not found"},"409":{"description":"The parent/tool-call identity was reused with a different request"}}}},"/runs/{parent_run_id}/children/{child_run_id}/event-writer-token":{"post":{"tags":["Runs"],"security":[{"runEventWriterAuth":[]}],"summary":"Mint a child run event writer token","description":"Delegates an expiring event-writer credential from an authenticated parent runtime to its direct child run, scoped to the child run identity and project.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"required":true,"name":"parent_run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"required":true,"name":"child_run_id","in":"path"}],"responses":{"200":{"description":"Child run event writer token","content":{"application/json":{"schema":{"type":"object","properties":{"run_event_token":{"type":"string","minLength":1}},"required":["run_event_token"],"additionalProperties":false}}}},"401":{"description":"A valid parent run event writer token is required"},"404":{"description":"Child run not found"}}}},"/runs/{run_id}/events":{"get":{"tags":["Runs"],"summary":"List events for a canonical durable run","description":"Lists every durable event type. Callers with editor access receive full diagnostic payloads including model call context; callers with only viewer access receive the sanitized public payload projection. Opaque provider replay blocks are always redacted. Clients may request up to 100 events; each page returns the ordered prefix that fits the aggregate serialized-byte budget, and an individually valid oversized first event is returned alone. Follow page_info.next with after_event_id to continue. This is a private, no-store API. Conversation polling, GraphQL, and SSE expose only their documented sanitized public projections. Pass format=typed to receive the typed contract: CUSTOM rows become typed events, TOOL_CALL_RESULT carries content and a nullable isError, and every row adds run_id, event_class, span_id, parent_span_id, turn_id, origin_event_type, origin_custom_name, and unrecoverable_fields. Cursor semantics are identical in both formats.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"after_event_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"errors_only","in":"query"},{"schema":{"type":"string","enum":["raw","typed"],"default":"raw","description":"Provide the format."},"required":false,"description":"Provide the format.","name":"format","in":"query"}],"responses":{"200":{"description":"Run events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","minLength":1},"payload":{"nullable":true},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"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","nullable":true,"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":"string","nullable":true,"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","nullable":true,"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","is_error","created_at"],"additionalProperties":false}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}},"post":{"tags":["Runs"],"security":[{"runEventWriterAuth":[]}],"summary":"Append events to a canonical durable run","description":"Appends runtime-produced events to a durable run using a run event writer token. This run-scoped path supports conversationless runs and is limited to credentials bound to the exact run.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expected_previous_event_id":{"type":"integer","nullable":true,"minimum":0},"expected_previous_external_event_sequence":{"type":"integer","nullable":true,"minimum":0},"external_sequence_scope":{"type":"string","enum":["agent","publish_only"]},"events":{"type":"array","items":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_START"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."},"role":{"type":"string","description":"The role associated with this record."}},"required":["type","messageId","contentId"],"description":"Structured option 1 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","messageId","contentId","delta"],"description":"Structured option 2 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_END"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."}},"required":["type","messageId","contentId"],"description":"Structured option 3 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_START"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"toolCallName":{"type":"string","minLength":1,"description":"The tool call name associated with this record."}},"required":["type","toolCallId","toolCallName"],"description":"Structured option 4 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_ARGS"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","toolCallId","delta"],"description":"Structured option 5 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_CHUNK"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","toolCallId","delta"],"description":"Structured option 6 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_END"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["type","toolCallId"],"description":"Structured option 7 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_RESULT"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"parentMessageId":{"type":"string","minLength":1,"description":"The parent message id associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"input":{"nullable":true,"description":"The input associated with this record."},"content":{"nullable":true,"description":"Source content or body stored on the record."},"result":{"nullable":true,"description":"The result associated with this record."},"role":{"type":"string","enum":["tool"],"description":"The role associated with this record."},"isError":{"type":"boolean","description":"The is error associated with this record."}},"required":["type","toolCallId"],"description":"Structured option 8 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["MESSAGES_SNAPSHOT"],"description":"The type associated with this record."},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Unique identifier for the record."},"role":{"type":"string","minLength":1,"description":"The role associated with this record."},"parts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1,"description":"The type associated with this record."}},"required":["type"],"description":"One part item associated with this record."},"description":"The parts associated with this record."},"content":{"nullable":true,"description":"Source content or body stored on the record."}},"description":"One message item associated with this record."},"description":"List of messages associated with this record."}},"required":["type","messages"],"description":"Structured option 9 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_SNAPSHOT"],"description":"The type associated with this record."},"snapshot":{"type":"object","additionalProperties":{"nullable":true,"description":"Additional structured values associated with this result."},"description":"Structured snapshot details associated with this record."}},"required":["type","snapshot"],"description":"Structured option 10 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_DELTA"],"description":"The type associated with this record."},"delta":{"anyOf":[{"type":"object","additionalProperties":{"nullable":true,"description":"Additional structured values associated with this result."},"description":"Structured option 1 details associated with this record."},{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace","move","copy","test"],"description":"The op associated with this record."},"path":{"type":"string","minLength":1,"description":"The path associated with this record."},"from":{"type":"string","minLength":1,"description":"The from associated with this record."},"value":{"nullable":true,"description":"The value associated with this record."}},"required":["op","path"],"description":"One option 2 item associated with this record."},"description":"List of option 2 associated with this record."}],"description":"The delta associated with this record."}},"required":["type","delta"],"description":"Structured option 11 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_STARTED","RUN_FINISHED","RUN_ERROR","STEP_STARTED","STEP_FINISHED","REASONING_START","REASONING_MESSAGE_START","REASONING_MESSAGE_CONTENT","REASONING_MESSAGE_END","REASONING_CONTENT","REASONING_END","ACTIVITY_SNAPSHOT","ACTIVITY_DELTA","CUSTOM"],"description":"The type associated with this record."}},"required":["type"],"description":"Structured option 12 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"status":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"toolCallName":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."}},"required":["type","toolCallId","status","toolCallName"],"description":"Structured option 13 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_CREATED"],"description":"The type associated with this record."},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["id"],"description":"Structured input request details associated with this record."}},"required":["type","inputRequest"],"description":"Structured option 14 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"],"description":"The type associated with this record."},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["id"],"description":"Structured input request details associated with this record."}},"required":["type","inputRequest"],"description":"Structured option 15 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"childRunId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"status":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"childConversationId":{"type":"string","nullable":true,"minLength":1,"description":"The child conversation id associated with this record."},"childMessageId":{"type":"string","nullable":true,"minLength":1,"description":"The child message id associated with this record."},"childAgentId":{"type":"string","nullable":true,"minLength":1,"description":"The child agent id associated with this record."},"description":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","toolCallId","childRunId","status"],"description":"Structured option 16 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_PARKED"],"description":"The type associated with this record."},"runId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"reason":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"lastEventId":{"type":"integer","minimum":0,"description":"The last event id associated with this record."}},"required":["type","runId","reason","lastEventId"],"description":"Structured option 17 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_LOG_CAPTURED"],"description":"The type associated with this record."},"logs":{"type":"string","description":"The logs associated with this record."}},"required":["type","logs"],"description":"Structured option 18 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"],"description":"The type associated with this record."},"runId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"lastEventId":{"type":"integer","minimum":0,"description":"The last event id associated with this record."}},"required":["type","runId","lastEventId"],"description":"Structured option 19 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["URL_CITED"],"description":"The type associated with this record."},"url":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"sourceId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"title":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","url","sourceId"],"description":"Structured option 20 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["DOCUMENT_CITED"],"description":"The type associated with this record."},"mediaType":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"sourceId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"title":{"type":"string","minLength":1,"description":"Human-readable description for the record."},"filename":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","mediaType","sourceId"],"description":"Structured option 21 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["FILE_ATTACHED"],"description":"The type associated with this record."},"mediaType":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"url":{"type":"string","minLength":1,"description":"Human-readable description for the record."},"filename":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","mediaType"],"description":"Structured option 22 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["FILES_CHANGED"],"description":"The type associated with this record."},"id":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."},"status":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."},"changes":{"nullable":true,"description":"The changes associated with this record."}},"required":["type","id","status","changes"],"description":"Structured option 23 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"],"description":"The type associated with this record."},"runtime":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"kind":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"value":{"nullable":true,"description":"The changes associated with this record."}},"required":["type","runtime","kind","value"],"description":"Structured option 24 details associated with this record."}],"description":"The event associated with this record."},{"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","minimum":0,"exclusiveMinimum":true},"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},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED","AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT"]},"requestHash":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["type","requestHash"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED","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},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED","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":{"nullable":true}}},"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},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED","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":{"nullable":true},"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":{"nullable":true}},"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":{"nullable":true}},"required":["type","name","inputSchema"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["provider"]},"name":{"type":"string"},"id":{"type":"string"},"args":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","name","id","args"],"additionalProperties":false}]}},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","messages"],"additionalProperties":false}]},"minItems":1,"maxItems":100}},"required":["events"]}}}},"responses":{"200":{"description":"Updated run cursor after appending events","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"requested_by_user_id":{"type":"string","format":"uuid"},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"agent_id":{"type":"string","minLength":1,"maxLength":128},"status":{"anyOf":[{"type":"string","enum":["completed","failed","cancelled"]},{"type":"string","enum":["pending","running","waiting_for_tool"]}]},"implementation_kind":{"type":"string","nullable":true,"minLength":1,"maxLength":64},"worker_key":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"parent_conversation_id":{"type":"string","nullable":true,"format":"uuid"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"spawned_from_message_id":{"type":"string","nullable":true,"format":"uuid"},"spawned_from_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"input_anchor_message_id":{"type":"string","nullable":true,"format":"uuid"},"handoff_message_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_deployment_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"waiting_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"waiting_tool_name":{"type":"string","nullable":true},"terminal_error_code":{"type":"string","nullable":true},"terminal_error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"finished_at":{"type":"string","nullable":true},"run_snapshot":{"type":"object","properties":{"project_agent":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["source"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","project_id","agent_id"]},{"type":"object","properties":{"kind":{"type":"string","enum":["installed"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128},"catalog_entry_id":{"type":"string","minLength":1},"agent_access_grant_id":{"type":"string","format":"uuid"},"service_account_id":{"type":"string","format":"uuid"}},"required":["kind","project_id","agent_id","catalog_entry_id","agent_access_grant_id","service_account_id"]},{"nullable":true}]},"source":{"type":"object","properties":{"type":{"type":"string","nullable":true,"enum":["project","catalog_entry"]},"path":{"type":"string","nullable":true},"hash":{"type":"string","nullable":true},"catalog_entry_id":{"type":"string","nullable":true}},"required":["type","path","hash","catalog_entry_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"environment_id":{"type":"string","nullable":true,"format":"uuid"},"branch_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_kind":{"type":"string","nullable":true},"deployment_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","environment_id","branch_id","resolved_target_id","resolved_target_kind","deployment_id"]},"requester":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"]}},"required":["project_agent","source","runtime_target","requester"]}},"required":["run_id","conversation_id","message_id","project_id","requested_by_user_id","agent_id","status","runtime_target_kind","latest_event_id","created_at","run_snapshot"]},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"appended_count":{"type":"integer","minimum":0}},"required":["run","latest_event_id","appended_count"]}}}},"401":{"description":"A run event writer token is required"}}}},"/runs/{run_id}/events/{event_id}":{"get":{"tags":["Runs"],"summary":"Get an authorized canonical run event detail","description":"Returns the requested event. Callers with editor access receive the full diagnostic payload; callers with only viewer access receive the sanitized public payload projection.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"event_id","in":"path"},{"schema":{"type":"string","enum":["raw","typed"],"default":"raw","description":"Provide the format."},"required":false,"description":"Provide the format.","name":"format","in":"query"}],"responses":{"200":{"description":"Run event detail","content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","minLength":1},"payload":{"nullable":true},"is_error":{"type":"boolean"},"created_at":{"type":"string"},"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","nullable":true,"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":"string","nullable":true,"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","nullable":true,"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","is_error","created_at"],"additionalProperties":false}}}},"404":{"description":"Run event not found"}}}},"/runs/{run_id}/resume":{"post":{"tags":["Runs"],"summary":"Submit a canonical resume signal to a waiting run","description":"Submits a resume signal to a waiting run and returns the emitted signal metadata.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"]},"tool_call_id":{"type":"string","minLength":1,"maxLength":128},"result":{"nullable":true},"is_error":{"type":"boolean","default":false}},"required":["type","tool_call_id","result"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["integration_connected"]},"integration":{"type":"string","minLength":1,"maxLength":128}},"required":["type","integration"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Resume signal accepted","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"}},"required":["accepted"]}}}}}}},"/runs/{run_id}/cancel":{"post":{"tags":["Runs"],"summary":"Cancel a canonical durable run","description":"Cancels a canonical durable run for callers with editor access to the run owner scope.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"responses":{"200":{"description":"Run cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"cancelled":{"type":"boolean"},"run":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"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},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"usage":{"type":"object","nullable":true,"properties":{"requests":{"type":"integer","minimum":0},"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"cache_creation_input_tokens":{"type":"integer","minimum":0},"cache_read_input_tokens":{"type":"integer","minimum":0},"reasoning_tokens":{"type":"integer","minimum":0},"cost_credits":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]}},"required":["requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","reasoning_tokens","cost_credits"]},"tool_error_count":{"type":"integer","minimum":0},"children_failed":{"type":"boolean"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"root_run_id":{"type":"string","minLength":1},"waiting_reason":{"type":"string","nullable":true,"enum":["tool","approval","event","input"]},"metadata":{"nullable":true},"target":{"type":"string","nullable":true},"workflow_id":{"type":"string","nullable":true},"schedule_id":{"type":"string","nullable":true,"format":"uuid"},"batch_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"nullable":true},"config":{"nullable":true},"output":{"nullable":true},"error":{"type":"object","nullable":true,"properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]},"logs":{"type":"string","nullable":true},"artifacts":{"type":"array","items":{"nullable":true}},"duration_ms":{"type":"integer","nullable":true},"exit_code":{"type":"integer","nullable":true},"start_mode":{"type":"string","nullable":true},"timeout_seconds":{"type":"integer","nullable":true},"backoff_limit":{"type":"integer","nullable":true},"trigger_kind":{"type":"string","nullable":true,"enum":["manual","schedule","webhook","api"]},"trigger_id":{"type":"string","nullable":true},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"updated_at":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"required":["run_id","kind","status","owner","conversation_id","message_id","usage","tool_error_count","children_failed","parent_run_id","root_run_id","waiting_reason","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","trigger_kind","trigger_id","created_by","updated_at","created_at","started_at","completed_at"]}},"required":["cancelled","run"]}}}}}}},"/runs/{run_id}/complete":{"post":{"tags":["Runs"],"summary":"Complete a canonical run","description":"Marks a canonical durable run complete with the provided completion payload.","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","nullable":true,"properties":{"provider":{"type":"string"},"model":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"cacheCreationInputTokens":{"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","nullable":true},"terminal_error_message":{"type":"string","nullable":true}},"required":["status"],"additionalProperties":false}}}},"responses":{"200":{"description":"Run completed","content":{"application/json":{"schema":{"type":"object","properties":{"completed":{"type":"boolean"},"run":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"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},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"usage":{"type":"object","nullable":true,"properties":{"requests":{"type":"integer","minimum":0},"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"cache_creation_input_tokens":{"type":"integer","minimum":0},"cache_read_input_tokens":{"type":"integer","minimum":0},"reasoning_tokens":{"type":"integer","minimum":0},"cost_credits":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]}},"required":["requests","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","reasoning_tokens","cost_credits"]},"tool_error_count":{"type":"integer","minimum":0},"children_failed":{"type":"boolean"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"root_run_id":{"type":"string","minLength":1},"waiting_reason":{"type":"string","nullable":true,"enum":["tool","approval","event","input"]},"metadata":{"nullable":true},"target":{"type":"string","nullable":true},"workflow_id":{"type":"string","nullable":true},"schedule_id":{"type":"string","nullable":true,"format":"uuid"},"batch_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"input":{"nullable":true},"config":{"nullable":true},"output":{"nullable":true},"error":{"type":"object","nullable":true,"properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]},"logs":{"type":"string","nullable":true},"artifacts":{"type":"array","items":{"nullable":true}},"duration_ms":{"type":"integer","nullable":true},"exit_code":{"type":"integer","nullable":true},"start_mode":{"type":"string","nullable":true},"timeout_seconds":{"type":"integer","nullable":true},"backoff_limit":{"type":"integer","nullable":true},"trigger_kind":{"type":"string","nullable":true,"enum":["manual","schedule","webhook","api"]},"trigger_id":{"type":"string","nullable":true},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"updated_at":{"type":"string"},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true}},"required":["run_id","kind","status","owner","conversation_id","message_id","usage","tool_error_count","children_failed","parent_run_id","root_run_id","waiting_reason","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","trigger_kind","trigger_id","created_by","updated_at","created_at","started_at","completed_at"]}},"required":["completed","run"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Run not found"},"410":{"description":"Run already terminal"}}}},"/runs/{run_id}/detached-complete":{"post":{"tags":["Runs"],"security":[{"runEventWriterAuth":[]}],"summary":"Terminally complete a detached agent run generation","description":"Settles or observes the current detached generation using an explicitly scoped runtime completion credential. Valid authenticated outcomes are terminal, deferred, or lost.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["completed","failed","cancelled"]},"metadata":{"type":"object","nullable":true,"properties":{"provider":{"type":"string"},"model":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"totalTokens":{"type":"number"},"cachedInputTokens":{"type":"number"},"cacheCreationInputTokens":{"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","nullable":true,"minLength":1,"maxLength":128},"terminal_error_message":{"type":"string","nullable":true,"minLength":1,"maxLength":2000},"terminal_event_code":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"terminal_event_message":{"type":"string","nullable":true,"minLength":1,"maxLength":2000}},"required":["status"],"additionalProperties":false}}}},"responses":{"200":{"description":"Detached completion terminal, deferred, or lost outcome","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["terminal"]},"run":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"requested_by_user_id":{"type":"string","format":"uuid"},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"agent_id":{"type":"string","minLength":1,"maxLength":128},"status":{"anyOf":[{"type":"string","enum":["completed","failed","cancelled"]},{"type":"string","enum":["pending","running","waiting_for_tool"]}]},"implementation_kind":{"type":"string","nullable":true,"minLength":1,"maxLength":64},"worker_key":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"parent_conversation_id":{"type":"string","nullable":true,"format":"uuid"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"spawned_from_message_id":{"type":"string","nullable":true,"format":"uuid"},"spawned_from_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"input_anchor_message_id":{"type":"string","nullable":true,"format":"uuid"},"handoff_message_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_deployment_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"waiting_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"waiting_tool_name":{"type":"string","nullable":true},"terminal_error_code":{"type":"string","nullable":true},"terminal_error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"finished_at":{"type":"string","nullable":true},"run_snapshot":{"type":"object","properties":{"project_agent":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["source"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","project_id","agent_id"]},{"type":"object","properties":{"kind":{"type":"string","enum":["installed"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128},"catalog_entry_id":{"type":"string","minLength":1},"agent_access_grant_id":{"type":"string","format":"uuid"},"service_account_id":{"type":"string","format":"uuid"}},"required":["kind","project_id","agent_id","catalog_entry_id","agent_access_grant_id","service_account_id"]},{"nullable":true}]},"source":{"type":"object","properties":{"type":{"type":"string","nullable":true,"enum":["project","catalog_entry"]},"path":{"type":"string","nullable":true},"hash":{"type":"string","nullable":true},"catalog_entry_id":{"type":"string","nullable":true}},"required":["type","path","hash","catalog_entry_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"environment_id":{"type":"string","nullable":true,"format":"uuid"},"branch_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_kind":{"type":"string","nullable":true},"deployment_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","environment_id","branch_id","resolved_target_id","resolved_target_kind","deployment_id"]},"requester":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"]}},"required":["project_agent","source","runtime_target","requester"]}},"required":["run_id","conversation_id","message_id","project_id","requested_by_user_id","agent_id","status","runtime_target_kind","latest_event_id","created_at","run_snapshot"]}},"required":["status","run"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["deferred"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["lost"]}},"required":["status"],"additionalProperties":false}]}}}},"400":{"description":"Invalid completion payload or receipt history"},"401":{"description":"An explicitly scoped detached completion credential is required"}}}},"/runs/{run_id}/detached-lease":{"post":{"tags":["Runs"],"security":[{"runEventWriterAuth":[]}],"summary":"Renew a detached agent run lease","description":"Extends the current detached generation lease using an explicitly scoped runtime credential. Superseded or expired generations cannot renew.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lease_duration_seconds":{"type":"integer","minimum":5,"maximum":300},"accept_dispatch":{"type":"boolean"}},"required":["lease_duration_seconds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Lease renewed, cancelled, or lost","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["renewed"]},"lease_expires_at":{"type":"string","format":"date-time"}},"required":["status","lease_expires_at"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["cancelled"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["lost"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["already_accepted"]}},"required":["status"],"additionalProperties":false}]}}}},"400":{"description":"Invalid lease duration or receipt history"},"401":{"description":"An explicitly scoped detached renewal credential is required"}}}},"/runs/{run_id}/stream":{"get":{"tags":["Runs"],"summary":"Attach to a durable agent run event stream by run ID","description":"Streams the sanitized public projection of an agent run event log, including conversationless runs. Resume strictly after a durable event with Last-Event-ID. Private diagnostic payloads remain available only from GET /runs/{run_id}/events. Pass format=typed for typed frames whose data is the same row shape as GET /runs/{run_id}/events?format=typed; the id cursor is unchanged.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"string","enum":["raw","typed"],"default":"raw","description":"Provide the format."},"required":false,"description":"Provide the format.","name":"format","in":"query"},{"schema":{"type":"string","description":"Resume strictly after this durable event ID."},"required":false,"name":"Last-Event-ID","in":"header"}],"responses":{"200":{"description":"Agent event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"404":{"description":"Agent run not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/runs/{run_id}/input-requests":{"get":{"tags":["Runs"],"summary":"List durable input requests for a run","description":"Lists durable input requests after verifying viewer access to the run owner scope.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"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"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Input requests","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"tool_call_id":{"type":"string"},"kind":{"type":"string","enum":["form"]},"status":{"type":"string","enum":["open","submitted","cancelled","expired"]},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"fields":{"type":"array","items":{"type":"object","properties":{}}},"recommendations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"expired_at":{"type":"string","nullable":true},"latest_response":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]}},"required":["id","conversation_id","run_id","tool_call_id","kind","status","requested_responder_type","title","description","fields","recommendations","metadata","created_at","expires_at","submitted_at","cancelled_at","expired_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}}},"/runs/{run_id}/input-requests/{input_request_id}":{"get":{"tags":["Runs"],"summary":"Read a durable input request for a run","description":"Returns one durable input request after verifying viewer access to the run owner scope.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"input_request_id","in":"path"}],"responses":{"200":{"description":"Input request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"tool_call_id":{"type":"string"},"kind":{"type":"string","enum":["form"]},"status":{"type":"string","enum":["open","submitted","cancelled","expired"]},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"fields":{"type":"array","items":{"type":"object","properties":{}}},"recommendations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"expired_at":{"type":"string","nullable":true},"latest_response":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]}},"required":["id","conversation_id","run_id","tool_call_id","kind","status","requested_responder_type","title","description","fields","recommendations","metadata","created_at","expires_at","submitted_at","cancelled_at","expired_at"]}}}},"404":{"description":"Input request not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/runs/{run_id}/input-requests/{input_request_id}/responses":{"post":{"tags":["Runs"],"summary":"Submit a durable input response for a run","description":"Submits a human response after verifying editor access to the run owner scope.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"input_request_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."}},"required":["values"]}}}},"responses":{"200":{"description":"Input response accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"input_request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"tool_call_id":{"type":"string"},"kind":{"type":"string","enum":["form"]},"status":{"type":"string","enum":["open","submitted","cancelled","expired"]},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"fields":{"type":"array","items":{"type":"object","properties":{}}},"recommendations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"expired_at":{"type":"string","nullable":true},"latest_response":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]}},"required":["id","conversation_id","run_id","tool_call_id","kind","status","requested_responder_type","title","description","fields","recommendations","metadata","created_at","expires_at","submitted_at","cancelled_at","expired_at"]},"input_response":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]},"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"}},"required":["success","input_request","input_response","accepted"]}}}},"404":{"description":"Input request not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"409":{"description":"Input request not open","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/participants":{"get":{"tags":["Conversations"],"summary":"List participant identities","description":"Lists canonical conversation participant identities by user or agent id.","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","nullable":true,"format":"uuid"},"agent_id":{"type":"string","nullable":true},"project_id":{"type":"string","nullable":true,"format":"uuid"},"display_name":{"type":"string","nullable":true}},"required":["id","participant_type"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true},"first":{"type":"string","nullable":true},"next":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true}}}},"required":["data","page_info"]}}}}}}},"/conversations":{"post":{"tags":["Conversations"],"summary":"Create Conversation","description":"Creates 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},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"initial_message":{"type":"object","properties":{"composing_user_id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["user"]},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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},"idempotency_key":{"type":"string","maxLength":255},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["role","parts"],"additionalProperties":false}}}}}},"responses":{"201":{"description":"Created conversation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"project_id":{"type":"string","nullable":true},"responding_agent_id":{"type":"string","nullable":true,"default":null},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived","deleted"]},"current_node":{"type":"string","nullable":true},"message_count":{"type":"number"},"last_message_at":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_by":{"type":"string","nullable":true},"archived_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"participant_id":{"type":"string","nullable":true},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":"string","nullable":true},"agent_id":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"role":{"type":"string","enum":["owner","member","viewer"]}},"required":["id","role"]},"default":[]},"initial_message_id":{"type":"string","nullable":true,"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":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"get":{"tags":["Conversations"],"summary":"List Conversations","description":"Lists 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"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"participant_ids","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"agent_id","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"user_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"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"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"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","nullable":true},"responding_agent_id":{"type":"string","nullable":true,"default":null},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived","deleted"]},"current_node":{"type":"string","nullable":true},"message_count":{"type":"number"},"last_message_at":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_by":{"type":"string","nullable":true},"archived_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"participant_id":{"type":"string","nullable":true},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":"string","nullable":true},"agent_id":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{id}":{"get":{"tags":["Conversations"],"summary":"Get Conversation","description":"Returns a conversation by ID.","parameters":[{"schema":{"type":"string","format":"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","nullable":true},"responding_agent_id":{"type":"string","nullable":true,"default":null},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived","deleted"]},"current_node":{"type":"string","nullable":true},"message_count":{"type":"number"},"last_message_at":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_by":{"type":"string","nullable":true},"archived_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"participant_id":{"type":"string","nullable":true},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":"string","nullable":true},"agent_id":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"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":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"patch":{"tags":["Conversations"],"summary":"Update Conversation","description":"Updates a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":500},"status":{"type":"string","enum":["active","archived"]},"summary":{"type":"string","maxLength":5000},"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","nullable":true},"responding_agent_id":{"type":"string","nullable":true,"default":null},"type":{"type":"string","enum":["chat","default_chat","plan","research","agent_task","support","channel","project_agent"]},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived","deleted"]},"current_node":{"type":"string","nullable":true},"message_count":{"type":"number"},"last_message_at":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_by":{"type":"string","nullable":true},"archived_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"participant_id":{"type":"string","nullable":true},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":"string","nullable":true},"agent_id":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"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":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"delete":{"tags":["Conversations"],"summary":"Delete Conversation","description":"Soft-deletes a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Conversation deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{id}/messages":{"get":{"tags":["Conversations"],"summary":"List Messages","description":"Lists messages in a conversation.","parameters":[{"schema":{"type":"string","format":"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":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"seq":{"type":"number"},"role":{"type":"string","enum":["user","assistant","tool"]},"created_by":{"type":"string","nullable":true},"sender_type":{"type":"string","enum":["user","webhook","service_account","integration","agent","system"],"default":"user"},"sender_id":{"type":"string","nullable":true},"sender_display_name":{"type":"string","nullable":true},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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","nullable":true},"token_usage":{"type":"object","nullable":true,"properties":{"input":{"type":"number"},"output":{"type":"number"},"reasoning_tokens":{"type":"integer","minimum":0}}},"finish_reason":{"type":"string","nullable":true},"cost_credits":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","streaming","completed","failed","cancelled"]},"edited_at":{"type":"string","nullable":true},"idempotency_key":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}},"required":["id","conversation_id","seq","role","parts","status","created_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"post":{"tags":["Conversations"],"summary":"Send Message","description":"Sends a user message in a conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"composing_user_id":{"type":"string","format":"uuid"},"parent_id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["user"]},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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},"idempotency_key":{"type":"string","maxLength":255},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["role","parts"]}}}},"responses":{"201":{"description":"Created message","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"seq":{"type":"number"},"role":{"type":"string","enum":["user","assistant","tool"]},"created_by":{"type":"string","nullable":true},"sender_type":{"type":"string","enum":["user","webhook","service_account","integration","agent","system"],"default":"user"},"sender_id":{"type":"string","nullable":true},"sender_display_name":{"type":"string","nullable":true},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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","nullable":true},"token_usage":{"type":"object","nullable":true,"properties":{"input":{"type":"number"},"output":{"type":"number"},"reasoning_tokens":{"type":"integer","minimum":0}}},"finish_reason":{"type":"string","nullable":true},"cost_credits":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","streaming","completed","failed","cancelled"]},"edited_at":{"type":"string","nullable":true},"idempotency_key":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}},"required":["id","conversation_id","seq","role","parts","status","created_at"]}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/messages/{message_id}":{"get":{"tags":["Conversations"],"summary":"Get Message","description":"Returns 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":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"seq":{"type":"number"},"role":{"type":"string","enum":["user","assistant","tool"]},"created_by":{"type":"string","nullable":true},"sender_type":{"type":"string","enum":["user","webhook","service_account","integration","agent","system"],"default":"user"},"sender_id":{"type":"string","nullable":true},"sender_display_name":{"type":"string","nullable":true},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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","nullable":true},"token_usage":{"type":"object","nullable":true,"properties":{"input":{"type":"number"},"output":{"type":"number"},"reasoning_tokens":{"type":"integer","minimum":0}}},"finish_reason":{"type":"string","nullable":true},"cost_credits":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","streaming","completed","failed","cancelled"]},"edited_at":{"type":"string","nullable":true},"idempotency_key":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}},"required":["id","conversation_id","seq","role","parts","status","created_at"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"patch":{"tags":["Conversations"],"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"seq":{"type":"number"},"role":{"type":"string","enum":["user","assistant","tool"]},"created_by":{"type":"string","nullable":true},"sender_type":{"type":"string","enum":["user","webhook","service_account","integration","agent","system"],"default":"user"},"sender_id":{"type":"string","nullable":true},"sender_display_name":{"type":"string","nullable":true},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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","nullable":true},"token_usage":{"type":"object","nullable":true,"properties":{"input":{"type":"number"},"output":{"type":"number"},"reasoning_tokens":{"type":"integer","minimum":0}}},"finish_reason":{"type":"string","nullable":true},"cost_credits":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","streaming","completed","failed","cancelled"]},"edited_at":{"type":"string","nullable":true},"idempotency_key":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}},"required":["id","conversation_id","seq","role","parts","status","created_at"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"delete":{"tags":["Conversations"],"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":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/branches/{message_id}":{"get":{"tags":["Conversations"],"summary":"List Message Branches","description":"Lists 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":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"seq":{"type":"number"},"role":{"type":"string","enum":["user","assistant","tool"]},"created_by":{"type":"string","nullable":true},"sender_type":{"type":"string","enum":["user","webhook","service_account","integration","agent","system"],"default":"user"},"sender_id":{"type":"string","nullable":true},"sender_display_name":{"type":"string","nullable":true},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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","nullable":true},"token_usage":{"type":"object","nullable":true,"properties":{"input":{"type":"number"},"output":{"type":"number"},"reasoning_tokens":{"type":"integer","minimum":0}}},"finish_reason":{"type":"string","nullable":true},"cost_credits":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","streaming","completed","failed","cancelled"]},"edited_at":{"type":"string","nullable":true},"idempotency_key":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}},"required":["id","conversation_id","seq","role","parts","status","created_at"]}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/branches":{"post":{"tags":["Conversations"],"summary":"Fork Message","description":"Creates 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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"seq":{"type":"number"},"role":{"type":"string","enum":["user","assistant","tool"]},"created_by":{"type":"string","nullable":true},"sender_type":{"type":"string","enum":["user","webhook","service_account","integration","agent","system"],"default":"user"},"sender_id":{"type":"string","nullable":true},"sender_display_name":{"type":"string","nullable":true},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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","nullable":true},"token_usage":{"type":"object","nullable":true,"properties":{"input":{"type":"number"},"output":{"type":"number"},"reasoning_tokens":{"type":"integer","minimum":0}}},"finish_reason":{"type":"string","nullable":true},"cost_credits":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","streaming","completed","failed","cancelled"]},"edited_at":{"type":"string","nullable":true},"idempotency_key":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}},"required":["id","conversation_id","seq","role","parts","status","created_at"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/branch-selection":{"get":{"tags":["Conversations"],"summary":"Get Branch Selection","description":"Returns 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","nullable":true,"format":"uuid"}},"required":["message_id"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"put":{"tags":["Conversations"],"summary":"Update Branch Selection","description":"Updates 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","nullable":true,"format":"uuid"}},"required":["message_id"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{id}/tree":{"get":{"tags":["Conversations"],"summary":"Get Conversation Tree","description":"Returns the conversation tree, including branches.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"All messages","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"seq":{"type":"number"},"role":{"type":"string","enum":["user","assistant","tool"]},"created_by":{"type":"string","nullable":true},"sender_type":{"type":"string","enum":["user","webhook","service_account","integration","agent","system"],"default":"user"},"sender_id":{"type":"string","nullable":true},"sender_display_name":{"type":"string","nullable":true},"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":{"nullable":true,"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":{"nullable":true,"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":{"nullable":true,"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","nullable":true},"token_usage":{"type":"object","nullable":true,"properties":{"input":{"type":"number"},"output":{"type":"number"},"reasoning_tokens":{"type":"integer","minimum":0}}},"finish_reason":{"type":"string","nullable":true},"cost_credits":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","streaming","completed","failed","cancelled"]},"edited_at":{"type":"string","nullable":true},"idempotency_key":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}},"required":["id","conversation_id","seq","role","parts","status","created_at"]}},"truncated":{"type":"boolean"}},"required":["items","truncated"]}}}}}}},"/conversations/{conversation_id}/participants":{"get":{"tags":["Conversations"],"summary":"List Participants","description":"Lists 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","nullable":true},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":"string","nullable":true},"agent_id":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"role":{"type":"string","enum":["owner","member","viewer"]},"last_read_message_id":{"type":"string","nullable":true},"notification_preference":{"type":"string"},"joined_at":{"type":"string"}},"required":["id","conversation_id","role","notification_preference","joined_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}},"post":{"tags":["Conversations"],"summary":"Add Participant","description":"Adds 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","nullable":true},"participant_type":{"type":"string","enum":["user","agent"],"default":"user"},"user_id":{"type":"string","nullable":true},"agent_id":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"role":{"type":"string","enum":["owner","member","viewer"]},"last_read_message_id":{"type":"string","nullable":true},"notification_preference":{"type":"string"},"joined_at":{"type":"string"}},"required":["id","conversation_id","role","notification_preference","joined_at"]}}}}}}},"/conversations/{conversation_id}/participants/{user_id}":{"delete":{"tags":["Conversations"],"summary":"Remove Participant","description":"Removes 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":{"tags":["Conversations"],"summary":"Get Read State","description":"Returns 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","nullable":true,"format":"uuid"},"unread_count":{"type":"integer","minimum":0}},"required":["last_read_message_id","unread_count"]}}}}}},"put":{"tags":["Conversations"],"summary":"Update Read State","description":"Updates the read cursor for the current user in 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 read state","content":{"application/json":{"schema":{"type":"object","properties":{"last_read_message_id":{"type":"string","nullable":true,"format":"uuid"},"unread_count":{"type":"integer","minimum":0}},"required":["last_read_message_id","unread_count"]}}}}}}},"/conversations/{conversation_id}/runs":{"get":{"tags":["Conversations"],"summary":"List durable agent runs for a conversation","description":"Lists durable public agent runs for the conversation with optional status filtering.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Agent runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"requested_by_user_id":{"type":"string","format":"uuid"},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"agent_id":{"type":"string","minLength":1,"maxLength":128},"status":{"anyOf":[{"type":"string","enum":["completed","failed","cancelled"]},{"type":"string","enum":["pending","running","waiting_for_tool"]}]},"implementation_kind":{"type":"string","nullable":true,"minLength":1,"maxLength":64},"worker_key":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"parent_conversation_id":{"type":"string","nullable":true,"format":"uuid"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"spawned_from_message_id":{"type":"string","nullable":true,"format":"uuid"},"spawned_from_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"input_anchor_message_id":{"type":"string","nullable":true,"format":"uuid"},"handoff_message_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_deployment_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"waiting_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"waiting_tool_name":{"type":"string","nullable":true},"terminal_error_code":{"type":"string","nullable":true},"terminal_error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"finished_at":{"type":"string","nullable":true},"run_snapshot":{"type":"object","properties":{"project_agent":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["source"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","project_id","agent_id"]},{"type":"object","properties":{"kind":{"type":"string","enum":["installed"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128},"catalog_entry_id":{"type":"string","minLength":1},"agent_access_grant_id":{"type":"string","format":"uuid"},"service_account_id":{"type":"string","format":"uuid"}},"required":["kind","project_id","agent_id","catalog_entry_id","agent_access_grant_id","service_account_id"]},{"nullable":true}]},"source":{"type":"object","properties":{"type":{"type":"string","nullable":true,"enum":["project","catalog_entry"]},"path":{"type":"string","nullable":true},"hash":{"type":"string","nullable":true},"catalog_entry_id":{"type":"string","nullable":true}},"required":["type","path","hash","catalog_entry_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"environment_id":{"type":"string","nullable":true,"format":"uuid"},"branch_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_kind":{"type":"string","nullable":true},"deployment_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","environment_id","branch_id","resolved_target_id","resolved_target_kind","deployment_id"]},"requester":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"]}},"required":["project_agent","source","runtime_target","requester"]}},"required":["run_id","conversation_id","message_id","project_id","requested_by_user_id","agent_id","status","runtime_target_kind","latest_event_id","created_at","run_snapshot"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}}},"/conversations/{conversation_id}/runs/children-by-parent-conversation":{"get":{"tags":["Conversations"],"summary":"List child runs by parent conversation lineage","description":"Lists child agent runs spawned from any parent run in the parent conversation lineage.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"spawned_from_tool_call_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Child runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"requested_by_user_id":{"type":"string","format":"uuid"},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"agent_id":{"type":"string","minLength":1,"maxLength":128},"status":{"anyOf":[{"type":"string","enum":["completed","failed","cancelled"]},{"type":"string","enum":["pending","running","waiting_for_tool"]}]},"implementation_kind":{"type":"string","nullable":true,"minLength":1,"maxLength":64},"worker_key":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"parent_conversation_id":{"type":"string","nullable":true,"format":"uuid"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"spawned_from_message_id":{"type":"string","nullable":true,"format":"uuid"},"spawned_from_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"input_anchor_message_id":{"type":"string","nullable":true,"format":"uuid"},"handoff_message_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_deployment_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"waiting_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"waiting_tool_name":{"type":"string","nullable":true},"terminal_error_code":{"type":"string","nullable":true},"terminal_error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"finished_at":{"type":"string","nullable":true},"run_snapshot":{"type":"object","properties":{"project_agent":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["source"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","project_id","agent_id"]},{"type":"object","properties":{"kind":{"type":"string","enum":["installed"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128},"catalog_entry_id":{"type":"string","minLength":1},"agent_access_grant_id":{"type":"string","format":"uuid"},"service_account_id":{"type":"string","format":"uuid"}},"required":["kind","project_id","agent_id","catalog_entry_id","agent_access_grant_id","service_account_id"]},{"nullable":true}]},"source":{"type":"object","properties":{"type":{"type":"string","nullable":true,"enum":["project","catalog_entry"]},"path":{"type":"string","nullable":true},"hash":{"type":"string","nullable":true},"catalog_entry_id":{"type":"string","nullable":true}},"required":["type","path","hash","catalog_entry_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"environment_id":{"type":"string","nullable":true,"format":"uuid"},"branch_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_kind":{"type":"string","nullable":true},"deployment_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","environment_id","branch_id","resolved_target_id","resolved_target_kind","deployment_id"]},"requester":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"]}},"required":["project_agent","source","runtime_target","requester"]}},"required":["run_id","conversation_id","message_id","project_id","requested_by_user_id","agent_id","status","runtime_target_kind","latest_event_id","created_at","run_snapshot"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}}},"/conversations/{conversation_id}/runs/{run_id}/events":{"get":{"tags":["Conversations"],"summary":"Get the durable mixed run-event log for an agent run","description":"Returns sanitized AG-UI and Veryfront control-plane events for an agent run, optionally after the requested durable cursor. Pass format=typed for the typed contract with the span envelope; cursors are identical in both formats.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"after_event_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["raw","typed"],"default":"raw","description":"Provide the format."},"required":false,"description":"Provide the format.","name":"format","in":"query"}],"responses":{"200":{"description":"Agent run event log","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"event_id":{"type":"integer","minimum":0},"event_type":{"type":"string","minLength":1},"event":{"nullable":true},"created_at":{"type":"string","nullable":true},"is_error":{"type":"boolean"},"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","nullable":true,"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":"string","nullable":true,"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","nullable":true,"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"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"post":{"tags":["Conversations"],"summary":"Append non-terminal events to a durable agent run","description":"Appends externally produced AG-UI events to an active durable run and returns the updated cursor state.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expected_previous_event_id":{"type":"integer","nullable":true,"minimum":0},"expected_previous_external_event_sequence":{"type":"integer","nullable":true,"minimum":0},"external_sequence_scope":{"type":"string","enum":["agent","publish_only"]},"events":{"type":"array","items":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_START"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."},"role":{"type":"string","description":"The role associated with this record."}},"required":["type","messageId","contentId"],"description":"Structured option 1 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","messageId","contentId","delta"],"description":"Structured option 2 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_END"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."}},"required":["type","messageId","contentId"],"description":"Structured option 3 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_START"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"toolCallName":{"type":"string","minLength":1,"description":"The tool call name associated with this record."}},"required":["type","toolCallId","toolCallName"],"description":"Structured option 4 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_ARGS"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","toolCallId","delta"],"description":"Structured option 5 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_CHUNK"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","toolCallId","delta"],"description":"Structured option 6 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_END"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["type","toolCallId"],"description":"Structured option 7 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_RESULT"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"parentMessageId":{"type":"string","minLength":1,"description":"The parent message id associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"input":{"nullable":true,"description":"The input associated with this record."},"content":{"nullable":true,"description":"Source content or body stored on the record."},"result":{"nullable":true,"description":"The result associated with this record."},"role":{"type":"string","enum":["tool"],"description":"The role associated with this record."},"isError":{"type":"boolean","description":"The is error associated with this record."}},"required":["type","toolCallId"],"description":"Structured option 8 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["MESSAGES_SNAPSHOT"],"description":"The type associated with this record."},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Unique identifier for the record."},"role":{"type":"string","minLength":1,"description":"The role associated with this record."},"parts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1,"description":"The type associated with this record."}},"required":["type"],"description":"One part item associated with this record."},"description":"The parts associated with this record."},"content":{"nullable":true,"description":"Source content or body stored on the record."}},"description":"One message item associated with this record."},"description":"List of messages associated with this record."}},"required":["type","messages"],"description":"Structured option 9 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_SNAPSHOT"],"description":"The type associated with this record."},"snapshot":{"type":"object","additionalProperties":{"nullable":true,"description":"Additional structured values associated with this result."},"description":"Structured snapshot details associated with this record."}},"required":["type","snapshot"],"description":"Structured option 10 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_DELTA"],"description":"The type associated with this record."},"delta":{"anyOf":[{"type":"object","additionalProperties":{"nullable":true,"description":"Additional structured values associated with this result."},"description":"Structured option 1 details associated with this record."},{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace","move","copy","test"],"description":"The op associated with this record."},"path":{"type":"string","minLength":1,"description":"The path associated with this record."},"from":{"type":"string","minLength":1,"description":"The from associated with this record."},"value":{"nullable":true,"description":"The value associated with this record."}},"required":["op","path"],"description":"One option 2 item associated with this record."},"description":"List of option 2 associated with this record."}],"description":"The delta associated with this record."}},"required":["type","delta"],"description":"Structured option 11 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_STARTED","RUN_FINISHED","RUN_ERROR","STEP_STARTED","STEP_FINISHED","REASONING_START","REASONING_MESSAGE_START","REASONING_MESSAGE_CONTENT","REASONING_MESSAGE_END","REASONING_CONTENT","REASONING_END","ACTIVITY_SNAPSHOT","ACTIVITY_DELTA","CUSTOM"],"description":"The type associated with this record."}},"required":["type"],"description":"Structured option 12 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"status":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"toolCallName":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."}},"required":["type","toolCallId","status","toolCallName"],"description":"Structured option 13 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_CREATED"],"description":"The type associated with this record."},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["id"],"description":"Structured input request details associated with this record."}},"required":["type","inputRequest"],"description":"Structured option 14 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"],"description":"The type associated with this record."},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["id"],"description":"Structured input request details associated with this record."}},"required":["type","inputRequest"],"description":"Structured option 15 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"childRunId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"status":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"childConversationId":{"type":"string","nullable":true,"minLength":1,"description":"The child conversation id associated with this record."},"childMessageId":{"type":"string","nullable":true,"minLength":1,"description":"The child message id associated with this record."},"childAgentId":{"type":"string","nullable":true,"minLength":1,"description":"The child agent id associated with this record."},"description":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","toolCallId","childRunId","status"],"description":"Structured option 16 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_PARKED"],"description":"The type associated with this record."},"runId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"reason":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"lastEventId":{"type":"integer","minimum":0,"description":"The last event id associated with this record."}},"required":["type","runId","reason","lastEventId"],"description":"Structured option 17 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_LOG_CAPTURED"],"description":"The type associated with this record."},"logs":{"type":"string","description":"The logs associated with this record."}},"required":["type","logs"],"description":"Structured option 18 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"],"description":"The type associated with this record."},"runId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"lastEventId":{"type":"integer","minimum":0,"description":"The last event id associated with this record."}},"required":["type","runId","lastEventId"],"description":"Structured option 19 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["URL_CITED"],"description":"The type associated with this record."},"url":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"sourceId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"title":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","url","sourceId"],"description":"Structured option 20 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["DOCUMENT_CITED"],"description":"The type associated with this record."},"mediaType":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"sourceId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"title":{"type":"string","minLength":1,"description":"Human-readable description for the record."},"filename":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","mediaType","sourceId"],"description":"Structured option 21 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["FILE_ATTACHED"],"description":"The type associated with this record."},"mediaType":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"url":{"type":"string","minLength":1,"description":"Human-readable description for the record."},"filename":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","mediaType"],"description":"Structured option 22 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["FILES_CHANGED"],"description":"The type associated with this record."},"id":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."},"status":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."},"changes":{"nullable":true,"description":"The changes associated with this record."}},"required":["type","id","status","changes"],"description":"Structured option 23 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"],"description":"The type associated with this record."},"runtime":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"kind":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"value":{"nullable":true,"description":"The changes associated with this record."}},"required":["type","runtime","kind","value"],"description":"Structured option 24 details associated with this record."}],"description":"The event associated with this record."},{"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","minimum":0,"exclusiveMinimum":true},"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},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED","AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT"]},"requestHash":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["type","requestHash"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED","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},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED","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":{"nullable":true}}},"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},{"type":"object","properties":{"type":{"type":"string","enum":["AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED","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":{"nullable":true},"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":{"nullable":true}},"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":{"nullable":true}},"required":["type","name","inputSchema"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["provider"]},"name":{"type":"string"},"id":{"type":"string"},"args":{"type":"object","additionalProperties":{"nullable":true}}},"required":["type","name","id","args"],"additionalProperties":false}]}},"elapsedMs":{"type":"number","minimum":0},"emittedAt":{"type":"integer","minimum":0}},"required":["type","messages"],"additionalProperties":false}]},"minItems":1,"maxItems":100}},"required":["events"]}}}},"responses":{"200":{"description":"Updated run cursor after appending events","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"requested_by_user_id":{"type":"string","format":"uuid"},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"agent_id":{"type":"string","minLength":1,"maxLength":128},"status":{"anyOf":[{"type":"string","enum":["completed","failed","cancelled"]},{"type":"string","enum":["pending","running","waiting_for_tool"]}]},"implementation_kind":{"type":"string","nullable":true,"minLength":1,"maxLength":64},"worker_key":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"parent_conversation_id":{"type":"string","nullable":true,"format":"uuid"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"spawned_from_message_id":{"type":"string","nullable":true,"format":"uuid"},"spawned_from_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"input_anchor_message_id":{"type":"string","nullable":true,"format":"uuid"},"handoff_message_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_deployment_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"waiting_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"waiting_tool_name":{"type":"string","nullable":true},"terminal_error_code":{"type":"string","nullable":true},"terminal_error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"finished_at":{"type":"string","nullable":true},"run_snapshot":{"type":"object","properties":{"project_agent":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["source"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","project_id","agent_id"]},{"type":"object","properties":{"kind":{"type":"string","enum":["installed"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128},"catalog_entry_id":{"type":"string","minLength":1},"agent_access_grant_id":{"type":"string","format":"uuid"},"service_account_id":{"type":"string","format":"uuid"}},"required":["kind","project_id","agent_id","catalog_entry_id","agent_access_grant_id","service_account_id"]},{"nullable":true}]},"source":{"type":"object","properties":{"type":{"type":"string","nullable":true,"enum":["project","catalog_entry"]},"path":{"type":"string","nullable":true},"hash":{"type":"string","nullable":true},"catalog_entry_id":{"type":"string","nullable":true}},"required":["type","path","hash","catalog_entry_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"environment_id":{"type":"string","nullable":true,"format":"uuid"},"branch_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_kind":{"type":"string","nullable":true},"deployment_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","environment_id","branch_id","resolved_target_id","resolved_target_kind","deployment_id"]},"requester":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"]}},"required":["project_agent","source","runtime_target","requester"]}},"required":["run_id","conversation_id","message_id","project_id","requested_by_user_id","agent_id","status","runtime_target_kind","latest_event_id","created_at","run_snapshot"]},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"appended_count":{"type":"integer","minimum":0}},"required":["run","latest_event_id","appended_count"]}}}}}}},"/conversations/{conversation_id}/runs/{run_id}":{"get":{"tags":["Conversations"],"summary":"Get a project-agent run","description":"Returns the durable public metadata for a single project-agent run in the conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"}],"responses":{"200":{"description":"Agent run","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"requested_by_user_id":{"type":"string","format":"uuid"},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"agent_id":{"type":"string","minLength":1,"maxLength":128},"status":{"anyOf":[{"type":"string","enum":["completed","failed","cancelled"]},{"type":"string","enum":["pending","running","waiting_for_tool"]}]},"implementation_kind":{"type":"string","nullable":true,"minLength":1,"maxLength":64},"worker_key":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"parent_conversation_id":{"type":"string","nullable":true,"format":"uuid"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"spawned_from_message_id":{"type":"string","nullable":true,"format":"uuid"},"spawned_from_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"input_anchor_message_id":{"type":"string","nullable":true,"format":"uuid"},"handoff_message_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_deployment_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"waiting_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"waiting_tool_name":{"type":"string","nullable":true},"terminal_error_code":{"type":"string","nullable":true},"terminal_error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"finished_at":{"type":"string","nullable":true},"run_snapshot":{"type":"object","properties":{"project_agent":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["source"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","project_id","agent_id"]},{"type":"object","properties":{"kind":{"type":"string","enum":["installed"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128},"catalog_entry_id":{"type":"string","minLength":1},"agent_access_grant_id":{"type":"string","format":"uuid"},"service_account_id":{"type":"string","format":"uuid"}},"required":["kind","project_id","agent_id","catalog_entry_id","agent_access_grant_id","service_account_id"]},{"nullable":true}]},"source":{"type":"object","properties":{"type":{"type":"string","nullable":true,"enum":["project","catalog_entry"]},"path":{"type":"string","nullable":true},"hash":{"type":"string","nullable":true},"catalog_entry_id":{"type":"string","nullable":true}},"required":["type","path","hash","catalog_entry_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"environment_id":{"type":"string","nullable":true,"format":"uuid"},"branch_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_kind":{"type":"string","nullable":true},"deployment_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","environment_id","branch_id","resolved_target_id","resolved_target_kind","deployment_id"]},"requester":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"]}},"required":["project_agent","source","runtime_target","requester"]}},"required":["run_id","conversation_id","message_id","project_id","requested_by_user_id","agent_id","status","runtime_target_kind","latest_event_id","created_at","run_snapshot"]}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/runs/{run_id}/snapshot":{"get":{"tags":["Conversations"],"summary":"Get the durable public stream snapshot for an agent run","description":"Returns the current replay snapshot for a durable agent run event stream. Pass format=typed to project every snapshot event through the typed contract, the same row shape GET .../events?format=typed returns; which events the snapshot selects is unchanged.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"string","enum":["raw","typed"],"default":"raw","description":"Provide the format."},"required":false,"description":"Provide the format.","name":"format","in":"query"}],"responses":{"200":{"description":"Agent run public stream snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"after_event_id":{"type":"integer","minimum":0},"events":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"event_id":{"type":"integer","nullable":true,"minimum":0},"event_type":{"type":"string","minLength":1},"event":{"nullable":true},"created_at":{"type":"string","nullable":true},"is_error":{"type":"boolean"},"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","nullable":true,"minLength":1,"description":"The parent span id associated with this record."},"turn_id":{"type":"string","nullable":true,"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","nullable":true,"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"]},{"type":"object","properties":{"event_id":{"type":"integer","nullable":true,"minimum":0},"event":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_START"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."},"role":{"type":"string","description":"The role associated with this record."}},"required":["type","messageId","contentId"],"description":"Structured option 1 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_CONTENT"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","messageId","contentId","delta"],"description":"Structured option 2 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TEXT_MESSAGE_END"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"contentId":{"type":"string","minLength":1,"description":"The content id associated with this record."}},"required":["type","messageId","contentId"],"description":"Structured option 3 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_START"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"toolCallName":{"type":"string","minLength":1,"description":"The tool call name associated with this record."}},"required":["type","toolCallId","toolCallName"],"description":"Structured option 4 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_ARGS"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","toolCallId","delta"],"description":"Structured option 5 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_CHUNK"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"delta":{"type":"string","description":"The delta associated with this record."}},"required":["type","toolCallId","delta"],"description":"Structured option 6 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_END"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["type","toolCallId"],"description":"Structured option 7 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_RESULT"],"description":"The type associated with this record."},"messageId":{"type":"string","minLength":1,"description":"The message id associated with this record."},"parentMessageId":{"type":"string","minLength":1,"description":"The parent message id associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"input":{"nullable":true,"description":"The input associated with this record."},"content":{"nullable":true,"description":"Source content or body stored on the record."},"result":{"nullable":true,"description":"The result associated with this record."},"role":{"type":"string","enum":["tool"],"description":"The role associated with this record."},"isError":{"type":"boolean","description":"The is error associated with this record."}},"required":["type","toolCallId"],"description":"Structured option 8 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["MESSAGES_SNAPSHOT"],"description":"The type associated with this record."},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Unique identifier for the record."},"role":{"type":"string","minLength":1,"description":"The role associated with this record."},"parts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1,"description":"The type associated with this record."}},"required":["type"],"description":"One part item associated with this record."},"description":"The parts associated with this record."},"content":{"nullable":true,"description":"Source content or body stored on the record."}},"description":"One message item associated with this record."},"description":"List of messages associated with this record."}},"required":["type","messages"],"description":"Structured option 9 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_SNAPSHOT"],"description":"The type associated with this record."},"snapshot":{"type":"object","additionalProperties":{"nullable":true,"description":"Additional structured values associated with this result."},"description":"Structured snapshot details associated with this record."}},"required":["type","snapshot"],"description":"Structured option 10 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STATE_DELTA"],"description":"The type associated with this record."},"delta":{"anyOf":[{"type":"object","additionalProperties":{"nullable":true,"description":"Additional structured values associated with this result."},"description":"Structured option 1 details associated with this record."},{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace","move","copy","test"],"description":"The op associated with this record."},"path":{"type":"string","minLength":1,"description":"The path associated with this record."},"from":{"type":"string","minLength":1,"description":"The from associated with this record."},"value":{"nullable":true,"description":"The value associated with this record."}},"required":["op","path"],"description":"One option 2 item associated with this record."},"description":"List of option 2 associated with this record."}],"description":"The delta associated with this record."}},"required":["type","delta"],"description":"Structured option 11 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_STARTED","RUN_FINISHED","RUN_ERROR","STEP_STARTED","STEP_FINISHED","REASONING_START","REASONING_MESSAGE_START","REASONING_MESSAGE_CONTENT","REASONING_MESSAGE_END","REASONING_CONTENT","REASONING_END","ACTIVITY_SNAPSHOT","ACTIVITY_DELTA","CUSTOM"],"description":"The type associated with this record."}},"required":["type"],"description":"Structured option 12 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["TOOL_CALL_STATUS_CHANGED"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"status":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"toolCallName":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."}},"required":["type","toolCallId","status","toolCallName"],"description":"Structured option 13 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_CREATED"],"description":"The type associated with this record."},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["id"],"description":"Structured input request details associated with this record."}},"required":["type","inputRequest"],"description":"Structured option 14 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["INPUT_REQUEST_UPDATED"],"description":"The type associated with this record."},"inputRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The tool call id associated with this record."}},"required":["id"],"description":"Structured input request details associated with this record."}},"required":["type","inputRequest"],"description":"Structured option 15 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["CHILD_RUN_STATUS_CHANGED"],"description":"The type associated with this record."},"toolCallId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"childRunId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"status":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"childConversationId":{"type":"string","nullable":true,"minLength":1,"description":"The child conversation id associated with this record."},"childMessageId":{"type":"string","nullable":true,"minLength":1,"description":"The child message id associated with this record."},"childAgentId":{"type":"string","nullable":true,"minLength":1,"description":"The child agent id associated with this record."},"description":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","toolCallId","childRunId","status"],"description":"Structured option 16 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_PARKED"],"description":"The type associated with this record."},"runId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"reason":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"lastEventId":{"type":"integer","minimum":0,"description":"The last event id associated with this record."}},"required":["type","runId","reason","lastEventId"],"description":"Structured option 17 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUN_LOG_CAPTURED"],"description":"The type associated with this record."},"logs":{"type":"string","description":"The logs associated with this record."}},"required":["type","logs"],"description":"Structured option 18 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["STREAM_HEARTBEAT_EMITTED"],"description":"The type associated with this record."},"runId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"lastEventId":{"type":"integer","minimum":0,"description":"The last event id associated with this record."}},"required":["type","runId","lastEventId"],"description":"Structured option 19 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["URL_CITED"],"description":"The type associated with this record."},"url":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"sourceId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"title":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","url","sourceId"],"description":"Structured option 20 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["DOCUMENT_CITED"],"description":"The type associated with this record."},"mediaType":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"sourceId":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"title":{"type":"string","minLength":1,"description":"Human-readable description for the record."},"filename":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","mediaType","sourceId"],"description":"Structured option 21 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["FILE_ATTACHED"],"description":"The type associated with this record."},"mediaType":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"url":{"type":"string","minLength":1,"description":"Human-readable description for the record."},"filename":{"type":"string","minLength":1,"description":"Human-readable description for the record."}},"required":["type","mediaType"],"description":"Structured option 22 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["FILES_CHANGED"],"description":"The type associated with this record."},"id":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."},"status":{"type":"string","nullable":true,"minLength":1,"description":"The tool call name associated with this record."},"changes":{"nullable":true,"description":"The changes associated with this record."}},"required":["type","id","status","changes"],"description":"Structured option 23 details associated with this record."},{"type":"object","properties":{"type":{"type":"string","enum":["RUNTIME_EVENT_RECORDED"],"description":"The type associated with this record."},"runtime":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"kind":{"type":"string","minLength":1,"description":"The tool call id associated with this record."},"value":{"nullable":true,"description":"The changes associated with this record."}},"required":["type","runtime","kind","value"],"description":"Structured option 24 details associated with this record."}],"description":"The event associated with this record."}},"required":["event_id","event"]}]}}},"required":["after_event_id","events"]}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/runs/{run_id}/children":{"get":{"tags":["Conversations"],"summary":"List child runs for a parent project-agent run","description":"Lists child agent runs spawned by the requested parent run in the conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"spawned_from_tool_call_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Child runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","minLength":1},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"message_id":{"type":"string","nullable":true,"format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"requested_by_user_id":{"type":"string","format":"uuid"},"trigger_principal_type":{"type":"string","nullable":true,"enum":["system","user","api_key","service_account"]},"trigger_principal_id":{"type":"string","nullable":true},"agent_id":{"type":"string","minLength":1,"maxLength":128},"status":{"anyOf":[{"type":"string","enum":["completed","failed","cancelled"]},{"type":"string","enum":["pending","running","waiting_for_tool"]}]},"implementation_kind":{"type":"string","nullable":true,"minLength":1,"maxLength":64},"worker_key":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"source_target_kind":{"type":"string","nullable":true,"enum":["project","main_branch","environment","preview_branch","release"]},"source_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"source_target_release_version":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"runtime_target_kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"runtime_target_environment_id":{"type":"string","nullable":true,"format":"uuid"},"runtime_target_branch_id":{"type":"string","nullable":true,"format":"uuid"},"parent_conversation_id":{"type":"string","nullable":true,"format":"uuid"},"parent_run_id":{"type":"string","nullable":true,"minLength":1},"spawned_from_message_id":{"type":"string","nullable":true,"format":"uuid"},"spawned_from_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"input_anchor_message_id":{"type":"string","nullable":true,"format":"uuid"},"handoff_message_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_deployment_id":{"type":"string","nullable":true,"format":"uuid"},"latest_event_id":{"type":"integer","minimum":0},"latest_external_event_sequence":{"type":"integer","minimum":0},"waiting_tool_call_id":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"waiting_tool_name":{"type":"string","nullable":true},"terminal_error_code":{"type":"string","nullable":true},"terminal_error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"started_at":{"type":"string","nullable":true},"finished_at":{"type":"string","nullable":true},"run_snapshot":{"type":"object","properties":{"project_agent":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["source"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","project_id","agent_id"]},{"type":"object","properties":{"kind":{"type":"string","enum":["installed"]},"project_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","minLength":1,"maxLength":128},"catalog_entry_id":{"type":"string","minLength":1},"agent_access_grant_id":{"type":"string","format":"uuid"},"service_account_id":{"type":"string","format":"uuid"}},"required":["kind","project_id","agent_id","catalog_entry_id","agent_access_grant_id","service_account_id"]},{"nullable":true}]},"source":{"type":"object","properties":{"type":{"type":"string","nullable":true,"enum":["project","catalog_entry"]},"path":{"type":"string","nullable":true},"hash":{"type":"string","nullable":true},"catalog_entry_id":{"type":"string","nullable":true}},"required":["type","path","hash","catalog_entry_id"]},"runtime_target":{"type":"object","properties":{"kind":{"type":"string","nullable":true,"enum":["main_branch","environment","preview_branch"],"description":"Provide the runtime target kind."},"environment_id":{"type":"string","nullable":true,"format":"uuid"},"branch_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_id":{"type":"string","nullable":true,"format":"uuid"},"resolved_target_kind":{"type":"string","nullable":true},"deployment_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["kind","environment_id","branch_id","resolved_target_id","resolved_target_kind","deployment_id"]},"requester":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"]}},"required":["project_agent","source","runtime_target","requester"]}},"required":["run_id","conversation_id","message_id","project_id","requested_by_user_id","agent_id","status","runtime_target_kind","latest_event_id","created_at","run_snapshot"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"404":{"description":"Parent run not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/runs/{run_id}/stream":{"get":{"tags":["Conversations"],"summary":"Attach to a durable agent run event stream","description":"Streams the sanitized public projection of one durable ordered run-event log using server-sent events. Private control-plane checkpoints and model call context are never emitted here; authorized diagnostics are available from GET /runs/{run_id}/events. The shared event ID cursor covers AG-UI wire events and sanitized Veryfront control-plane extensions. Persist Last-Event-ID for every valid ID-bearing frame, including event names the client does not render. See GET /runs/event-types for the canonical ag-ui and control-plane scopes. Pass format=typed for typed frames whose data is the same row shape as GET /runs/{run_id}/events?format=typed; the id cursor is unchanged.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"run_id","in":"path"},{"schema":{"type":"string","enum":["raw","typed"],"default":"raw","description":"Provide the format."},"required":false,"description":"Provide the format.","name":"format","in":"query"},{"schema":{"type":"string","description":"Resume strictly after this durable event ID. Advance it for every valid ID-bearing frame, including control-plane event names the client does not render."},"required":false,"name":"Last-Event-ID","in":"header"}],"responses":{"200":{"description":"Agent event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/input-requests":{"post":{"tags":["Conversations"],"summary":"Create a durable input request for a conversation","description":"Creates an owner-scoped durable input request for a conversation so a human responder can provide structured input.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"maxLength":255},"tool_call_id":{"type":"string","minLength":1,"maxLength":255},"kind":{"type":"string","enum":["form"],"default":"form"},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string","minLength":1,"maxLength":1000},"description":{"type":"string","minLength":1,"maxLength":20000},"fields":{"type":"array","items":{"type":"object","properties":{}},"minItems":1,"maxItems":100},"recommendations":{"type":"object","additionalProperties":{"nullable":true}},"expires_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["run_id","tool_call_id","requested_responder_type","title","fields"]}}}},"responses":{"201":{"description":"Created input request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"tool_call_id":{"type":"string"},"kind":{"type":"string","enum":["form"]},"status":{"type":"string","enum":["open","submitted","cancelled","expired"]},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"fields":{"type":"array","items":{"type":"object","properties":{}}},"recommendations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"expired_at":{"type":"string","nullable":true},"latest_response":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]}},"required":["id","conversation_id","run_id","tool_call_id","kind","status","requested_responder_type","title","description","fields","recommendations","metadata","created_at","expires_at","submitted_at","cancelled_at","expired_at"]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}},"get":{"tags":["Conversations"],"summary":"List durable input requests for a conversation","description":"Lists durable input requests for a conversation, optionally filtered by status or agent run.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"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","minLength":1,"maxLength":255},"required":false,"name":"run_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Input requests","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"tool_call_id":{"type":"string"},"kind":{"type":"string","enum":["form"]},"status":{"type":"string","enum":["open","submitted","cancelled","expired"]},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"fields":{"type":"array","items":{"type":"object","properties":{}}},"recommendations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"expired_at":{"type":"string","nullable":true},"latest_response":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]}},"required":["id","conversation_id","run_id","tool_call_id","kind","status","requested_responder_type","title","description","fields","recommendations","metadata","created_at","expires_at","submitted_at","cancelled_at","expired_at"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}}},"/conversations/{conversation_id}/input-requests/{input_request_id}":{"get":{"tags":["Conversations"],"summary":"Read a durable input request","description":"Returns one durable input request after verifying viewer access to the parent conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"input_request_id","in":"path"}],"responses":{"200":{"description":"Input request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"tool_call_id":{"type":"string"},"kind":{"type":"string","enum":["form"]},"status":{"type":"string","enum":["open","submitted","cancelled","expired"]},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"fields":{"type":"array","items":{"type":"object","properties":{}}},"recommendations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"expired_at":{"type":"string","nullable":true},"latest_response":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]}},"required":["id","conversation_id","run_id","tool_call_id","kind","status","requested_responder_type","title","description","fields","recommendations","metadata","created_at","expires_at","submitted_at","cancelled_at","expired_at"]}}}},"404":{"description":"Input request not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/input-requests/{input_request_id}/responses":{"post":{"tags":["Conversations"],"summary":"Submit a durable input response","description":"Submits a human response for an open durable input request after verifying editor access to the conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"input_request_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."}},"required":["values"]}}}},"responses":{"200":{"description":"Input response accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"input_request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"tool_call_id":{"type":"string"},"kind":{"type":"string","enum":["form"]},"status":{"type":"string","enum":["open","submitted","cancelled","expired"]},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"fields":{"type":"array","items":{"type":"object","properties":{}}},"recommendations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"expired_at":{"type":"string","nullable":true},"latest_response":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]}},"required":["id","conversation_id","run_id","tool_call_id","kind","status","requested_responder_type","title","description","fields","recommendations","metadata","created_at","expires_at","submitted_at","cancelled_at","expired_at"]},"input_response":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]},"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"}},"required":["success","input_request","input_response","accepted"]}}}},"404":{"description":"Input request not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}},"409":{"description":"Input request not open","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/conversations/{conversation_id}/input-requests/{input_request_id}/cancel":{"post":{"tags":["Conversations"],"summary":"Cancel a durable input request","description":"Cancels an open durable input request after verifying editor access to the parent conversation.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversation_id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"input_request_id","in":"path"}],"responses":{"200":{"description":"Input request cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"input_request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"tool_call_id":{"type":"string"},"kind":{"type":"string","enum":["form"]},"status":{"type":"string","enum":["open","submitted","cancelled","expired"]},"requested_responder_type":{"type":"string","enum":["human","agent","system"]},"title":{"type":"string"},"description":{"type":"string","nullable":true},"fields":{"type":"array","items":{"type":"object","properties":{}}},"recommendations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"expired_at":{"type":"string","nullable":true},"latest_response":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"input_request_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","nullable":true,"format":"uuid"},"run_id":{"type":"string"},"actor_type":{"type":"string","enum":["human","agent","system","integration"]},"actor_id":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Provide the option 1."},{"type":"boolean","description":"Provide the option 2."},{"type":"number","description":"Provide the option 3."},{"nullable":true,"description":"Provide the option 4."},{"nullable":true}],"description":"Additional structured values supplied to the tool."},"description":"Structured values submitted to the tool."},"created_at":{"type":"string"}},"required":["id","input_request_id","conversation_id","run_id","actor_type","actor_id","values","created_at"]}},"required":["id","conversation_id","run_id","tool_call_id","kind","status","requested_responder_type","title","description","fields","recommendations","metadata","created_at","expires_at","submitted_at","cancelled_at","expired_at"]}},"required":["input_request"]}}}},"404":{"description":"Input request not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/credits/balance":{"get":{"tags":["Credits"],"summary":"Get credit balance","description":"Returns the authenticated user credit balance by monthly tier pool and purchased pool.","responses":{"200":{"description":"Credit balance by pool","content":{"application/json":{"schema":{"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},"tier_limit":{"type":"number","description":"Monthly credit allocation for the user tier","example":50}},"required":["tier","purchased","total","tier_limit"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/credits/transactions":{"get":{"tags":["Credits"],"summary":"List credit transactions","description":"Returns 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","nullable":true,"description":"Human-readable transaction description"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"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","nullable":true,"description":"Project ID associated with the transaction"},"project_name":{"type":"string","nullable":true,"description":"Project name associated with the transaction"},"project_slug":{"type":"string","nullable":true,"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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/credits/packages":{"get":{"tags":["Credits"],"summary":"List credit packages","description":"Returns 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":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}}}}},"/credits/topup":{"post":{"tags":["Credits"],"summary":"Create credit checkout","description":"Creates 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":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/credits/coupons/redeem":{"post":{"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","nullable":true,"description":"Credit transaction associated with the redemption"}},"required":["status","credits_granted","balance","transaction_id"]}}}},"400":{"description":"Invalid coupon code","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"402":{"description":"Coupon redemption limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/gates/{gate}":{"get":{"tags":["Gates"],"summary":"Check gate access","description":"Checks whether the authenticated user or project owner can access a feature gate.","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","nullable":true,"minimum":0,"description":"Current resource count in camelCase form","example":2},"required":false,"name":"currentCount","in":"query"},{"schema":{"type":"integer","nullable":true,"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":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/dependency-artifacts/lookup":{"post":{"operationId":"lookupDependencyArtifacts","tags":["Dependencies"],"summary":"Look up dependency artifacts","description":"Returns durable artifact states for exact public npm identities. Requires a project-scoped Veryfront runtime token.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"artifacts":{"type":"array","items":{"type":"object","properties":{"origin_key":{"type":"string","enum":["npm:public"]},"package_name":{"type":"string","minLength":1,"maxLength":214,"pattern":"^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"},"exact_version":{"type":"string","minLength":1,"maxLength":128},"subpath":{"type":"string","maxLength":512,"default":""},"target":{"type":"string","enum":["es2022"]},"profile":{"type":"string","enum":["standard-v1","react-v1","react-dom-v1"]}},"required":["origin_key","package_name","exact_version","target","profile"],"additionalProperties":false},"minItems":1,"maxItems":100}},"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"]},"package_name":{"type":"string","minLength":1,"maxLength":214,"pattern":"^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"},"exact_version":{"type":"string","minLength":1,"maxLength":128},"subpath":{"type":"string","maxLength":512,"default":""},"target":{"type":"string","enum":["es2022"]},"profile":{"type":"string","enum":["standard-v1","react-v1","react-dom-v1"]}},"required":["origin_key","package_name","exact_version","target","profile"],"additionalProperties":false},"key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"status":{"type":"string","enum":["ready","missing","building","failed","denied"]},"root_content_hash":{"type":"string","nullable":true,"pattern":"^[0-9a-f]{64}$"},"graph_schema_version":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"attempt_count":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"retry_after":{"type":"string","nullable":true,"format":"date-time"},"failure_code":{"type":"string","nullable":true,"minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$"}},"required":["identity","key_hash","status","root_content_hash","graph_schema_version","attempt_count","retry_after","failure_code"]}}},"required":["artifacts"]}}}},"400":{"description":"Invalid dependency artifact identity or batch"},"401":{"description":"Authentication required"},"403":{"description":"Runtime authority required"}}}},"/dependency-artifacts/ensure":{"post":{"operationId":"ensureDependencyArtifacts","tags":["Dependencies"],"summary":"Ensure dependency artifacts","description":"Returns durable artifact states for exact public npm identities. Ingest is disabled in this release, so 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"]},"package_name":{"type":"string","minLength":1,"maxLength":214,"pattern":"^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"},"exact_version":{"type":"string","minLength":1,"maxLength":128},"subpath":{"type":"string","maxLength":512,"default":""},"target":{"type":"string","enum":["es2022"]},"profile":{"type":"string","enum":["standard-v1","react-v1","react-dom-v1"]}},"required":["origin_key","package_name","exact_version","target","profile"],"additionalProperties":false},"minItems":1,"maxItems":100}},"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"]},"package_name":{"type":"string","minLength":1,"maxLength":214,"pattern":"^(@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"},"exact_version":{"type":"string","minLength":1,"maxLength":128},"subpath":{"type":"string","maxLength":512,"default":""},"target":{"type":"string","enum":["es2022"]},"profile":{"type":"string","enum":["standard-v1","react-v1","react-dom-v1"]}},"required":["origin_key","package_name","exact_version","target","profile"],"additionalProperties":false},"key_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"status":{"type":"string","enum":["ready","missing","building","failed","denied"]},"root_content_hash":{"type":"string","nullable":true,"pattern":"^[0-9a-f]{64}$"},"graph_schema_version":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"attempt_count":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"retry_after":{"type":"string","nullable":true,"format":"date-time"},"failure_code":{"type":"string","nullable":true,"minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$"}},"required":["identity","key_hash","status","root_content_hash","graph_schema_version","attempt_count","retry_after","failure_code"]}}},"required":["artifacts"]}}}},"400":{"description":"Invalid dependency artifact identity or batch"},"401":{"description":"Authentication required"},"403":{"description":"Runtime authority required"}}}},"/dependency-artifacts/{artifact_id}/attempts/{attempt_count}/assets/{content_hash}":{"put":{"operationId":"uploadDependencyArtifactAsset","tags":["Dependencies"],"summary":"Upload a dependency artifact asset","description":"Uploads one immutable asset after verifying the signed runtime owns the current artifact build attempt.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"artifact_id","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"attempt_count","in":"path"},{"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"},"required":true,"name":"content_hash","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":"Invalid asset or content hash mismatch"},"401":{"description":"Authentication required"},"403":{"description":"Runtime publication authority required"},"412":{"description":"Build attempt is not current"},"413":{"description":"Asset exceeds the size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["Payload Too Large"]},"detail":{"type":"string"}},"required":["error","detail"]}}}}}}},"/dependency-artifacts/{artifact_id}/attempts/{attempt_count}/result":{"post":{"operationId":"reportDependencyArtifactBuildResult","tags":["Dependencies"],"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.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"artifact_id","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"attempt_count","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"outcome":{"type":"string","enum":["ready"]},"graph":{"type":"object","properties":{"graph_schema_version":{"type":"integer","minimum":0,"exclusiveMinimum":true},"root_content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"assets":{"type":"array","items":{"type":"object","properties":{"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"content_type":{"type":"string","enum":["text/javascript","text/css"]},"size":{"type":"integer","minimum":0}},"required":["content_hash","content_type","size"],"additionalProperties":false},"minItems":1,"maxItems":1024}},"required":["graph_schema_version","root_content_hash","assets"],"additionalProperties":false}},"required":["outcome","graph"],"additionalProperties":false},{"type":"object","properties":{"outcome":{"type":"string","enum":["failed"]},"failure_code":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$"},"failure_message":{"type":"string","minLength":1,"maxLength":500},"retry_after":{"type":"string","format":"date-time"}},"required":["outcome","failure_code"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Build result accepted","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]},"state":{"type":"string","enum":["ready","failed"]}},"required":["accepted","state"]}}}},"400":{"description":"Invalid build result"},"401":{"description":"Authentication required"},"403":{"description":"Runtime publication authority required"},"412":{"description":"Build attempt is not current"}}}},"/favorites":{"get":{"tags":["Favorites"],"summary":"List Favorites","description":"Get all projects favorited by the current user","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"}}},"required":["data","favorite_ids"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"500":{"description":"Server error"}}}},"/favorites/{project_reference}":{"get":{"tags":["Favorites"],"summary":"Check Favorite","description":"Check if a specific project is in the user's favorites","parameters":[{"schema":{"type":"string","description":"Project ID (UUID) or slug","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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"post":{"tags":["Favorites"],"summary":"Create Favorite","description":"Add a project to the user's favorites","parameters":[{"schema":{"type":"string","description":"Project ID (UUID) or slug","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"},"user_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"created_at":{"type":"string"}},"required":["id","user_id","project_id","created_at"]}},"required":["success","favorite"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}},"delete":{"tags":["Favorites"],"summary":"Delete Favorite","description":"Remove a project from the user's favorites","parameters":[{"schema":{"type":"string","description":"Project ID (UUID) or slug","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"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Favorite not found"},"500":{"description":"Server error"}}}},"/templates":{"get":{"tags":["Templates"],"summary":"List Templates","description":"Returns available project templates with support for filtering, sorting, and search.","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 (e.g., \"Store\", \"Landing\")","example":"Store"},"required":false,"name":"use_case","in":"query"},{"schema":{"type":"string","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.","example":"name:ASC"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["name","slug","created_at","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"},{"schema":{"type":"string","description":"Cursor for pagination (template ID)"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","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"},"slug":{"type":"string"},"name":{"type":"string"},"config":{"type":"object","properties":{"description":{"type":"string"},"category":{"type":"string"},"preview_url":{"type":"string"}}},"coming_soon":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","slug","name"]}},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"400":{"description":"Invalid query parameters"},"500":{"description":"Server error"}}}},"/templates/find":{"post":{"tags":["Templates"],"summary":"Search Templates","description":"Finds the best matching template for a project idea.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"user_intent":{"type":"string","maxLength":500,"description":"The user's description of what they want to build"}},"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","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"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient permissions"},"500":{"description":"Server error - AI processing failed"},"503":{"description":"Service unavailable - AI service not configured"}}}},"/oauth/connect/session":{"post":{"operationId":"oauthCreateConnectSession","tags":["OAuth"],"summary":"Create OAuth Connect Session","description":"Creates 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","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."}},"required":["session_token","connect_url"]}}}}}}},"/oauth/connect/{integration}":{"get":{"operationId":"oauthConnect","tags":["OAuth"],"summary":"Start OAuth Connection","description":"Starts 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","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","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":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable OAuth error message."}},"required":["error"]}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable OAuth error message."}},"required":["error"]}}}}}}},"/oauth/callback/{integration}":{"get":{"operationId":"oauthCallback","tags":["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","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","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":"Invalid callback","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable OAuth error message."}},"required":["error"]}}}}}}},"/oauth/status/{integration}":{"get":{"operationId":"oauthStatus","tags":["OAuth"],"summary":"Get OAuth Status","description":"Returns 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":"Exact current connection row; omitted when disconnected."},"connectionGenerationId":{"type":"string","format":"uuid","description":"Current destructive generation; omitted when disconnected."}},"required":["connected","integration"]}}}}}}},"/oauth/disconnect/{integration}":{"post":{"operationId":"oauthDisconnect","tags":["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":{"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":"Exact connection row to disconnect."}},"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"]}}}}}}},"/oauth/token/{integration}":{"get":{"operationId":"oauthGetToken","tags":["OAuth"],"summary":"Get Access Token","description":"Returns a valid access token for an integration.","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; required, OAuth tokens are project-scoped."},"required":false,"description":"Project UUID or slug; required, OAuth tokens are project-scoped.","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":"Token response (success, auth required, or refresh failed)","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"accessToken":{"type":"string","description":"Valid OAuth access token for the requested integration."}},"required":["accessToken"]},{"type":"object","properties":{"error":{"type":"string","enum":["authentication_required"]},"connectUrl":{"type":"string","description":"URL to start OAuth authorization for the requested integration."}},"required":["error","connectUrl"]},{"type":"object","properties":{"error":{"type":"string","enum":["refresh_failed"]},"message":{"type":"string","description":"Token refresh failure message."}},"required":["error","message"]}]}}}},"400":{"description":"Missing project scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable token retrieval error."}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable token retrieval error."}},"required":["error"]}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable token retrieval error."}},"required":["error"]}}}}}}},"/providers/{provider}/files":{"get":{"operationId":"providerListFiles","tags":["External Storage"],"summary":"List provider files","description":"Lists files and folders from an external storage provider using user or project provider credentials.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `google_drive`."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Optional project UUID or slug for project-scoped provider credentials."},"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"}],"responses":{"200":{"description":"File listing","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"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."},"mime_type":{"type":"string","description":"MIME type or `folder` for folders."},"size":{"type":"number","description":"File size in bytes. Folders may report 0."},"is_folder":{"type":"boolean","description":"Whether this item is a folder."},"modified_at":{"type":"string","description":"Provider modified timestamp."},"thumbnail":{"type":"string","description":"Optional provider thumbnail URL."}},"required":["id","name","path","mime_type","size","is_folder","modified_at"]},"description":"Provider files and folders."},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"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"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}},"post":{"operationId":"providerUploadFile","tags":["External Storage"],"summary":"Upload provider file","description":"Uploads base64-encoded file content to an external provider folder.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `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 for project-scoped provider credentials."},"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":{"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."},"mime_type":{"type":"string","description":"MIME type or `folder` for folders."},"size":{"type":"number","description":"File size in bytes. Folders may report 0."},"is_folder":{"type":"boolean","description":"Whether this item is a folder."},"modified_at":{"type":"string","description":"Provider modified timestamp."},"thumbnail":{"type":"string","description":"Optional provider thumbnail URL."}},"required":["id","name","path","mime_type","size","is_folder","modified_at"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}}},"/providers/{provider}/files/{file_id}":{"get":{"operationId":"providerGetFile","tags":["External Storage"],"summary":"Get provider file","description":"Returns provider file or folder metadata using user or project provider credentials.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `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 for project-scoped provider credentials."},"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":{"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."},"mime_type":{"type":"string","description":"MIME type or `folder` for folders."},"size":{"type":"number","description":"File size in bytes. Folders may report 0."},"is_folder":{"type":"boolean","description":"Whether this item is a folder."},"modified_at":{"type":"string","description":"Provider modified timestamp."},"thumbnail":{"type":"string","description":"Optional provider thumbnail URL."}},"required":["id","name","path","mime_type","size","is_folder","modified_at"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}},"put":{"operationId":"providerUpdateFile","tags":["External Storage"],"summary":"Update provider file","description":"Replaces a provider file with base64-encoded content.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `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 for project-scoped provider credentials."},"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":{"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."},"mime_type":{"type":"string","description":"MIME type or `folder` for folders."},"size":{"type":"number","description":"File size in bytes. Folders may report 0."},"is_folder":{"type":"boolean","description":"Whether this item is a folder."},"modified_at":{"type":"string","description":"Provider modified timestamp."},"thumbnail":{"type":"string","description":"Optional provider thumbnail URL."}},"required":["id","name","path","mime_type","size","is_folder","modified_at"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}},"delete":{"operationId":"providerDeleteFile","tags":["External Storage"],"summary":"Delete provider file","description":"Deletes a file or folder from an external storage provider.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `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 for project-scoped provider credentials."},"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"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}}},"/providers/{provider}/files/{file_id}/import":{"post":{"operationId":"providerImportFile","tags":["External Storage"],"summary":"Import provider file","description":"Imports a provider file into Veryfront storage after validating provider access and storage quota.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `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 for project-scoped provider credentials."},"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"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}}},"/providers/{provider}/folders":{"post":{"operationId":"providerCreateFolder","tags":["External Storage"],"summary":"Create provider folder","description":"Creates a folder in an external storage provider.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `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 for project-scoped provider credentials."},"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":{"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."},"mime_type":{"type":"string","description":"MIME type or `folder` for folders."},"size":{"type":"number","description":"File size in bytes. Folders may report 0."},"is_folder":{"type":"boolean","description":"Whether this item is a folder."},"modified_at":{"type":"string","description":"Provider modified timestamp."},"thumbnail":{"type":"string","description":"Optional provider thumbnail URL."}},"required":["id","name","path","mime_type","size","is_folder","modified_at"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}}},"/providers/{provider}/search":{"get":{"operationId":"providerSearchFiles","tags":["External Storage"],"summary":"Search provider files","description":"Searches files in an external storage provider using project provider credentials.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `google_drive`."},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","description":"Project UUID or slug for project-scoped provider credentials."},"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"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"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."},"mime_type":{"type":"string","description":"MIME type or `folder` for folders."},"size":{"type":"number","description":"File size in bytes. Folders may report 0."},"is_folder":{"type":"boolean","description":"Whether this item is a folder."},"modified_at":{"type":"string","description":"Provider modified timestamp."},"thumbnail":{"type":"string","description":"Optional provider thumbnail URL."}},"required":["id","name","path","mime_type","size","is_folder","modified_at"]},"description":"Provider files and folders."},"page_info":{"type":"object","properties":{"self":{"type":"string","nullable":true,"description":"Cursor pointing to the current page"},"first":{"type":"object","nullable":true,"enum":[null],"description":"First page cursor (always null for cursor-based pagination)"},"next":{"type":"string","nullable":true,"description":"Cursor for the next page (null if no more pages)"},"prev":{"type":"string","nullable":true,"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."}},"required":["data","page_info"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}}},"/providers/{provider}/files/{file_id}/move":{"post":{"operationId":"providerMoveFile","tags":["External Storage"],"summary":"Move provider file","description":"Moves or renames a file in an external storage provider.","parameters":[{"schema":{"type":"string","description":"External storage provider identifier, such as `onedrive`, `sharepoint`, or `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 for project-scoped provider credentials."},"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":{"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."},"mime_type":{"type":"string","description":"MIME type or `folder` for folders."},"size":{"type":"number","description":"File size in bytes. Folders may report 0."},"is_folder":{"type":"boolean","description":"Whether this item is a folder."},"modified_at":{"type":"string","description":"Provider modified timestamp."},"thumbnail":{"type":"string","description":"Optional provider thumbnail URL."}},"required":["id","name","path","mime_type","size","is_folder","modified_at"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"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"]}}}}}}},"/.well-known/jwks.json":{"get":{"operationId":"getJwks","tags":["Authentication"],"summary":"Get JWKS","description":"Returns 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":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/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 that opens one protected environment. An all-project key acts as its owner; a project-scoped key acts as a token principal for its own project only. The token is bound to the named project and environment, is not accepted by this API, and is not recalled when the key is revoked; it expires on its own.","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/logout":{"post":{"operationId":"oauthLogout","tags":["Authentication"],"summary":"Log Out","description":"Revokes the current session and clears the authentication cookie. Returns 503 if revocation cannot be confirmed.","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"}}}}}},"get":{"operationId":"oauthLogoutGetMethodNotAllowed","tags":["Authentication"],"summary":"Log Out","description":"Logout is only available through POST so cross-site GET requests cannot revoke sessions.","responses":{"405":{"description":"Logout must use POST","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/auth/magiclink/create":{"post":{"operationId":"createMagicLink","tags":["Authentication"],"summary":"Create Magic Link","description":"Sends 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","format":"uri","description":"URL to redirect after verification"},"required":false,"name":"redirect_url","in":"query"},{"schema":{"type":"string","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 magic_link_* error when the link is expired, already used, or invalid"},"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":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.veryfront.com/errors/validation-error"},"title":{"type":"string","description":"Short human-readable summary of the problem","example":"Validation Error"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code","example":400},"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"},"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"]}}}}}}},"/auth/github":{"get":{"operationId":"githubOAuth","tags":["Authentication"],"summary":"GitHub OAuth","description":"Starts or completes GitHub OAuth.","parameters":[{"schema":{"type":"string","description":"URL to redirect after authentication (OAuth 2.0 standard)"},"required":false,"name":"redirect_uri","in":"query"},{"schema":{"type":"string","description":"OAuth authorization code"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string","description":"CSRF state token"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","description":"OAuth error code (e.g., 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"}}}}}}},"/auth/google":{"get":{"operationId":"googleOAuth","tags":["Authentication"],"summary":"Google OAuth","description":"Starts or completes Google OAuth.","parameters":[{"schema":{"type":"string","description":"URL to redirect after authentication (OAuth 2.0 standard)"},"required":false,"name":"redirect_uri","in":"query"},{"schema":{"type":"string","description":"OAuth authorization code"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string","description":"CSRF state token"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","description":"OAuth error code (e.g., 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"}}}}}}},"/auth/microsoft":{"get":{"operationId":"microsoftOAuth","tags":["Authentication"],"summary":"Microsoft OAuth","description":"Starts or completes Microsoft OAuth.","parameters":[{"schema":{"type":"string","description":"URL to redirect after authentication (OAuth 2.0 standard)"},"required":false,"name":"redirect_uri","in":"query"},{"schema":{"type":"string","description":"OAuth authorization code"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string","description":"CSRF state token"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","description":"OAuth error code (e.g., 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"}}}}}}},"/errors":{"get":{"tags":["Errors"],"summary":"List error types","description":"Returns 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":{"tags":["Errors"],"summary":"Get error type by slug","description":"Returns full details for a single error type including solution steps and related errors. 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"}}}},"404":{"description":"Error type not found"}}}}},"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"},"tags":[{"name":"Projects","description":"Core project operations"},{"name":"Account","description":"Transitional account-level users and settings retained for dashboard compatibility"},{"name":"Project Users","description":"Project members and invites"},{"name":"Members","description":"Project members and invites"},{"name":"Files","description":"Main branch files"},{"name":"Branch Files","description":"Files on branches"},{"name":"Environment Files","description":"Files in environments"},{"name":"Release Files","description":"Files in releases"},{"name":"Uploads","description":"File uploads and assets"},{"name":"Branches","description":"Content branches for previews"},{"name":"Releases","description":"Published file snapshots"},{"name":"Deployments","description":"Connect releases to environments"},{"name":"Environments","description":"Deployment targets and variables"},{"name":"Environment Variables","description":"Project environment variable management"},{"name":"Domains","description":"Custom domains for environments"},{"name":"Project Servers","description":"Project-scoped dedicated server instances"},{"name":"Root Servers","description":"Transitional root dedicated-server administration retained for compatibility"},{"name":"Tasks","description":"Project tasks"},{"name":"Evals","description":"Project eval definitions and eval run projections"},{"name":"Workflows","description":"Project workflows"},{"name":"Workflow Runs","description":"Workflow run history and status"},{"name":"Schedules","description":"Recurring project automation schedules"},{"name":"Webhooks","description":"Webhook-triggered automation entry points"},{"name":"Skills","description":"Project skills"},{"name":"Prompts","description":"Project prompts"},{"name":"Tools","description":"Project tools"},{"name":"Resources","description":"Project-defined resource documents and source-backed resource definitions"},{"name":"Sandboxes","description":"Ephemeral sandbox execution environments"},{"name":"Search","description":"Text and vector search"},{"name":"Knowledge","description":"Knowledge manifest lookup across project knowledge files"},{"name":"Chunks","description":"File chunks for search indexing"},{"name":"Embeddings","description":"Vector embeddings"},{"name":"RAG Documents","description":"Project retrieval-augmented knowledge documents"},{"name":"Style Artifacts","description":"Project style artifact state and build outputs"},{"name":"Dependencies","description":"npm dependency resolution, exact-version pinning, and signed runtime artifact registry contracts"},{"name":"External Storage","description":"Transitional connected cloud-provider file operations"},{"name":"Project Cache","description":"Project-scoped distributed cache operations"},{"name":"User Cache","description":"Transitional user cache helpers retained for compatibility"},{"name":"API Keys","description":"Transitional user/account API key management; prefer project-scoped keys for public integrations"},{"name":"User","description":"Transitional current-user profile endpoint for first-party clients"},{"name":"Favorites","description":"Transitional user favorites for first-party dashboard clients"},{"name":"Subscriptions","description":"Transitional account billing and subscription workflows"},{"name":"Credits","description":"Transitional account credit balance, purchase, and insufficiency flows"},{"name":"Usage","description":"Project/account usage limits and warnings; account-level usage is transitional"},{"name":"Gates","description":"Transitional plan and feature gate checks for first-party clients"},{"name":"Channels","description":"Project channel integrations and delivery settings"},{"name":"Agents","description":"Project agents"},{"name":"Agent Templates","description":"Public template catalog of addable agents assembled from curated template projects"},{"name":"Agent Workers","description":"Internal/transitional agent worker leases and sessions"},{"name":"Agent Runtimes","description":"Registered push-based agent runtime services and runtime target health"},{"name":"Project Integrations","description":"Project-scoped integration catalog and configuration"},{"name":"Integrations","description":"Transitional external integration catalog for first-party clients"},{"name":"Connections","description":"Viewer-visible project and project-user integration connections"},{"name":"Integration Tools","description":"Transitional dynamic integration tool listing, invocation, and connection state"},{"name":"OAuth","description":"Transitional OAuth integration flows for first-party and connected-app clients"},{"name":"Templates","description":"Transitional starter-template discovery used during project creation"},{"name":"AI","description":"Transitional platform AI gateway/model helpers; project AI assets use project-scoped routes"},{"name":"Images","description":"Generated images and image assets"},{"name":"Conversations","description":"Transitional conversation/run-control HTTP surface for first-party clients"},{"name":"Runs","description":"Transitional hosted run-control endpoints for conversation execution"},{"name":"MCP","description":"MCP catalog/playground helpers; primary MCP traffic uses the streamable MCP handler"},{"name":"Logs","description":"Project log queries via Loki"},{"name":"Metrics","description":"Project metric queries via a Prometheus-compatible backend"},{"name":"Traces","description":"Project trace queries via Grafana Tempo"},{"name":"Errors","description":"Internal/public error type catalog (RFC 9457)"},{"name":"Authentication","description":"Transitional auth token, login, logout, magic-link, and JWKS flows"}],"x-tagGroups":[{"name":"Identity and Access","tags":["Authentication","User","Account","Project Users","Members","API Keys","OAuth"]},{"name":"Projects and Configuration","tags":["Projects","Environment Variables","Domains","Gates"]},{"name":"Agents","tags":["Agents","Agent Templates","Agent Workers","Agent Runtimes","Conversations","Prompts","Tools","Skills","Resources","Evals","Search","Knowledge","RAG Documents","Chunks","Embeddings","MCP","AI"]},{"name":"Automation","tags":["Tasks","Workflows","Runs","Workflow Runs","Schedules","Webhooks"]},{"name":"Develop","tags":["Files","Branch Files","Environment Files","Release Files","Branches","Uploads","Style Artifacts","Images","Templates","Dependencies"]},{"name":"Runtime","tags":["Sandboxes","Project Servers","Root Servers","Project Cache","User Cache"]},{"name":"Deploy","tags":["Environments","Releases","Deployments"]},{"name":"Observe","tags":["Logs","Metrics","Traces","Errors","Usage"]},{"name":"Connect","tags":["Channels","Project Integrations","Integrations","Connections","Integration Tools","External Storage"]},{"name":"Admin","tags":["Subscriptions","Credits","Favorites"]}],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}]}