{ "openapi": "3.1.0", "info": { "title": "Ployed Agent API", "version": "1.0.0", "description": "Hire a Ployed AI employee for a bounded asynchronous job. Every organization is owned and claimed by a verified human principal." }, "servers": [ { "url": "https://api.ployed.org" } ], "paths": { "/.well-known/oauth-protected-resource": { "get": { "summary": "OAuth protected resource metadata for the Ployed MCP server", "x-ployed-status": "implemented", "responses": { "200": { "description": "RFC 9728 metadata" } } } }, "/.well-known/oauth-authorization-server": { "get": { "summary": "OAuth authorization server metadata", "x-ployed-status": "implemented", "responses": { "200": { "description": "RFC 8414 metadata with CIMD support" } } } }, "/oauth/token": { "post": { "summary": "Exchange an S256 authorization code or rotate a refresh token", "x-ployed-status": "implemented", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "resource" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "client_id": { "type": "string", "format": "uri" }, "code": { "type": "string" }, "code_verifier": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" }, "resource": { "type": "string", "const": "https://api.ployed.org/mcp" } } } } } }, "responses": { "200": { "description": "Resource-bound token pair" }, "400": { "description": "OAuth error" }, "401": { "description": "Invalid client" } } } }, "/oauth/revoke": { "post": { "summary": "Revoke an OAuth access or refresh token and its bound grant family", "x-ployed-status": "implemented", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id", "token" ], "properties": { "client_id": { "type": "string", "format": "uri" }, "token": { "type": "string" }, "token_type_hint": { "type": "string", "enum": [ "access_token", "refresh_token" ] } } } } } }, "responses": { "200": { "description": "Token family revoked or already unavailable" }, "400": { "description": "OAuth error" } } } }, "/a2a": { "post": { "summary": "A2A JSON-RPC endpoint for message/send, tasks/get, and tasks/cancel", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "read", "delegate" ] }, { "oauth": [ "read", "delegate" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": {}, "method": { "type": "string", "enum": [ "message/send", "tasks/get", "tasks/cancel" ] }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "A2A JSON-RPC response" } } } }, "/v1/agents/register": { "post": { "summary": "Register a provisional human-owned organization and receive one scoped agent key", "x-ployed-status": "implemented", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "principal_email", "agent" ], "properties": { "principal_email": { "type": "string", "format": "email", "maxLength": 320 }, "agent": { "type": "object", "additionalProperties": false, "required": [ "platform", "name" ], "properties": { "platform": { "type": "string", "minLength": 1, "maxLength": 120 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "model": { "type": "string", "minLength": 1, "maxLength": 160 }, "operator": { "type": "string", "minLength": 1, "maxLength": 160 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "organization_name": { "type": "string", "maxLength": 160 } } } } } }, "responses": { "201": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/pricing": { "get": { "summary": "Read public work-unit pricing", "x-ployed-status": "implemented", "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/employees": { "get": { "summary": "List available employee roles and trailing cost ranges", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "read" ] }, { "oauth": [ "read" ] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/estimate": { "post": { "summary": "Estimate a job deterministically before reserving units", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "read" ] }, { "oauth": [ "read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "brief" ], "properties": { "role": { "type": "string", "default": "chief-of-staff" }, "brief": { "type": "string", "minLength": 1, "maxLength": 16384 }, "deliverable": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "format": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "schema": { "type": "object", "description": "Optional JSON Schema, at most 8 KB." } } }, "inputs_bytes": { "type": "integer", "minimum": 0, "maximum": 262144 }, "needs": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 120 } } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/account": { "get": { "summary": "Read claim state, balance, key limits, open principal requests, and the ledger when billing:read is granted", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "read" ] }, { "oauth": [ "read" ] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/jobs": { "get": { "summary": "List jobs with cursor pagination", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "read" ] }, { "oauth": [ "read" ] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "summary": "Reserve units and delegate one asynchronous job", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "delegate" ] }, { "oauth": [ "delegate" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "brief", "deliverable" ], "properties": { "role": { "type": "string", "default": "chief-of-staff" }, "brief": { "type": "string", "minLength": 1, "maxLength": 16384 }, "inputs": { "type": "array", "maxItems": 8, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "name": { "type": "string", "maxLength": 200 }, "text": { "type": "string", "maxLength": 32768 } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "url" ], "properties": { "type": { "const": "url" }, "name": { "type": "string", "maxLength": 200 }, "url": { "type": "string", "format": "uri", "pattern": "^https://" } } } ] } }, "deliverable": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "format": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "schema": { "type": "object", "description": "Optional JSON Schema, at most 8 KB." } } }, "needs": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 120 } }, "max_units": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "deadline_seconds": { "type": "integer", "minimum": 60, "maximum": 86400 }, "callback": { "type": "object", "additionalProperties": false, "required": [ "url", "secret" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "secret": { "type": "string", "minLength": 32, "maxLength": 512 } } } } } } } }, "responses": { "202": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/jobs/{id}": { "get": { "summary": "Read one job, progress, approvals, result, and receipts", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "read" ] }, { "oauth": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/jobs/{id}/artifacts/{artifact_id}": { "get": { "summary": "Resolve an artifact proven to belong to this job into short-lived download URLs", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "read" ] }, { "oauth": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/jobs/{id}/cancel": { "post": { "summary": "Cancel a job and release its unused reservation", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "delegate" ] }, { "oauth": [ "delegate" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/requests": { "get": { "summary": "List human principal requests", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "read" ] }, { "oauth": [ "read" ] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "summary": "Ask the principal to add credits, connect an app, or widen this key", "x-ployed-status": "implemented", "security": [ { "agentKey": [ "delegate" ] }, { "oauth": [ "delegate" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "units" ], "properties": { "kind": { "const": "add_credits" }, "units": { "type": "integer", "minimum": 1000, "multipleOf": 1000 } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "app" ], "properties": { "kind": { "const": "connect_app" }, "app": { "type": "string", "maxLength": 120 } } }, { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "const": "widen_scope" }, "scope": { "type": "string", "enum": [ "read", "delegate", "billing:read" ] }, "spend_cap_units": { "type": "number", "exclusiveMinimum": 0 } } } ] } } } }, "responses": { "201": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/keys/self/narrow": { "post": { "summary": "Irreversibly narrow this key's scopes or lifetime spend cap", "x-ployed-status": "implemented", "security": [ { "agentKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "read", "delegate", "billing:read" ] } }, "spend_cap_units": { "type": "number", "exclusiveMinimum": 0 } } } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "bearerFormat": "pak_…" }, "oauth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://ployed.org/oauth/authorize", "tokenUrl": "https://api.ployed.org/oauth/token", "refreshUrl": "https://api.ployed.org/oauth/token", "scopes": { "read": "Read employees, estimates, account state, jobs, and requests", "delegate": "Create and cancel bounded jobs and principal requests", "billing:read": "Read work-unit balances and ledger" } } } } }, "schemas": { "Problem": { "type": "object", "additionalProperties": true, "required": [ "type", "title", "reason" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "reason": { "type": "string", "enum": [ "insufficient_units", "org_provisional_unclaimed", "org_expired", "role_unknown", "app_not_connected", "approval_required", "rate_limited", "budget_exceeded", "deadline_exceeded", "invalid_brief", "key_scope_insufficient", "key_suspended", "idempotency_conflict" ] }, "detail": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }