{ "openapi": "3.1.0", "info": { "title": "WOVI API", "version": "1.0.0", "description": "Run WOVI's agents and pipelines from your own software. The same engine as the app: typed inputs, your Brand Brain, the quality gate, credits held and charged the same way.\n\nAuthenticate with an API key from Settings, API: `Authorization: Bearer wovi_sk_...`. A key works in one workspace with one role. Keys never approve or reject results, top up credits or change limits.\n\nNo key? The two start endpoints also take x402: call without Authorization, get a 402 with the price, pay on Robinhood Chain, send the call again with X-PAYMENT. See GET /x402. MCP stays on API keys.\n\nErrors: `unauthenticated` (401), `forbidden` (403), `not_found` (404), `invalid_input` (422), `invalid_request` (400), `not_enough_credits` (402), `over_limit` (402), `idempotency_conflict` (409), `not_ready` (409), `rate_limited` (429), `payload_too_large` (413), `method_not_allowed` (405), `internal_error` (500), `content_blocked` (422)." }, "servers": [ { "url": "https://wovi-production.up.railway.app/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Key" }, { "name": "Agents" }, { "name": "Runs" }, { "name": "Pipelines" }, { "name": "Brand Brains" }, { "name": "Credits" }, { "name": "Webhooks" }, { "name": "x402" } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Key" ], "summary": "The key's workspace, role and limits", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agents": { "get": { "operationId": "listAgents", "tags": [ "Agents" ], "summary": "List the agents you can run", "description": "Each agent's name, job, form (with JSON Schema), output shape, quality scorecard and about what one run costs. Never its instructions or models.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agents/{id}": { "get": { "operationId": "getAgent", "tags": [ "Agents" ], "summary": "One agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agents/{id}/runs": { "post": { "operationId": "startRun", "tags": [ "Runs" ], "summary": "Start a run", "description": "Checks the inputs against the agent's form, picks the Brand Brain (the one named, else the workspace default), holds the estimate in credits and queues the run. Answers at once with the run; poll GET /runs/{id} or listen for run.finished. Send an Idempotency-Key so a retried request never starts a second run. No key? Pay per call with x402: call it without Authorization to get a 402 with the price, pay, then send it again with X-PAYMENT. See /x402.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any 1 to 100 letters, digits, _ . : or -. The same key with the same body returns the first run; with a different body, idempotency_conflict.", "schema": { "type": "string", "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartRunBody" } } } }, "responses": { "202": { "description": "Accepted. The run is queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "headers": { "X-PAYMENT-RESPONSE": { "description": "Paid with x402 only: base64 JSON of SettleResponse.", "schema": { "type": "string" } }, "X-Receipt-Token": { "description": "Paid with x402 only: reads this run at /x402/runs/{id} or /x402/pipeline-runs/{id} as Authorization: Bearer wovi_rt_...", "schema": { "type": "string" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits (with a key, the Error shape), or, with no key and x402 on: payment required (the PaymentRequired shape). Pay one of `accepts`, then send the same request again with X-PAYMENT: base64 JSON of PaymentPayload.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PaymentRequired" } ] } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "That Idempotency-Key was already used for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some fields need a look. Each issue has the field's path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, {} ], "x-x402": { "version": 1, "scheme": "tx-hash", "network": "eip155:4663", "price": "The call's estimate in credits, one credit = $0.01, quoted in the asset when the 402 is made. Never charged more.", "paymentHeader": "X-PAYMENT", "responseHeader": "X-PAYMENT-RESPONSE", "discovery": "/api/v1/x402" } } }, "/runs": { "get": { "operationId": "listRuns", "tags": [ "Runs" ], "summary": "List runs, newest first", "description": "Runs started in this workspace, from the app or the API. Runs a pipeline made are inside their pipeline run.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many, 1 to 100. Default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "description": "queued, running, succeeded, failed or cancelled.", "schema": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] } }, { "name": "agent", "in": "query", "required": false, "description": "Only this agent's runs.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRunsResponse" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/runs/{id}": { "get": { "operationId": "getRun", "tags": [ "Runs" ], "summary": "One run: status, output, quality and charge", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/runs/{id}/cancel": { "post": { "operationId": "cancelRun", "tags": [ "Runs" ], "summary": "Stop a run", "description": "Stops a queued or running run and gives its credits back. A finished run is returned as it is.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/runs/{id}/feedback": { "post": { "operationId": "giveRunFeedback", "tags": [ "Runs" ], "summary": "Say what happened to a result: used, edited, run again or rated", "description": "Feeds the agent's live stats (acceptance, edit rate, regenerate rate, rating). One of each action per run: a use or a regenerate counts once, an edit or a rating sent again replaces the first. Finished runs only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackBody" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some fields need a look. Each issue has the field's path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pipelines": { "get": { "operationId": "listPipelines", "tags": [ "Pipelines" ], "summary": "List the pipelines you can start", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPipelinesResponse" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pipelines/{id}/runs": { "post": { "operationId": "startPipeline", "tags": [ "Pipelines" ], "summary": "Start a pipeline run", "description": "Holds one estimate for the whole chain and starts the first step. When a step asks a person to pick, the run waits with status waiting; answer with POST /pipeline-runs/{id}/pick. No key? Pay per call with x402: call it without Authorization to get a 402 with the price, pay, then send it again with X-PAYMENT. See /x402.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any 1 to 100 letters, digits, _ . : or -. The same key with the same body returns the first run; with a different body, idempotency_conflict.", "schema": { "type": "string", "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPipelineBody" } } } }, "responses": { "202": { "description": "Accepted. The run is queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRun" } } }, "headers": { "X-PAYMENT-RESPONSE": { "description": "Paid with x402 only: base64 JSON of SettleResponse.", "schema": { "type": "string" } }, "X-Receipt-Token": { "description": "Paid with x402 only: reads this run at /x402/runs/{id} or /x402/pipeline-runs/{id} as Authorization: Bearer wovi_rt_...", "schema": { "type": "string" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits (with a key, the Error shape), or, with no key and x402 on: payment required (the PaymentRequired shape). Pay one of `accepts`, then send the same request again with X-PAYMENT: base64 JSON of PaymentPayload.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PaymentRequired" } ] } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "That Idempotency-Key was already used for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some fields need a look. Each issue has the field's path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, {} ], "x-x402": { "version": 1, "scheme": "tx-hash", "network": "eip155:4663", "price": "The call's estimate in credits, one credit = $0.01, quoted in the asset when the 402 is made. Never charged more.", "paymentHeader": "X-PAYMENT", "responseHeader": "X-PAYMENT-RESPONSE", "discovery": "/api/v1/x402" } } }, "/pipeline-runs": { "get": { "operationId": "listPipelineRuns", "tags": [ "Pipelines" ], "summary": "List pipeline runs, newest first", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many, 1 to 100. Default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "pipeline", "in": "query", "required": false, "description": "Only this pipeline's runs.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPipelineRunsResponse" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pipeline-runs/{id}": { "get": { "operationId": "getPipelineRun", "tags": [ "Pipelines" ], "summary": "One pipeline run: every step, what waits, the package", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRun" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pipeline-runs/{id}/pick": { "post": { "operationId": "pickOption", "tags": [ "Pipelines" ], "summary": "Pick an option where a step waits", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickBody" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRun" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some fields need a look. Each issue has the field's path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pipeline-runs/{id}/cancel": { "post": { "operationId": "cancelPipelineRun", "tags": [ "Pipelines" ], "summary": "Stop a pipeline run", "description": "Stops a running or waiting pipeline run. What the finished steps did not use comes back.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRun" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brand-brains": { "get": { "operationId": "listBrandBrains", "tags": [ "Brand Brains" ], "summary": "List the workspace's Brand Brains", "description": "Read only. Pass an id as brandBrainId when you start a run.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBrandBrainsResponse" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credits": { "get": { "operationId": "getCredits", "tags": [ "Credits" ], "summary": "The credit balance", "description": "Read only. Keys never top up or change limits.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credits" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Admin keys only.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Register a webhook", "description": "Admin keys only. The answer carries the signing secret once. Deliveries are signed in Wovi-Signature (t=,v1=) and tried again with backoff: after 10 s, 1 min, 5 min, 30 min and 2 h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookBody" } } } }, "responses": { "201": { "description": "Made.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Some fields need a look. Each issue has the field's path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "get": { "operationId": "getWebhook", "tags": [ "Webhooks" ], "summary": "One webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Remove a webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookResponse" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "listDeliveries", "tags": [ "Webhooks" ], "summary": "The delivery log, newest first", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many, 1 to 100. Default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeliveriesResponse" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Send a test delivery now", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } } }, "401": { "description": "No API key, or a key that is revoked or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key is real but its role may not do this. Approving, rejecting, topping up and changing limits are never for keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing with that id in the key's workspace. Other workspaces always answer this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait the seconds in Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x402": { "get": { "operationId": "x402Discovery", "tags": [ "x402" ], "summary": "Which endpoints take x402, and the prices", "description": "No key. Whether x402 is on, the network, the receiving address, the assets, and every agent and pipeline with its price in credits and USD. Also at /.well-known/x402.", "security": [], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Discovery" } } } } } } }, "/x402/runs/{id}": { "get": { "operationId": "x402GetRun", "tags": [ "x402" ], "summary": "A paid run, with its receipt", "description": "Authorization: Bearer wovi_rt_... from X-Receipt-Token. The run, and the payment with what was charged and anything owed back.", "security": [ { "receipt": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402RunResult" } } } }, "401": { "description": "No receipt token, or one that ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Another run, or nothing with that id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x402/runs/{id}/cancel": { "post": { "operationId": "x402CancelRun", "tags": [ "x402" ], "summary": "Stop a paid run", "description": "Stops it. What it did not use is owed back to the payer.", "security": [ { "receipt": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402RunResult" } } } }, "401": { "description": "No receipt token, or one that ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Another run, or nothing with that id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x402/pipeline-runs/{id}": { "get": { "operationId": "x402GetPipelineRun", "tags": [ "x402" ], "summary": "A paid pipeline run, with its receipt", "description": "Every step, what waits, the package, and the payment.", "security": [ { "receipt": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PipelineRunResult" } } } }, "401": { "description": "No receipt token, or one that ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Another run, or nothing with that id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x402/pipeline-runs/{id}/pick": { "post": { "operationId": "x402PickOption", "tags": [ "x402" ], "summary": "Pick where a paid pipeline run waits", "description": "The same as POST /pipeline-runs/{id}/pick, with the receipt token.", "security": [ { "receipt": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PipelineRunResult" } } } }, "401": { "description": "No receipt token, or one that ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Another run, or nothing with that id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickBody" } } } } } }, "/x402/pipeline-runs/{id}/cancel": { "post": { "operationId": "x402CancelPipelineRun", "tags": [ "x402" ], "summary": "Stop a paid pipeline run", "description": "What the finished steps did not use is owed back.", "security": [ { "receipt": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PipelineRunResult" } } } }, "401": { "description": "No receipt token, or one that ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Another run, or nothing with that id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "run.finished": { "post": { "summary": "A run finished: it succeeded, failed or was stopped. data.run is the run.", "parameters": [ { "name": "Wovi-Signature", "in": "header", "required": true, "description": "t=,v1=. Refuse it when t is more than 5 minutes off.", "schema": { "type": "string" } }, { "name": "Wovi-Event", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Wovi-Delivery", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered. Anything else is tried again with backoff." } } } }, "pipeline.waiting": { "post": { "summary": "A pipeline step waits for a person to pick. data.pipelineRun.waiting has the options.", "parameters": [ { "name": "Wovi-Signature", "in": "header", "required": true, "description": "t=,v1=. Refuse it when t is more than 5 minutes off.", "schema": { "type": "string" } }, { "name": "Wovi-Event", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Wovi-Delivery", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered. Anything else is tried again with backoff." } } } }, "pipeline.finished": { "post": { "summary": "A pipeline is ready for approval, failed or was stopped. data.pipelineRun is the run.", "parameters": [ { "name": "Wovi-Signature", "in": "header", "required": true, "description": "t=,v1=. Refuse it when t is more than 5 minutes off.", "schema": { "type": "string" } }, { "name": "Wovi-Event", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Wovi-Delivery", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx counts as delivered. Anything else is tried again with backoff." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "wovi_sk_...", "description": "An API key from Settings, API." }, "receipt": { "type": "http", "scheme": "bearer", "bearerFormat": "wovi_rt_...", "description": "A receipt token from a run paid with x402 (X-Receipt-Token). Reads that one run." } }, "schemas": { "Agent": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" }, "job": { "type": "string" }, "category": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/InputField" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The inputs as JSON Schema." }, "output": { "$ref": "#/components/schemas/OutputShape" }, "brandBrainParts": { "type": "array", "items": { "type": "string" }, "description": "The parts of the Brand Brain it reads." }, "confirmations": { "type": "object", "properties": { "rights": { "type": "boolean" }, "voiceConsent": { "type": "boolean" } }, "required": [ "rights", "voiceConsent" ], "additionalProperties": false, "description": "Confirmations it needs before it runs." }, "quality": { "type": "object", "properties": { "bar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The score a result needs to be ready, 0 to 100." }, "scorecard": { "$ref": "#/components/schemas/Scorecard" } }, "required": [ "bar", "scorecard" ], "additionalProperties": false }, "estimate": { "type": "object", "properties": { "credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "About what one run costs, in credits. It never costs more." } }, "required": [ "credits" ], "additionalProperties": false } }, "required": [ "id", "version", "name", "job", "category", "platforms", "inputs", "inputSchema", "output", "brandBrainParts", "confirmations", "quality", "estimate" ], "additionalProperties": false, "description": "An agent you can run. Never its instructions or models." }, "InputField": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "long_text", "url", "file", "image", "video", "choice", "number", "profile" ] }, "required": { "type": "boolean" }, "help": { "type": "string" }, "limits": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "multiple": { "type": "boolean" }, "default": {} }, "required": [ "key", "label", "type", "required" ], "additionalProperties": false, "description": "One field of an agent's or pipeline's form." }, "OutputShape": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "list", "script", "caption_set", "post_set", "image", "storyboard", "video" ] } }, "required": [ "kind" ], "additionalProperties": {}, "description": "What one run returns: the kind and its limits." }, "Scorecard": { "type": "object", "properties": { "runs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "passRate": { "description": "Share of runs that passed the quality bar, 0 to 1.", "type": [ "number", "null" ] }, "averageScore": { "type": [ "number", "null" ] }, "approvalRate": { "type": [ "number", "null" ] }, "changesAskedRate": { "type": [ "number", "null" ] }, "isNew": { "type": "boolean", "description": "Fewer than 5 runs so far." }, "summary": { "type": "string" } }, "required": [ "runs", "passRate", "averageScore", "approvalRate", "changesAskedRate", "isNew", "summary" ], "additionalProperties": false }, "Run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "agent": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "version", "name" ], "additionalProperties": false }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "brandBrain": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "output": { "anyOf": [ { "$ref": "#/components/schemas/RunOutput" }, { "type": "null" } ] }, "ready": { "type": "boolean", "description": "Succeeded, passed the quality bar and every check." }, "needsReview": { "type": "boolean" }, "quality": { "anyOf": [ { "$ref": "#/components/schemas/Quality" }, { "type": "null" } ] }, "flags": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "string" }, "message": { "type": "string" }, "findings": { "type": "array", "items": { "type": "string" } } }, "required": [ "check", "message", "findings" ], "additionalProperties": false }, "description": "Checks that failed." }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "charge": { "anyOf": [ { "$ref": "#/components/schemas/Charge" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/Decision" }, { "type": "null" } ], "description": "A person's decision on it. Keys cannot decide." }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "aiGenerated": { "type": "boolean", "const": true, "description": "Always true: an AI model wrote the output (EU AI Act Art. 50). Label it where a platform asks." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "published": { "type": [ "string", "null" ] }, "searchedAt": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "published", "searchedAt" ], "additionalProperties": false }, "description": "The web pages the agent's trend lookup found, with their dates and when the search ran. Empty for agents without a lookup." } }, "required": [ "id", "status", "agent", "inputs", "brandBrain", "output", "ready", "needsReview", "quality", "flags", "error", "charge", "decision", "createdAt", "finishedAt", "aiGenerated", "sources" ], "additionalProperties": false, "description": "One run of one agent." }, "RunOutput": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "list", "script", "caption_set", "post_set" ] } }, "required": [ "kind" ], "additionalProperties": {}, "description": "The result in its typed shape: text {text}, list {items}, script {sections}, caption_set {captions}, post_set {posts}." }, "Quality": { "type": "object", "properties": { "score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "verdict": { "type": "string", "enum": [ "ready", "needs_review" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "rewrites": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "weak", "fail", "skipped" ] }, "score": { "type": [ "number", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "status", "score", "reasons" ], "additionalProperties": false } } }, "required": [ "score", "bar", "verdict", "reasons", "rewrites", "checks" ], "additionalProperties": false }, "Charge": { "type": "object", "properties": { "estimate": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "charged": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "back": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "state": { "type": "string" } }, "required": [ "estimate", "charged", "back", "state" ], "additionalProperties": false, "description": "Credits held and charged. Only for keys that may see costs (admin keys); null otherwise." }, "Decision": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "note": { "type": "string" }, "at": { "type": "string" } }, "required": [ "decision", "note", "at" ], "additionalProperties": false }, "Pipeline": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" }, "job": { "type": "string" }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/InputField" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "label", "agent" ], "additionalProperties": false } }, "confirmations": { "type": "object", "properties": { "rights": { "type": "boolean" }, "voiceConsent": { "type": "boolean" } }, "required": [ "rights", "voiceConsent" ], "additionalProperties": false }, "estimate": { "type": "object", "properties": { "credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "credits" ], "additionalProperties": false } }, "required": [ "id", "version", "name", "job", "inputs", "inputSchema", "steps", "confirmations", "estimate" ], "additionalProperties": false, "description": "A saved chain of agents." }, "PipelineRun": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "waiting", "ready", "approved", "rejected", "failed", "cancelled" ] }, "pipeline": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "version", "name" ], "additionalProperties": false }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "brandBrain": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "needsReview": { "type": "boolean" }, "waiting": { "anyOf": [ { "type": "object", "properties": { "step": { "type": "string" }, "label": { "type": "string" }, "prompt": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Option" } }, "suggested": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "step", "label", "prompt", "options", "suggested" ], "additionalProperties": false }, { "type": "null" } ], "description": "Set while a step waits for a pick. Answer with POST /pipeline-runs/{id}/pick." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "version", "name" ], "additionalProperties": false }, "output": { "anyOf": [ { "$ref": "#/components/schemas/RunOutput" }, { "type": "null" } ] }, "picked": { "anyOf": [ { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "by": { "type": "string" } }, "required": [ "index", "by" ], "additionalProperties": false }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "object", "properties": { "score": { "type": "number" }, "bar": { "type": "number" }, "verdict": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "score", "bar", "verdict", "reasons" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "label", "status", "agent", "output", "picked", "quality", "error" ], "additionalProperties": false } }, "package": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "string" }, "label": { "type": "string" }, "item": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "text": { "type": "string" }, "fields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "brandFit": { "type": [ "number", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } }, "required": [ "label", "text", "fields", "brandFit", "flags" ], "additionalProperties": false }, { "type": "null" } ] }, "output": { "anyOf": [ { "$ref": "#/components/schemas/RunOutput" }, { "type": "null" } ] }, "brandFit": { "type": [ "number", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } }, "required": [ "step", "label", "item", "output", "brandFit", "flags" ], "additionalProperties": false } }, { "type": "null" } ], "description": "What a person approves at the end." }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/Decision" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "step": { "type": [ "string", "null" ] } }, "required": [ "code", "message", "step" ], "additionalProperties": false }, { "type": "null" } ] }, "charge": { "anyOf": [ { "$ref": "#/components/schemas/Charge" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "pipeline", "inputs", "brandBrain", "needsReview", "waiting", "steps", "package", "decision", "error", "charge", "createdAt", "finishedAt" ], "additionalProperties": false, "description": "One run of a pipeline." }, "Option": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string" }, "text": { "type": "string" }, "fields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "brandFit": { "type": [ "number", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } }, "required": [ "index", "label", "text", "fields", "brandFit", "flags" ], "additionalProperties": false }, "BrandBrain": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "niche": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "voice": { "type": "string" }, "tone": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "isDefault", "niche", "platforms", "voice", "tone", "updatedAt" ], "additionalProperties": false, "description": "A brand or client the agents write for. Read only through the API." }, "Credits": { "type": "object", "properties": { "available": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "held": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Held for runs in progress." }, "usedThisMonth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Used this month by the person who made the key." }, "monthlyLimit": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "That person's monthly limit, if one is set." }, "creditUsd": { "type": "number", "description": "What one credit is worth in US dollars." } }, "required": [ "available", "held", "usedThisMonth", "monthlyLimit", "creditUsd" ], "additionalProperties": false, "description": "The workspace's balance. Read only: keys never top up or change limits." }, "Me": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "editor", "viewer" ] } }, "required": [ "id", "role" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "workspaceRequestsPerMinute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "startsPerMinute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maxBodyBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "requestsPerMinute", "workspaceRequestsPerMinute", "startsPerMinute", "maxBodyBytes" ], "additionalProperties": false } }, "required": [ "workspace", "key", "limits" ], "additionalProperties": false }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "run.finished", "pipeline.waiting", "pipeline.finished" ] } }, "description": { "type": "string" }, "secretHint": { "type": "string" }, "paused": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "events", "description", "secretHint", "paused", "createdAt" ], "additionalProperties": false }, "WebhookCreated": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "run.finished", "pipeline.waiting", "pipeline.finished" ] } }, "description": { "type": "string" }, "secretHint": { "type": "string" }, "paused": { "type": "boolean" }, "createdAt": { "type": "string" }, "secret": { "type": "string", "description": "The signing secret. Shown once; keep it safe." } }, "required": [ "id", "url", "events", "description", "secretHint", "paused", "createdAt", "secret" ], "additionalProperties": false }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "type": { "type": "string", "enum": [ "run.finished", "pipeline.waiting", "pipeline.finished", "ping" ] }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "at": { "type": "string" }, "status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ms": { "type": "number" }, "error": { "type": "string" }, "sender": { "type": "string" } }, "required": [ "n", "at", "status", "ms", "sender" ], "additionalProperties": false } }, "nextAttemptAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "eventId", "type", "status", "attempts", "nextAttemptAt", "createdAt" ], "additionalProperties": false }, "WebhookPayload": { "type": "object", "properties": { "id": { "type": "string", "description": "The event id. The same event never comes twice to one URL, but a retry repeats it; dedupe on it." }, "type": { "type": "string", "enum": [ "run.finished", "pipeline.waiting", "pipeline.finished", "ping" ] }, "createdAt": { "type": "string" }, "workspaceId": { "type": "string" }, "data": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" }, "pipelineRun": { "$ref": "#/components/schemas/PipelineRun" }, "message": { "type": "string" } }, "additionalProperties": false } }, "required": [ "id", "type", "createdAt", "workspaceId", "data" ], "additionalProperties": false, "description": "The body of every webhook delivery. Signed in the Wovi-Signature header." }, "Confirmations": { "type": "object", "properties": { "rights": { "description": "You own the material or have the right to use it. Agents that rework posts ask for it.", "type": "boolean" }, "voiceConsent": { "description": "You have the person's consent to use their voice.", "type": "boolean" } }, "additionalProperties": false, "description": "Confirmations some agents ask for before they run." }, "StartRunBody": { "type": "object", "properties": { "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The agent's form values by input key. See the agent's inputSchema." }, "brandBrainId": { "description": "The Brand Brain to write for. Leave it out to use the workspace's default.", "type": "string", "minLength": 1, "maxLength": 100 }, "idea": { "description": "An idea for this run only. It steers agents that read the Brand Brain's idea.", "type": "string", "maxLength": 1000 }, "confirmations": { "$ref": "#/components/schemas/Confirmations" }, "maxCredits": { "description": "The most this run may hold, in credits. The run never costs more than this or its estimate.", "type": "integer", "minimum": 1, "maximum": 1000000 } }, "required": [ "inputs" ], "additionalProperties": false, "description": "Starts a run of one agent." }, "StartPipelineBody": { "type": "object", "properties": { "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The pipeline's form values by input key. See the pipeline's inputSchema." }, "brandBrainId": { "description": "The Brand Brain every step writes for. Leave it out to use the workspace's default.", "type": "string", "minLength": 1, "maxLength": 100 }, "confirmations": { "$ref": "#/components/schemas/Confirmations" }, "maxCredits": { "description": "The most the whole pipeline may hold, in credits.", "type": "integer", "minimum": 1, "maximum": 1000000 } }, "required": [ "inputs" ], "additionalProperties": false, "description": "Starts a pipeline run." }, "PickBody": { "type": "object", "properties": { "step": { "description": "The step that waits. Leave it out to answer whichever step waits now.", "type": "string", "minLength": 1, "maxLength": 40 }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The option to pick, counting from 0, as listed in waiting.options." } }, "required": [ "index" ], "additionalProperties": false, "description": "Answers a pipeline step that waits for a person to pick." }, "FeedbackBody": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "use", "edit", "regenerate", "rating" ], "description": "use: the result was used as it is. edit: the person changed it (send the whole kept text). regenerate: they asked for another try. rating: thumbs up or down." }, "text": { "description": "For edit: the whole text the person kept. Only the size of the change is counted unless the person allowed WOVI to learn from their edits.", "type": "string", "minLength": 1, "maxLength": 20000 }, "rating": { "description": "For rating.", "type": "string", "enum": [ "up", "down" ] }, "note": { "description": "For rating: a short note.", "type": "string", "maxLength": 300 } }, "required": [ "action" ], "additionalProperties": false, "description": "What a person did with a result. One of each per run: a use or a regenerate is counted once, an edit or a rating sent again replaces the first." }, "Feedback": { "type": "object", "properties": { "used": { "type": "boolean" }, "edited": { "anyOf": [ { "type": "object", "properties": { "distance": { "type": "number", "minimum": 0, "maximum": 1 }, "at": { "type": "string" } }, "required": [ "distance", "at" ], "additionalProperties": false }, { "type": "null" } ], "description": "The share of the result that was changed, 0 to 1." }, "regenerated": { "type": "boolean" }, "rating": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ] }, "note": { "type": [ "string", "null" ] } }, "required": [ "used", "edited", "regenerated", "rating", "note" ], "additionalProperties": false, "description": "What has been recorded for this run." }, "CreateWebhookBody": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Where to POST. https:// only; http://localhost works while the app runs on your machine." }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "run.finished", "pipeline.waiting", "pipeline.finished" ] }, "description": "Which events to send." }, "description": { "type": "string", "maxLength": 120 } }, "required": [ "url", "events" ], "additionalProperties": false, "description": "Registers a URL for webhook events." }, "Issue": { "type": "object", "properties": { "path": { "type": "string", "description": "The field, like \"inputs.idea\"." }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthenticated", "forbidden", "not_found", "invalid_input", "invalid_request", "not_enough_credits", "over_limit", "idempotency_conflict", "not_ready", "rate_limited", "payload_too_large", "method_not_allowed", "internal_error", "content_blocked" ] }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "retryAfter": { "description": "For rate_limited: seconds to wait.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "description": "Every error has this shape." }, "ListAgentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } }, "required": [ "data" ], "additionalProperties": false }, "ListRunsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } }, "required": [ "data" ], "additionalProperties": false }, "ListPipelinesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } } }, "required": [ "data" ], "additionalProperties": false }, "ListPipelineRunsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineRun" } } }, "required": [ "data" ], "additionalProperties": false }, "ListBrandBrainsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BrandBrain" } } }, "required": [ "data" ], "additionalProperties": false }, "ListWebhooksResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ], "additionalProperties": false }, "DeleteWebhookResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false }, "ListDeliveriesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } }, "required": [ "data" ], "additionalProperties": false }, "PaymentRequired": { "type": "object", "properties": { "x402Version": { "type": "number", "const": 1 }, "error": { "type": "string", "description": "Why payment is needed, or what was wrong with the payment sent." }, "code": { "type": "string", "enum": [ "payment_required", "payment_invalid", "payment_unknown_quote", "payment_expired", "payment_used", "payment_wrong_resource", "payment_bad_signature", "payment_not_found", "payment_not_confirmed", "payment_wrong_chain", "payment_wrong_recipient", "payment_wrong_asset", "payment_wrong_payer", "payment_amount_too_low", "payment_too_old", "payment_too_late", "payment_failed", "payment_check_failed" ] }, "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequirements" }, "description": "Quotes to pay, one per asset. Empty when nothing can be quoted right now." } }, "required": [ "x402Version", "error", "code", "accepts" ], "additionalProperties": false, "description": "The body of a 402 from x402 (version 1)." }, "PaymentRequirements": { "type": "object", "properties": { "scheme": { "type": "string", "const": "tx-hash", "description": "WOVI's scheme: pay on chain yourself, then send the transaction hash, signed. Not \"exact\": that needs a facilitator and a token with signed transfers." }, "network": { "type": "string", "description": "CAIP-2, eip155:4663 for Robinhood Chain." }, "maxAmountRequired": { "type": "string", "description": "Atomic units of the asset (wei for ETH), as a decimal string." }, "resource": { "type": "string", "description": "The URL this pays for." }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "payTo": { "type": "string", "description": "Where to send the transfer." }, "maxTimeoutSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long the quote stays open." }, "asset": { "type": "string", "description": "The token contract, or 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for ETH (EIP-7528)." }, "outputSchema": { "type": "null" }, "extra": { "type": "object", "properties": { "nonce": { "type": "string", "description": "Single use. Goes into X-PAYMENT and into the signed message." }, "expiresAt": { "type": "string", "description": "The transfer must be mined before this." }, "chainId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The estimate in credits: the most the run can be charged." }, "priceUsd": { "type": "string", "description": "The same in USD, one credit is $0.01." }, "sign": { "type": "string", "description": "The message the paying wallet signs (EIP-191), with {txHash} filled in." } }, "required": [ "nonce", "expiresAt", "chainId", "symbol", "decimals", "credits", "priceUsd", "sign" ], "additionalProperties": false } }, "required": [ "scheme", "network", "maxAmountRequired", "resource", "description", "mimeType", "payTo", "maxTimeoutSeconds", "asset", "outputSchema", "extra" ], "additionalProperties": false, "description": "One way to pay for this call." }, "PaymentPayload": { "type": "object", "properties": { "x402Version": { "type": "number", "const": 1 }, "scheme": { "type": "string", "const": "tx-hash" }, "network": { "type": "string" }, "payload": { "type": "object", "properties": { "nonce": { "type": "string" }, "txHash": { "type": "string", "description": "The transfer you sent to payTo." }, "payer": { "type": "string", "description": "The wallet that sent it." }, "asset": { "type": "string" }, "signature": { "type": "string", "description": "The payer's EIP-191 signature of extra.sign with {txHash} filled in." } }, "required": [ "nonce", "txHash", "payer", "asset", "signature" ], "additionalProperties": false } }, "required": [ "x402Version", "scheme", "network", "payload" ], "additionalProperties": false, "description": "What goes into the X-PAYMENT header, as base64 of this JSON." }, "SettleResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "transaction": { "type": "string" }, "network": { "type": "string" }, "payer": { "type": "string" }, "errorReason": { "type": "string" } }, "required": [ "success", "transaction", "network", "payer" ], "additionalProperties": false, "description": "What the X-PAYMENT-RESPONSE header holds, as base64 of this JSON." }, "X402Payment": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "settled", "not_started", "rejected" ] }, "payer": { "type": "string" }, "network": { "type": "string" }, "transaction": { "type": "string" }, "asset": { "type": "string" }, "symbol": { "type": "string" }, "paid": { "type": "string", "description": "Atomic units." }, "required": { "type": "string" }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Quoted." }, "charged": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Charged once the run ended. Never more than quoted." }, "refund": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "string" }, "status": { "type": "string", "enum": [ "owed", "paid" ] }, "reason": { "type": "string" } }, "required": [ "amount", "status", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "What the owner owes back, if anything. Sent by the owner, not automatically." }, "test": { "type": "boolean", "description": "True on a test server with the fake verifier: no money moved." } }, "required": [ "id", "status", "payer", "network", "transaction", "asset", "symbol", "paid", "required", "credits", "charged", "refund", "test" ], "additionalProperties": false, "description": "A payment, as its payer sees it." }, "X402RunResult": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" }, "payment": { "$ref": "#/components/schemas/X402Payment" } }, "required": [ "run", "payment" ], "additionalProperties": false, "description": "A paid run and its payment." }, "X402PipelineRunResult": { "type": "object", "properties": { "pipelineRun": { "$ref": "#/components/schemas/PipelineRun" }, "payment": { "$ref": "#/components/schemas/X402Payment" } }, "required": [ "pipelineRun", "payment" ], "additionalProperties": false, "description": "A paid pipeline run and its payment." }, "X402Discovery": { "type": "object", "properties": { "x402Version": { "type": "number", "const": 1 }, "enabled": { "type": "boolean" }, "off": { "type": "string" }, "test": { "type": "boolean" }, "scheme": { "type": "string", "const": "tx-hash" }, "network": { "type": "string" }, "chainId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payTo": { "type": [ "string", "null" ] }, "assets": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "asset": { "type": "string" }, "decimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "symbol", "asset", "decimals" ], "additionalProperties": false } }, "creditUsd": { "type": "string" }, "quoteSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "confirmations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pricing": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "description": { "type": "string" }, "prices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "usd": { "type": "string" } }, "required": [ "id", "name", "credits", "usd" ], "additionalProperties": false } } }, "required": [ "method", "path", "description", "prices" ], "additionalProperties": false } }, "receipts": { "type": "object", "properties": { "header": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "string" } } }, "required": [ "header", "endpoints" ], "additionalProperties": false }, "payment": { "type": "object", "properties": { "header": { "type": "string" }, "sign": { "type": "string" }, "refunds": { "type": "string" } }, "required": [ "header", "sign", "refunds" ], "additionalProperties": false }, "mcp": { "type": "string" }, "openapi": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "x402Version", "enabled", "test", "scheme", "network", "chainId", "payTo", "assets", "creditUsd", "quoteSeconds", "confirmations", "pricing", "endpoints", "receipts", "payment", "mcp", "openapi", "docs" ], "additionalProperties": false, "description": "Which endpoints take x402, and the prices." } } } }