{ "openapi": "3.1.0", "info": { "title": "drp.icu — Modern Zen for agents", "version": "1.0.0", "summary": "Plans, recommendations, agent-readiness scans, briefs, orders, and status.", "description": "The REST face of drp.icu. Same capabilities as the MCP server at https://drp.icu/mcp. Every success body carries next_actions; every error carries a concrete fix. Prices come from the catalog only.", "contact": { "name": "Modern Zen Strategies, Inc.", "url": "https://modernzen.co", "email": "enter@drp.icu" }, "termsOfService": "https://modernzen.co/legal/", "license": { "name": "© Modern Zen Strategies, Inc.", "url": "https://modernzen.co/legal/" } }, "servers": [ { "url": "https://drp.icu" } ], "security": [], "tags": [ { "name": "discovery", "description": "Static, cacheable surfaces." }, { "name": "catalog", "description": "Plans, availability, recommendations." }, { "name": "intake", "description": "Briefs and quotes." }, { "name": "commerce", "description": "Orders, payment, engagements." } ], "paths": { "/plans.json": { "get": { "operationId": "getCatalog", "summary": "Catalog", "description": "All published plans, prices, offerings, and terms. Cached 5 minutes; strong ETag.", "tags": [ "discovery" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalog_version": { "type": "string" }, "currency": { "type": "string", "const": "usd" }, "provider": { "type": "object", "properties": { "name": { "type": "string" }, "legal_name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "agent_entrance": { "type": "string", "format": "uri" }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "booking_url": { "type": "string", "format": "uri" }, "legal_url": { "type": "string", "format": "uri" } }, "required": [ "name", "legal_name", "url", "agent_entrance", "email", "booking_url", "legal_url" ], "additionalProperties": false }, "terms": { "type": "object", "properties": { "cancel_anytime": { "type": "boolean" }, "cancellation_effective": { "type": "string", "enum": [ "end_of_paid_term", "immediate" ] }, "client_owns_outputs": { "type": "boolean" }, "support_channels": { "type": "array", "items": { "type": "string" } }, "direct_founder_access": { "type": "boolean" }, "response_sla": { "type": "object", "properties": { "duration": { "type": "string" }, "business_days": { "type": "boolean" }, "timezone": { "type": "string" }, "label": { "type": "string" } }, "required": [ "duration", "business_days", "timezone", "label" ], "additionalProperties": false }, "agentic_checkout": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "max_order_usd": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "term_months": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "stripe_spt", "stablecoin" ] } }, "stablecoin_enabled": { "type": "boolean" } }, "required": [ "enabled", "max_order_usd", "term_months", "methods", "stablecoin_enabled" ], "additionalProperties": false }, "human_checkout": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "provider": { "type": "string", "const": "stripe_checkout" } }, "required": [ "enabled", "provider" ], "additionalProperties": false } }, "required": [ "cancel_anytime", "cancellation_effective", "client_owns_outputs", "support_channels", "direct_founder_access", "response_sla", "agentic_checkout", "human_checkout" ], "additionalProperties": false }, "offerings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "06" ] }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" } }, "required": [ "id", "slug", "name", "summary" ], "additionalProperties": false } }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "offerings": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "06" ] } }, "kind": { "type": "string", "enum": [ "subscription", "one_time", "quote" ] }, "add_on": { "type": "boolean" }, "price": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] } }, "required": [ "amount_cents", "interval" ], "additionalProperties": false }, { "type": "null" } ] }, "duration": { "type": "string", "pattern": "^P\\d+[DWM]$" }, "autonomy": { "type": "string", "enum": [ "auto", "approval", "human" ] }, "requires": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string", "minLength": 1 }, "deliverables": { "type": "array", "items": { "type": "string" } }, "includes": { "type": "array", "items": { "type": "string" } }, "excludes": { "type": "array", "items": { "type": "string" } }, "onboarding_inputs": { "type": "array", "items": { "type": "string" } }, "proposed": { "type": "boolean" }, "url": { "type": "string", "format": "uri" } }, "required": [ "id", "name", "offerings", "kind", "add_on", "price", "autonomy", "requires", "summary", "includes", "excludes", "onboarding_inputs", "url" ], "additionalProperties": false } } }, "required": [ "catalog_version", "currency", "provider", "terms", "offerings", "plans" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/proof.json": { "get": { "operationId": "getProof", "summary": "Proof", "description": "Case studies as structured claims with source links.", "tags": [ "discovery" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "client": { "type": "string" }, "claim": { "type": "string" }, "metric": { "type": "object", "properties": { "before": { "type": [ "number", "null" ] }, "after": { "type": [ "number", "null" ] }, "unit": { "type": "string" }, "period": { "type": "string" } }, "required": [ "before", "after", "unit", "period" ], "additionalProperties": false }, "source_url": { "type": "string", "format": "uri" }, "verified": { "type": "boolean" } }, "required": [ "id", "client", "claim", "metric", "source_url", "verified" ], "additionalProperties": false } } }, "required": [ "updated", "entries" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent.json": { "get": { "operationId": "getAgentManifest", "summary": "Entrance manifest", "description": "Offerings, the gate, the brief JSON Schema, and an index of every surface.", "tags": [ "discovery" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "surfaces": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "brief": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "surfaces", "brief" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/catalog": { "get": { "operationId": "listCatalog", "summary": "Catalog with capacity", "description": "Offerings, published plans, terms, and a capacity summary. Free.", "tags": [ "catalog" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalog_version": { "type": "string" }, "currency": { "type": "string", "const": "usd" }, "provider": { "type": "object", "properties": { "name": { "type": "string" }, "legal_name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "booking_url": { "type": "string", "format": "uri" }, "legal_url": { "type": "string", "format": "uri" } }, "required": [ "name", "legal_name", "url", "email", "booking_url", "legal_url" ], "additionalProperties": false }, "terms": { "type": "object", "properties": { "cancel_anytime": { "type": "boolean" }, "cancellation_effective": { "type": "string", "enum": [ "end_of_paid_term", "immediate" ] }, "client_owns_outputs": { "type": "boolean" }, "support_channels": { "type": "array", "items": { "type": "string" } }, "direct_founder_access": { "type": "boolean" }, "response_sla": { "type": "object", "properties": { "duration": { "type": "string" }, "business_days": { "type": "boolean" }, "timezone": { "type": "string" }, "label": { "type": "string" } }, "required": [ "duration", "business_days", "timezone", "label" ], "additionalProperties": false }, "agentic_checkout": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "max_order_usd": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "term_months": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "stripe_spt", "stablecoin" ] } }, "stablecoin_enabled": { "type": "boolean" } }, "required": [ "enabled", "max_order_usd", "term_months", "methods", "stablecoin_enabled" ], "additionalProperties": false }, "human_checkout": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "provider": { "type": "string", "const": "stripe_checkout" } }, "required": [ "enabled", "provider" ], "additionalProperties": false } }, "required": [ "cancel_anytime", "cancellation_effective", "client_owns_outputs", "support_channels", "direct_founder_access", "response_sla", "agentic_checkout", "human_checkout" ], "additionalProperties": false }, "offerings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "06" ] }, "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" } }, "required": [ "id", "slug", "name", "summary" ], "additionalProperties": false } }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "offerings": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "06" ] } }, "kind": { "type": "string", "enum": [ "subscription", "one_time", "quote" ] }, "add_on": { "type": "boolean" }, "price": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] } }, "required": [ "amount_cents", "interval" ], "additionalProperties": false }, { "type": "null" } ] }, "duration": { "type": "string", "pattern": "^P\\d+[DWM]$" }, "autonomy": { "type": "string", "enum": [ "auto", "approval", "human" ] }, "requires": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string", "minLength": 1 }, "deliverables": { "type": "array", "items": { "type": "string" } }, "includes": { "type": "array", "items": { "type": "string" } }, "excludes": { "type": "array", "items": { "type": "string" } }, "onboarding_inputs": { "type": "array", "items": { "type": "string" } }, "proposed": { "type": "boolean" }, "url": { "type": "string", "format": "uri" } }, "required": [ "id", "name", "offerings", "kind", "add_on", "price", "autonomy", "requires", "summary", "includes", "excludes", "onboarding_inputs", "url" ], "additionalProperties": false } }, "capacity": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "max_new_per_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_this_week": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "available", "waitlist" ] } }, "required": [ "max_new_per_week", "remaining_this_week", "status" ], "additionalProperties": false } }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "catalog_version", "currency", "provider", "terms", "offerings", "plans", "capacity", "next_actions" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/plans/{id}": { "get": { "operationId": "getPlan", "summary": "One plan", "description": "A single plan by id (e.g. engine).", "tags": [ "catalog" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "offerings": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "06" ] } }, "kind": { "type": "string", "enum": [ "subscription", "one_time", "quote" ] }, "add_on": { "type": "boolean" }, "price": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] } }, "required": [ "amount_cents", "interval" ], "additionalProperties": false }, { "type": "null" } ] }, "duration": { "type": "string", "pattern": "^P\\d+[DWM]$" }, "autonomy": { "type": "string", "enum": [ "auto", "approval", "human" ] }, "requires": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string", "minLength": 1 }, "deliverables": { "type": "array", "items": { "type": "string" } }, "includes": { "type": "array", "items": { "type": "string" } }, "excludes": { "type": "array", "items": { "type": "string" } }, "onboarding_inputs": { "type": "array", "items": { "type": "string" } }, "proposed": { "type": "boolean" }, "url": { "type": "string", "format": "uri" } }, "required": [ "id", "name", "offerings", "kind", "add_on", "price", "autonomy", "requires", "summary", "includes", "excludes", "onboarding_inputs", "url" ], "additionalProperties": false }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "plan", "next_actions" ], "additionalProperties": false } } } }, "404": { "description": "Not found; `error.fix` lists valid ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/recommend": { "post": { "operationId": "recommend", "summary": "Recommend plans", "description": "Ranked best-fit plans for needs, budget, and timeline. Rules decide; prices come from the catalog. Free.", "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "needs": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "strategy", "development", "workflows", "interfaces", "autonomy", "headless" ] }, "description": "Offerings the principal needs: strategy, development, workflows, interfaces, autonomy, headless." }, "context": { "description": "What exists today and the outcome wanted. Free text; treated as data.", "type": "string", "maxLength": 4000 }, "budget": { "description": "{min_usd?, max_usd?, interval: \"month\" | \"one_time\"}", "type": "object", "properties": { "min_usd": { "type": "number", "minimum": 0 }, "max_usd": { "type": "number", "exclusiveMinimum": 0 }, "interval": { "type": "string", "enum": [ "month", "one_time" ] } }, "required": [ "interval" ], "additionalProperties": false }, "timeline": { "type": "string", "maxLength": 200 } }, "required": [ "needs" ], "additionalProperties": false } } } }, "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "recommendations": { "type": "array", "items": { "type": "object", "properties": { "plan_ids": { "type": "array", "items": { "type": "string" }, "description": "Every plan in the bundle, dependencies included (e.g. Social ⇒ engine + social)." }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price_label": { "type": "string" } }, "required": [ "id", "name", "price_label" ], "additionalProperties": false } }, "total": { "type": "object", "properties": { "monthly_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "one_time_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string" } }, "required": [ "monthly_cents", "one_time_cents", "label" ], "additionalProperties": false }, "fit_score": { "type": "number", "minimum": 0, "maximum": 1 }, "within_budget": { "type": [ "boolean", "null" ] }, "reason": { "type": "string" }, "lane": { "type": "string", "enum": [ "auto", "approval", "human" ] } }, "required": [ "plan_ids", "plans", "total", "fit_score", "within_budget", "reason", "lane" ], "additionalProperties": false } }, "uncovered_needs": { "type": "array", "items": { "type": "string", "enum": [ "strategy", "development", "workflows", "interfaces", "autonomy", "headless" ] } }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "recommendations", "uncovered_needs", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/availability": { "get": { "operationId": "availability", "summary": "Availability", "description": "Per plan: available or waitlist, plus the earliest start date.", "tags": [ "catalog" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string" }, "timezone": { "type": "string" }, "plans": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "type": "string" }, "available": { "type": "boolean" }, "status": { "type": "string", "enum": [ "available", "waitlist" ] }, "earliest_start": { "type": "string", "description": "ISO date (YYYY-MM-DD)." }, "capacity_key": { "type": [ "string", "null" ] }, "remaining_this_week": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "plan_id", "available", "status", "earliest_start", "capacity_key", "remaining_this_week" ], "additionalProperties": false } }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "as_of", "timezone", "plans", "next_actions" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/scan": { "post": { "operationId": "scanSite", "summary": "Agent-readiness scan", "description": "Free scan of a public website: score 0–100, twelve checks with fixes, and which plans close the gaps. Cached per origin for 24 h. Rate-limited.", "tags": [ "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The site to scan, e.g. https://example.com. Public http(s) hosts only." } }, "required": [ "url" ], "additionalProperties": false } } } }, "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "origin": { "type": "string" }, "scanned_at": { "type": "string" }, "cached": { "type": "boolean" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "pass": { "type": "boolean" }, "weight": { "type": "number" }, "detail": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "id", "label", "pass", "weight", "detail", "fix" ], "additionalProperties": false } }, "recommended_plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price_label": { "type": "string" }, "why": { "type": "string" } }, "required": [ "id", "name", "price_label", "why" ], "additionalProperties": false } }, "fetches": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "url", "origin", "scanned_at", "cached", "score", "grade", "checks", "recommended_plans", "fetches", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/human": { "post": { "operationId": "talkToAHuman", "summary": "Talk to a human", "description": "Routes to Sedale at Modern Zen; returns the booking link and email.", "tags": [ "intake" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "description": "What the conversation is about, e.g. \"SAGE partnership\".", "type": "string", "maxLength": 500 }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The human or organization the agent acts for." }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Where kickoff, quotes, and receipts are sent. Always a human inbox." }, "org": { "type": "string", "maxLength": 200 }, "website": { "type": "string", "format": "uri" } }, "required": [ "name", "email" ], "additionalProperties": false }, "message": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } } } }, "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "booking_url": { "type": "string", "format": "uri" }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "eta": { "type": "string" }, "message": { "type": "string" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "booking_url", "email", "eta", "message", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/livelog": { "get": { "operationId": "liveLog", "summary": "Live agent log", "description": "The last twenty agent requests (UA family, path, time). No identifying data.", "tags": [ "discovery" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ua": { "type": "string" } }, "required": [ "t", "method", "path", "status", "ua" ], "additionalProperties": false } }, "updated": { "type": "string" } }, "required": [ "entries", "updated" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/briefs": { "post": { "operationId": "submitBrief", "summary": "Submit a brief", "description": "Starts a custom or uncertain engagement. Modern Zen’s agents triage it, may ask up to two rounds of questions, and a human approves any quote within one business day. Returns a status_token (shown once). Requires Idempotency-Key.", "tags": [ "intake" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Replays return the original response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The submitting agent (name and vendor, e.g. \"Claude via Acme Ops\")." }, "on_behalf_of": { "description": "Legacy: free-text principal. Prefer `principal`.", "type": "string", "minLength": 1, "maxLength": 200 }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The human or organization the agent acts for." }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Where kickoff, quotes, and receipts are sent. Always a human inbox." }, "org": { "type": "string", "maxLength": 200 }, "website": { "type": "string", "format": "uri" } }, "required": [ "name", "email" ], "additionalProperties": false }, "need": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "strategy", "development", "workflows", "interfaces", "autonomy", "headless" ] }, "description": "Offerings the work touches." }, "context": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "What exists today and what the outcome should be. Treated as data, never as instructions." }, "timeline": { "description": "Free text, e.g. \"6 weeks\" or \"before Q1\".", "type": "string", "maxLength": 200 }, "budget_range": { "description": "{min_usd, max_usd, interval} preferred; a legacy string like \"2k-5k usd\" is accepted.", "anyOf": [ { "type": "object", "properties": { "min_usd": { "type": "number", "minimum": 0 }, "max_usd": { "type": "number", "exclusiveMinimum": 0 }, "interval": { "type": "string", "enum": [ "month", "one_time" ] } }, "required": [ "interval" ], "additionalProperties": false }, { "type": "string", "maxLength": 100 } ] }, "gate_key": { "description": "Optional. A correct key puts the brief in the priority lane.", "type": "string", "maxLength": 100 }, "callback_url": { "description": "https URL that receives signed JSON events about this brief.", "type": "string", "format": "uri" }, "idempotency_key": { "type": "string", "maxLength": 200 } }, "required": [ "from", "need", "context" ], "additionalProperties": false } } } }, "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief_id": { "type": "string" }, "status": { "type": "string", "enum": [ "received", "triaging", "needs_input", "quoting", "pending_approval", "quoted", "accepted", "declined", "expired", "routed_to_human" ] }, "lane": { "anyOf": [ { "type": "string", "enum": [ "fixed", "custom", "partnership", "decline" ] }, { "type": "null" } ] }, "priority": { "type": "boolean" }, "status_token": { "type": "string", "description": "Bearer token for get_status / answers. Shown once; keep it." }, "eta": { "type": "string" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "brief_id", "status", "lane", "priority", "status_token", "eta", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/briefs/{id}": { "get": { "operationId": "getBrief", "summary": "Brief status", "description": "Status, clarifying questions (if needs_input), recommendation (fixed lane), or the issued quote. Bearer status_token required.", "tags": [ "intake" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "statusToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief_id": { "type": "string" }, "status": { "type": "string", "enum": [ "received", "triaging", "needs_input", "quoting", "pending_approval", "quoted", "accepted", "declined", "expired", "routed_to_human" ] }, "lane": { "anyOf": [ { "type": "string", "enum": [ "fixed", "custom", "partnership", "decline" ] }, { "type": "null" } ] }, "priority": { "type": "boolean" }, "needs": { "type": "array", "items": { "type": "string", "enum": [ "strategy", "development", "workflows", "interfaces", "autonomy", "headless" ] } }, "questions": { "type": "array", "items": { "type": "string" }, "description": "Present when status is needs_input." }, "recommendation": { "anyOf": [ { "type": "object", "properties": { "plan_ids": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" } }, "required": [ "plan_ids", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Present for the fixed lane." }, "quote": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "brief_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "issued", "accepted", "declined", "expired" ] }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "description": "A catalog plan id, or null for custom work.", "type": [ "string", "null" ] }, "description": { "type": "string", "maxLength": 300 }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] } }, "required": [ "plan_id", "description", "amount_cents", "interval" ], "additionalProperties": false } }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] }, "assumptions": { "type": "array", "items": { "type": "string" } }, "timeline": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "brief_id", "status", "line_items", "total_cents", "interval", "assumptions", "timeline", "issued_at", "expires_at" ], "additionalProperties": false }, { "type": "null" } ] }, "decline_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "brief_id", "status", "lane", "priority", "needs", "questions", "recommendation", "quote", "decline_reason", "updated_at", "next_actions" ], "additionalProperties": false } } } }, "404": { "description": "Not found; `error.fix` lists valid ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/briefs/{id}/answers": { "post": { "operationId": "answerQuestions", "summary": "Answer clarifying questions", "description": "Reply to the Scoper’s questions; triage resumes. Bearer status_token required.", "tags": [ "intake" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Replays return the original response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 300 }, "answer": { "type": "string", "maxLength": 2000 } }, "required": [ "question", "answer" ], "additionalProperties": false } } }, "required": [ "answers" ], "additionalProperties": false } } } }, "security": [ { "statusToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief_id": { "type": "string" }, "status": { "type": "string", "enum": [ "received", "triaging", "needs_input", "quoting", "pending_approval", "quoted", "accepted", "declined", "expired", "routed_to_human" ] }, "lane": { "anyOf": [ { "type": "string", "enum": [ "fixed", "custom", "partnership", "decline" ] }, { "type": "null" } ] }, "priority": { "type": "boolean" }, "needs": { "type": "array", "items": { "type": "string", "enum": [ "strategy", "development", "workflows", "interfaces", "autonomy", "headless" ] } }, "questions": { "type": "array", "items": { "type": "string" }, "description": "Present when status is needs_input." }, "recommendation": { "anyOf": [ { "type": "object", "properties": { "plan_ids": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" } }, "required": [ "plan_ids", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Present for the fixed lane." }, "quote": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "brief_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "issued", "accepted", "declined", "expired" ] }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "description": "A catalog plan id, or null for custom work.", "type": [ "string", "null" ] }, "description": { "type": "string", "maxLength": 300 }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] } }, "required": [ "plan_id", "description", "amount_cents", "interval" ], "additionalProperties": false } }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] }, "assumptions": { "type": "array", "items": { "type": "string" } }, "timeline": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "brief_id", "status", "line_items", "total_cents", "interval", "assumptions", "timeline", "issued_at", "expires_at" ], "additionalProperties": false }, { "type": "null" } ] }, "decline_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "brief_id", "status", "lane", "priority", "needs", "questions", "recommendation", "quote", "decline_reason", "updated_at", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found; `error.fix` lists valid ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/orders": { "post": { "operationId": "createOrder", "summary": "Create an order", "description": "Orders fixed-price plans (or renews an engagement via engagement_id) and returns a payment URL that works for an agent (MPP, Shared Payment Token) or a human (Stripe Checkout). Add-ons need their base plan in the same order or an active engagement. Capacity-limited plans may come back waitlisted with an earliest start. Requires Idempotency-Key.", "tags": [ "commerce" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Replays return the original response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "plan_id": { "type": "string" } }, "required": [ "plan_id" ], "additionalProperties": false }, "description": "Fixed-price plan ids. Add-ons need their base plan in the same order or an active engagement for the principal." }, "term_months": { "default": 1, "description": "Prepaid term for subscription plans when an agent pays (1, 3, or 6). Humans paying by Stripe Checkout get a monthly subscription instead.", "type": "integer", "minimum": 1, "maximum": 12 }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The human or organization the agent acts for." }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Where kickoff, quotes, and receipts are sent. Always a human inbox." }, "org": { "type": "string", "maxLength": 200 }, "website": { "type": "string", "format": "uri" } }, "required": [ "name", "email" ], "additionalProperties": false, "description": "The human the plans are for. Receives the kickoff email and the receipts." }, "agent": { "description": "The ordering agent (name and vendor).", "type": "string", "maxLength": 200 }, "engagement_id": { "description": "Renewing? The eng_… id; items then default to that engagement’s plans.", "type": "string" }, "gate_key": { "type": "string", "maxLength": 100 }, "callback_url": { "description": "https URL that receives signed JSON events (paid, engagement.created, renewal_due).", "type": "string", "format": "uri" }, "idempotency_key": { "type": "string", "maxLength": 200 } }, "required": [ "items", "term_months", "principal" ], "additionalProperties": false } } } }, "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "paid", "failed", "canceled", "refunded" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string", "enum": [ "subscription", "one_time", "custom" ] }, "unit_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] }, "quantity_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Months charged for subscription items (term); 1 for one-time." }, "line_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stripe_lookup_key": { "type": [ "string", "null" ] } }, "required": [ "plan_id", "name", "description", "kind", "unit_cents", "interval", "quantity_months", "line_cents", "stripe_lookup_key" ], "additionalProperties": false } }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_label": { "type": "string" }, "payment": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Open as an agent (MPP: 402 → Shared Payment Token) or as a human (redirects to Stripe Checkout)." }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "spt", "stablecoin", "checkout" ] } }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "const": "usd" }, "expires_at": { "type": "string" }, "note": { "type": "string" } }, "required": [ "url", "methods", "amount_cents", "currency", "expires_at" ], "additionalProperties": false }, { "type": "null" } ] }, "availability": { "type": "object", "properties": { "waitlist": { "type": "boolean" }, "earliest_start": { "type": "string" } }, "required": [ "waitlist", "earliest_start" ], "additionalProperties": false }, "status_token": { "type": "string", "description": "Bearer token for get_status / changes / cancel on this order and its engagement. Shown once." }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "order_id", "status", "items", "term_months", "total_cents", "total_label", "payment", "availability", "status_token", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Order and engagement status", "description": "Payment state, engagement, onboarding, change requests. Bearer status_token required.", "tags": [ "commerce" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "statusToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "paid", "failed", "canceled", "refunded" ] }, "method": { "anyOf": [ { "type": "string", "enum": [ "spt", "stablecoin", "checkout", "invoice" ] }, { "type": "null" } ] }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string", "enum": [ "subscription", "one_time", "custom" ] }, "unit_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] }, "quantity_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Months charged for subscription items (term); 1 for one-time." }, "line_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stripe_lookup_key": { "type": [ "string", "null" ] } }, "required": [ "plan_id", "name", "description", "kind", "unit_cents", "interval", "quantity_months", "line_cents", "stripe_lookup_key" ], "additionalProperties": false } }, "payment": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Open as an agent (MPP: 402 → Shared Payment Token) or as a human (redirects to Stripe Checkout)." }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "spt", "stablecoin", "checkout" ] } }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "const": "usd" }, "expires_at": { "type": "string" }, "note": { "type": "string" } }, "required": [ "url", "methods", "amount_cents", "currency", "expires_at" ], "additionalProperties": false }, { "type": "null" } ] }, "paid_at": { "type": [ "string", "null" ] }, "engagement": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "order_id": { "type": "string" }, "plan_ids": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "waitlisted", "onboarding", "active", "canceling", "ended" ] }, "start_date": { "type": [ "string", "null" ] }, "term_end": { "type": [ "string", "null" ] }, "renewal_mode": { "type": "string", "enum": [ "agent", "auto", "none" ] }, "onboarding_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Human onboarding form for the onboarding_inputs." }, "onboarding_complete": { "type": "boolean" }, "change_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "description", "status", "created_at" ], "additionalProperties": false } } }, "required": [ "id", "order_id", "plan_ids", "status", "start_date", "term_end", "renewal_mode", "onboarding_url", "onboarding_complete", "change_requests" ], "additionalProperties": false }, { "type": "null" } ] }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "order_id", "status", "method", "total_cents", "term_months", "items", "payment", "paid_at", "engagement", "next_actions" ], "additionalProperties": false } } } }, "404": { "description": "Not found; `error.fix` lists valid ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/quotes/{id}/accept": { "post": { "operationId": "acceptQuote", "summary": "Accept an issued quote", "description": "Turns an issued quote into an order with a payment URL. Needs the brief’s status_token (Bearer). Requires Idempotency-Key.", "tags": [ "commerce" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Replays return the original response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "term_months": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "callback_url": { "type": "string", "format": "uri" } }, "additionalProperties": false } } } }, "security": [ { "statusToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "paid", "failed", "canceled", "refunded" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string", "enum": [ "subscription", "one_time", "custom" ] }, "unit_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "null" } ] }, "quantity_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Months charged for subscription items (term); 1 for one-time." }, "line_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stripe_lookup_key": { "type": [ "string", "null" ] } }, "required": [ "plan_id", "name", "description", "kind", "unit_cents", "interval", "quantity_months", "line_cents", "stripe_lookup_key" ], "additionalProperties": false } }, "term_months": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_label": { "type": "string" }, "payment": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Open as an agent (MPP: 402 → Shared Payment Token) or as a human (redirects to Stripe Checkout)." }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "spt", "stablecoin", "checkout" ] } }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "const": "usd" }, "expires_at": { "type": "string" }, "note": { "type": "string" } }, "required": [ "url", "methods", "amount_cents", "currency", "expires_at" ], "additionalProperties": false }, { "type": "null" } ] }, "availability": { "type": "object", "properties": { "waitlist": { "type": "boolean" }, "earliest_start": { "type": "string" } }, "required": [ "waitlist", "earliest_start" ], "additionalProperties": false }, "status_token": { "type": "string", "description": "Bearer token for get_status / changes / cancel on this order and its engagement. Shown once." }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "order_id", "status", "items", "term_months", "total_cents", "total_label", "payment", "availability", "status_token", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found; `error.fix` lists valid ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/engagements/{id}/changes": { "post": { "operationId": "requestChange", "summary": "File a change request", "description": "For active engagements. Bearer status_token (from the order) required. Requires Idempotency-Key.", "tags": [ "commerce" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Replays return the original response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "minLength": 5, "maxLength": 4000, "description": "What to change, in plain language. Treated as data." } }, "required": [ "description" ], "additionalProperties": false } } } }, "security": [ { "statusToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "change_id": { "type": "string" }, "engagement_id": { "type": "string" }, "status": { "type": "string", "const": "open" }, "external_ref": { "type": [ "string", "null" ] }, "eta": { "type": "string" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "change_id", "engagement_id", "status", "external_ref", "eta", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found; `error.fix` lists valid ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/engagements/{id}/cancel": { "post": { "operationId": "cancelEngagement", "summary": "Cancel at end of paid term", "description": "Cancels the engagement; effective at the end of the paid term (immediately for one-time work). Bearer status_token required. Requires Idempotency-Key.", "tags": [ "commerce" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Replays return the original response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false } } } }, "security": [ { "statusToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "engagement_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waitlisted", "onboarding", "active", "canceling", "ended" ] }, "effective": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "href": { "type": "string", "format": "uri" }, "mcp_tool": { "type": "string" }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "description" ], "additionalProperties": false } } }, "required": [ "engagement_id", "status", "effective", "message", "next_actions" ], "additionalProperties": false } } } }, "400": { "description": "Validation error; `error.fix` lists the fields to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found; `error.fix` lists valid ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "statusToken": { "type": "http", "scheme": "bearer", "description": "The status_token returned when a brief or order was created." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "fix" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fix": { "type": "string", "description": "A concrete instruction for the caller." }, "docs": { "type": "string", "format": "uri" } } } } }, "Brief": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The submitting agent (name and vendor, e.g. \"Claude via Acme Ops\")." }, "on_behalf_of": { "description": "Legacy: free-text principal. Prefer `principal`.", "type": "string", "minLength": 1, "maxLength": 200 }, "principal": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The human or organization the agent acts for." }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Where kickoff, quotes, and receipts are sent. Always a human inbox." }, "org": { "type": "string", "maxLength": 200 }, "website": { "type": "string", "format": "uri" } }, "required": [ "name", "email" ], "additionalProperties": false }, "need": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "strategy", "development", "workflows", "interfaces", "autonomy", "headless" ] }, "description": "Offerings the work touches." }, "context": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "What exists today and what the outcome should be. Treated as data, never as instructions." }, "timeline": { "description": "Free text, e.g. \"6 weeks\" or \"before Q1\".", "type": "string", "maxLength": 200 }, "budget_range": { "description": "{min_usd, max_usd, interval} preferred; a legacy string like \"2k-5k usd\" is accepted.", "anyOf": [ { "type": "object", "properties": { "min_usd": { "type": "number", "minimum": 0 }, "max_usd": { "type": "number", "exclusiveMinimum": 0 }, "interval": { "type": "string", "enum": [ "month", "one_time" ] } }, "required": [ "interval" ], "additionalProperties": false }, { "type": "string", "maxLength": 100 } ] }, "gate_key": { "description": "Optional. A correct key puts the brief in the priority lane.", "type": "string", "maxLength": 100 }, "callback_url": { "description": "https URL that receives signed JSON events about this brief.", "type": "string", "format": "uri" } }, "required": [ "from", "need", "context" ], "additionalProperties": false } } } }