{"openapi": "3.1.0", "info": {"title": "SwishrJobs Job API", "version": "1.0.0", "description": "Submit digital jobs to SwishrJobs and receive independently verified deliverables. A job is quoted, explicitly authorized, executed, and verified by a checker other than the one that produced it. A priced job may be paid over x402 when the deployment configures a receiving address; otherwise no charge occurs."}, "servers": [{"url": "https://swishrjobs-api.onrender.com"}], "paths": {"/health": {"get": {"operationId": "getHealth", "summary": "Liveness and readiness probe.", "description": "Reports that the process is answering, plus the truthful execution gate state. A healthy service whose gate is closed reports status ok with execution_ready false.", "responses": {"200": {"description": "Health report."}}}}, "/v1/capabilities": {"get": {"operationId": "listCapabilities", "summary": "List capabilities SwishrJobs can execute.", "description": "Each capability carries its inputs, deliverables, acceptance criteria, limitations, buyer-phrased example requests, tags, and the live executability fields (provider_supports, provider_available, available, executable_now) so a caller can tell what can run now from what merely exists.", "responses": {"200": {"description": "Capability list.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CapabilityList"}}}}}}}, "/v1/capabilities/{capability_id}": {"get": {"operationId": "describeCapability", "summary": "Describe one capability, its inputs and deliverables.", "parameters": [{"name": "capability_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Capability description.", "content": {"application/json": {"schema": {"type": "object"}}}}, "404": {"description": "Unknown capability.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/jobs": {"get": {"operationId": "listJobs", "summary": "List the jobs a job access token can read.", "parameters": [{"name": "X-Job-Token", "in": "header", "required": false, "description": "The access_token returned by authorize. Without it the list is empty; a token returns only its own jobs.", "schema": {"type": "string"}}], "responses": {"200": {"description": "Jobs visible to the token."}}}, "post": {"operationId": "submitJob", "summary": "Validate a job request and receive a quote.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://swishrjobs.com/schemas/job-request.json", "title": "SwishrJobs Job Request", "type": "object", "additionalProperties": false, "required": ["capability_id"], "properties": {"capability_id": {"type": "string", "enum": ["boundary-value-generation", "csv-json-transformation", "data-validation-module", "dataset-quality-report", "duplicate-group-report", "edge-case-check", "field-mapping", "json-csv-conversion", "json-schema-inference", "key-normalisation", "malformed-record-detection", "markdown-table-rendering", "metadata-extraction", "nested-flattening", "python-multifile-package", "python-utility-module", "readme-generation", "record-deduplication", "regex-from-examples", "regression-suite-generation", "text-parser-module", "webhook-payload-validation", "xml-json-conversion"]}, "requester": {"type": "string", "minLength": 1, "description": "Identifier of the requesting agent or operator."}, "inputs": {"type": "object", "description": "Capability-specific inputs; see the capability's schema."}}}}}}, "responses": {"200": {"description": "Preflight result and quote."}, "400": {"description": "Malformed request."}}}}, "/v1/jobs/{job_id}/authorize": {"post": {"operationId": "authorizeJob", "summary": "Explicitly authorize execution of a quoted job.", "parameters": [{"name": "job_id", "in": "path", "required": true, "description": "The server assigns the job id; the path value is not used to name the job.", "schema": {"type": "string"}}, {"name": "X-Job-Token", "in": "header", "required": false, "description": "The access_token from a prior authorize on this job. Required to re-authorize an existing job.", "schema": {"type": "string"}}, {"name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 payment payload. Required only when the deployment prices the capability and has a receiving address; absent it, a priced job answers 402 with the requirements rather than running for free.", "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["authorized_by"], "properties": {"authorized_by": {"type": "string", "minLength": 1, "description": "Identifier of the human or agent authorizing the work."}, "capability_id": {"type": "string"}, "inputs": {"type": "object"}, "idempotency_key": {"type": "string", "description": "Makes a retry safe: the same key returns the existing job rather than creating a second one."}}}}}}, "responses": {"202": {"description": "Job accepted and run.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JobResult"}}}}, "400": {"description": "Missing authorized_by or malformed body.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Payment required or refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/jobs/{job_id}": {"get": {"operationId": "getJob", "summary": "Fetch job state, history, and result.", "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "X-Job-Token", "in": "header", "required": true, "description": "The access_token returned by authorize. Without it the job is reported as not found.", "schema": {"type": "string"}}], "responses": {"200": {"description": "Job record.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JobResult"}}}}, "404": {"description": "Unknown job, or a job this token may not read."}}}}, "/v1/performance": {"get": {"operationId": "getPerformance", "summary": "Measured success rate, latency and cost per accepted result.", "description": "Controlled synthetic benchmark results for every capability. A capability that has not been benchmarked reports measured=false with a null success_rate; no rate is invented. These are not customer outcomes and are labelled as synthetic.", "responses": {"200": {"description": "Performance report."}}}}, "/v1/select": {"post": {"operationId": "selectCapability", "summary": "Rank capabilities for a described task.", "description": "Rank capabilities by task match, measured synthetic success rate, and expected cost per accepted result, and explain the ranking. Unmeasured capabilities rank below measured ones.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["task"], "properties": {"task": {"type": "string", "minLength": 1}, "limit": {"type": "integer", "minimum": 0, "default": 5}, "available_only": {"type": "boolean", "default": true}}}}}}, "responses": {"200": {"description": "Ranked capabilities."}, "400": {"description": "Missing or malformed task.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/a2a": {"post": {"operationId": "a2aJsonRpc", "summary": "A2A JSON-RPC binding (SendMessage, GetTask, CancelTask).", "responses": {"200": {"description": "JSON-RPC response."}}}}, "/.well-known/agent-card.json": {"get": {"operationId": "getAgentCard", "summary": "The A2A agent card.", "responses": {"200": {"description": "Agent card."}}}}}, "components": {"schemas": {"JobRequest": {"$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://swishrjobs.com/schemas/job-request.json", "title": "SwishrJobs Job Request", "type": "object", "additionalProperties": false, "required": ["capability_id"], "properties": {"capability_id": {"type": "string", "enum": ["boundary-value-generation", "csv-json-transformation", "data-validation-module", "dataset-quality-report", "duplicate-group-report", "edge-case-check", "field-mapping", "json-csv-conversion", "json-schema-inference", "key-normalisation", "malformed-record-detection", "markdown-table-rendering", "metadata-extraction", "nested-flattening", "python-multifile-package", "python-utility-module", "readme-generation", "record-deduplication", "regex-from-examples", "regression-suite-generation", "text-parser-module", "webhook-payload-validation", "xml-json-conversion"]}, "requester": {"type": "string", "minLength": 1, "description": "Identifier of the requesting agent or operator."}, "inputs": {"type": "object", "description": "Capability-specific inputs; see the capability's schema."}}}, "Quote": {"$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://swishrjobs.com/schemas/quote.json", "title": "SwishrJobs Quote", "type": "object", "additionalProperties": false, "required": ["billable", "amount", "currency", "reason", "cost_basis"], "properties": {"billable": {"type": "boolean"}, "amount": {"type": ["number", "null"]}, "currency": {"type": ["string", "null"]}, "reason": {"type": "string"}, "cost_basis": {"type": "string"}, "payment_processing": {"type": "string"}, "price_status": {"type": "string", "enum": ["quoted", "custom_quote_required", "not_offered"]}, "pricebook_version": {"type": "string"}, "service_quote": {"anyOf": [{"$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://swishrjobs.com/schemas/service-quote.json", "title": "SwishrJobs Service Quote", "type": "object", "additionalProperties": false, "required": ["quote_id", "status", "capability_id", "service_name", "scope", "issued_at", "expires_at", "amount", "currency", "price_basis", "price_status", "evidence_backed", "pricebook_version", "deliverables", "acceptance_criteria", "included_limits", "exclusions", "verification_method", "failure_policy", "re_quote_conditions"], "properties": {"quote_id": {"type": "string"}, "status": {"type": "string", "enum": ["quoted", "custom_quote_required", "not_offered"]}, "capability_id": {"type": "string"}, "service_name": {"type": "string"}, "scope": {"type": "string"}, "assumptions": {"type": "array", "items": {"type": "string"}}, "issued_at": {"type": "string"}, "expires_at": {"type": "string"}, "amount": {"type": ["string", "null"]}, "currency": {"type": ["string", "null"]}, "billing_unit": {"type": ["string", "null"]}, "quantity": {"type": "integer", "minimum": 1}, "price_basis": {"type": "string", "enum": ["introductory", "standard", "custom", "none"]}, "price_status": {"type": "string"}, "evidence_backed": {"type": "boolean"}, "pricebook_version": {"type": "string"}, "deliverables": {"type": "array", "items": {"type": "string"}}, "acceptance_criteria": {"type": "array", "items": {"type": "string"}}, "included_limits": {"type": "array", "items": {"type": "string"}}, "exclusions": {"type": "array", "items": {"type": "string"}}, "estimated_completion_hours": {"type": ["integer", "null"]}, "dependencies": {"type": "array", "items": {"type": "string"}}, "required_inputs": {"type": "array", "items": {"type": "string"}}, "required_permissions": {"type": "array", "items": {"type": "string"}}, "verification_method": {"type": "string"}, "revisions_included": {"type": "integer", "minimum": 0}, "failure_policy": {"type": "string"}, "re_quote_conditions": {"type": "array", "items": {"type": "string"}}, "comparables": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["label", "price_usd", "url", "accessed", "quality"], "properties": {"label": {"type": "string"}, "price_usd": {"type": "number"}, "url": {"type": "string"}, "accessed": {"type": "string"}, "quality": {"type": "string"}}}}, "payment_processing": {"type": "string"}}}, {"type": "null"}]}}}, "JobResult": {"type": "object", "required": ["job_id", "state"], "properties": {"job_id": {"type": "string"}, "state": {"enum": ["received", "rejected", "quoted", "authorized", "executing", "deferred", "verifying", "completed", "failed", "timed_out", "cancelled"]}, "capability_id": {"type": "string"}, "access_token": {"type": "string", "description": "Per-job credential. Present it as the X-Job-Token header to read the job or list it. Keep it; it is the only credential for this job."}, "verification": {"type": "object", "description": "Independent verification. verification.ok = false means the job failed, not a partial success."}, "artifacts": {"type": "array"}, "quote": {"type": "object"}}}, "CapabilityList": {"type": "object", "required": ["service", "capabilities"], "properties": {"service": {"type": "string"}, "version": {"type": "string"}, "execution_gate": {"type": "string"}, "execution_ready": {"type": "boolean"}, "payment": {"type": "object"}, "capabilities": {"type": "array", "items": {"type": "object"}}}}, "Error": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}