{
 "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.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"
     }
    }
   }
  }
 }
}