{ "openapi": "3.1.0", "info": { "title": "WorldHinge Request API", "version": "0.2.1", "description": "Physical-world request intake and saved conversations, reviewed by Ryan O’Shea, Future Grind, LLC. Replies are retrieved asynchronously. Scope, timing and any price are agreed separately.", "contact": { "name": "Ryan O’Shea, Future Grind, LLC", "email": "ryan@futuregrind.org" } }, "servers": [ { "url": "/" } ], "components": { "securitySchemes": { "RequestToken": { "type": "http", "scheme": "bearer", "description": "The token for this individual request, never a founder/deployment credential." } }, "schemas": { "Intake": { "type": "object", "additionalProperties": false, "properties": { "need": { "type": "string", "minLength": 10, "maxLength": 4000 }, "requester_type": { "enum": [ "human", "agent", "unknown" ], "default": "unknown" }, "channel": { "enum": [ "api", "web_form", "web_chat" ], "default": "api" }, "category": { "enum": [ "observation", "installation_check", "measurement", "spatial_capture", "field_task", "research_dataset", "other" ], "default": "other" }, "location": { "type": "string", "minLength": 0, "maxLength": 300 }, "deliverable": { "type": "string", "minLength": 0, "maxLength": 1000 }, "deadline": { "type": "string", "minLength": 0, "maxLength": 200 }, "authorization": { "type": "string", "minLength": 0, "maxLength": 1000 }, "already_tried": { "type": "string", "minLength": 0, "maxLength": 1000 }, "acceptance_criteria": { "type": "array", "maxItems": 6, "items": { "type": "string", "minLength": 1, "maxLength": 300 } }, "principal": { "type": "string", "minLength": 0, "maxLength": 200 }, "reply_contact": { "type": "string", "minLength": 0, "maxLength": 254, "description": "Optional contact details for the operator. Replies are posted in the saved conversation; automatic email notifications are not implemented." }, "consent": { "const": true }, "allow_aggregate": { "type": "boolean", "default": false, "description": "Optional inclusion in private category-count exports. The website form does not opt in. See the privacy notice." }, "simulation": { "type": "boolean", "default": false }, "website": { "const": "", "default": "" }, "budget": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000, "default": null }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "USD" }, "authority": { "enum": [ "unknown", "asserted" ], "default": "unknown" } }, "required": [] } }, "required": [ "need", "consent" ] }, "Message": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer" }, "role": { "enum": [ "user", "assistant" ] }, "content": { "type": "string", "minLength": 0, "maxLength": 4000 }, "source": { "enum": [ "requester", "receipt", "founder" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "role", "content", "source", "created_at" ] }, "Request": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^ww_[a-f0-9]{32}$" }, "status": { "enum": [ "new", "clarifying", "researching", "candidate_solution", "needs_human_review", "declined", "closed" ] }, "category": { "enum": [ "observation", "installation_check", "measurement", "spatial_capture", "field_task", "research_dataset", "other" ] }, "evidence": { "enum": [ "simulation", "unverified_external", "credible_request", "verified_buyer", "repeat_buyer" ] }, "summary": { "type": "string", "minLength": 0, "maxLength": 600 }, "feasibility": { "const": "requires_human_review" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "turns": { "type": "integer", "minimum": 1, "maximum": 12 }, "payload": { "$ref": "#/components/schemas/Intake" }, "assessment": { "type": "null" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "remaining_turns": { "type": "integer", "minimum": 0 }, "fulfillment_confirmed": { "const": false } }, "required": [ "id", "status", "payload", "messages", "expires_at", "remaining_turns" ] }, "CreatedRequest": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^ww_[a-f0-9]{32}$" }, "status": { "enum": [ "new", "clarifying", "researching", "candidate_solution", "needs_human_review", "declined", "closed" ] }, "category": { "enum": [ "observation", "installation_check", "measurement", "spatial_capture", "field_task", "research_dataset", "other" ] }, "evidence": { "enum": [ "simulation", "unverified_external", "credible_request", "verified_buyer", "repeat_buyer" ] }, "summary": { "type": "string", "minLength": 0, "maxLength": 600 }, "feasibility": { "const": "requires_human_review" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "turns": { "type": "integer", "minimum": 1, "maximum": 12 }, "payload": { "$ref": "#/components/schemas/Intake" }, "assessment": { "type": "null" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "remaining_turns": { "type": "integer", "minimum": 0 }, "fulfillment_confirmed": { "const": false }, "access_token": { "type": "string", "description": "Private bearer credential; save securely." }, "replayed": { "type": "boolean" } }, "required": [ "id", "status", "payload", "messages", "expires_at", "remaining_turns", "access_token", "replayed" ] }, "MessageResult": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^ww_[a-f0-9]{32}$" }, "status": { "enum": [ "new", "clarifying", "researching", "candidate_solution", "needs_human_review", "declined", "closed" ] }, "category": { "enum": [ "observation", "installation_check", "measurement", "spatial_capture", "field_task", "research_dataset", "other" ] }, "evidence": { "enum": [ "simulation", "unverified_external", "credible_request", "verified_buyer", "repeat_buyer" ] }, "summary": { "type": "string", "minLength": 0, "maxLength": 600 }, "feasibility": { "const": "requires_human_review" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "turns": { "type": "integer", "minimum": 1, "maximum": 12 }, "payload": { "$ref": "#/components/schemas/Intake" }, "assessment": { "type": "null" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "remaining_turns": { "type": "integer", "minimum": 0 }, "fulfillment_confirmed": { "const": false }, "replayed": { "type": "boolean" } }, "required": [ "id", "status", "payload", "messages", "expires_at", "remaining_turns", "replayed" ] }, "MessageInput": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "content" ] } } }, "paths": { "/api/capabilities": { "get": { "description": "Current service capabilities, communication model and capacity handling.", "responses": { "200": { "description": "Saved response; no physical fulfillment is confirmed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "403": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "404": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "408": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "409": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "410": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "413": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "415": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "429": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "503": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } } } } }, "/api/requests": { "post": { "description": "Create a saved request for human review. No account required. Creation keys recover the original credential until rotation or expiry.", "responses": { "201": { "description": "Saved response; no physical fulfillment is confirmed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedRequest" } } } }, "401": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "403": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "404": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "408": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "409": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "410": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "413": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "415": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "429": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "503": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "description": "Secret random key. Reuse only for retrying the same operation and identical JSON.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intake" } } } } } }, "/api/requests/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^ww_[a-f0-9]{32}$" } } ], "get": { "description": "Read this private request.", "responses": { "200": { "description": "Saved response; no physical fulfillment is confirmed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "401": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "403": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "404": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "408": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "409": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "410": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "413": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "415": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "429": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "503": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } } }, "security": [ { "RequestToken": [] } ] }, "delete": { "description": "Delete active request and linked content. Provider recovery history may persist up to 30 days.", "responses": { "200": { "description": "Saved response; no physical fulfillment is confirmed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "deleted": { "const": true }, "note": { "type": "string" } }, "required": [] } } } }, "401": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "403": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "404": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "408": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "409": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "410": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "413": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "415": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "429": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "503": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } } }, "security": [ { "RequestToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } }, "/api/requests/{id}/messages": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^ww_[a-f0-9]{32}$" } } ], "get": { "description": "Read this private conversation.", "responses": { "200": { "description": "Saved response; no physical fulfillment is confirmed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "required": [ "messages" ] } } } }, "401": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "403": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "404": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "408": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "409": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "410": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "413": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "415": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "429": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "503": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } } }, "security": [ { "RequestToken": [] } ] }, "post": { "description": "Save a follow-up for human review. No model call or automatic email.", "responses": { "200": { "description": "Saved response; no physical fulfillment is confirmed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResult" } } } }, "401": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "403": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "404": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "408": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "409": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "410": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "413": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "415": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "429": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "503": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } } }, "security": [ { "RequestToken": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "description": "Secret random key. Reuse only for retrying the same operation and identical JSON.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } } } }, "/api/requests/{id}/rotate-token": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^ww_[a-f0-9]{32}$" } } ], "post": { "description": "Immediately revoke the old token. Save the returned new token; this operation is not automatically retryable.", "responses": { "200": { "description": "Saved response; no physical fulfillment is confirmed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "access_token": { "type": "string" } }, "required": [ "id", "access_token" ] } } } }, "401": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "403": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "404": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "408": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "409": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "410": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "413": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "415": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "429": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } }, "503": { "description": "Validation, credential, capacity, or availability error. Use Retry-After when supplied. HTTP 429 distinguishes capacity_full (service capacity) from rate_limited (client rate limit) when code is present.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "capacity_full", "rate_limited" ] } }, "required": [ "detail" ] } } } } }, "security": [ { "RequestToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } } } }