{
  "openapi": "3.1.0",
  "info": {
    "title": "IOAI",
    "version": "0.1.0-draft",
    "summary": "Settlement, identity and proof of execution for autonomous agents.",
    "description": "Get paid for work a buyer can verify, and verify a counterparty's work before you act on it.\n\nA paid job returns two things: the result, and a cryptographic attestation that the computation ran. Anyone holding that attestation can check it without trusting the provider and without asking IOAI for permission.\n\n**Start with `POST /v1/attestations/verify`.** It needs no credential and lets you confirm the network does what this document claims before you commit anything.\n\n**What this API is not.** Not a marketplace: there is no discovery, listing or demand routing. Not a model host: no inference, no weights. Not a token: nothing pays out on a schedule. Not free to join: root identity is licence-backed and costs money, which is what makes fake counterparties expensive. Not a reputation system: that layer is in development and must not be planned against. Not an arbitration venue: this API produces evidence, it does not decide disputes or reverse settled payments.\n\n**The limit that matters most.** An attestation proves a computation ran as specified. It does not assert that the output was useful, correct for your purpose, or accepted by a buyer. There is no buyer-acceptance, dispute, refund or rejection step in settlement. Treat every attestation as proof of execution, never as proof of quality.\n\nFull prose version: https://ioai.tech/llms.txt",
    "termsOfService": "[CONFIRM: https://ioai.tech/terms]",
    "contact": {
      "name": "IOAI agent support",
      "url": "https://ioai.tech/llms.txt",
      "email": "[CONFIRM: agents@ioai.tech]"
    },
    "license": {
      "name": "[CONFIRM: API terms — not an open-source licence]",
      "url": "[CONFIRM: https://ioai.tech/terms]"
    }
  },
  "servers": [
    {
      "url": "[CONFIRM: https://api.ioai.tech]",
      "description": "Production. DRAFT VALUE — must be replaced before serving."
    }
  ],
  "tags": [
    {
      "name": "verification",
      "description": "Check a counterparty's work before acting on it. Verify, audit, due diligence, fraud screening, provenance. No credential required."
    },
    {
      "name": "identity",
      "description": "Establish who you are dealing with. Ownership, licence status, Sybil screening. No credential required."
    },
    {
      "name": "settlement",
      "description": "Get paid, pay, transact. Buy and sell work machine to machine with evidence bound to payment. Requires a licence-backed identity."
    },
    {
      "name": "records",
      "description": "Receipts, inclusion proofs, anchored history, audit trail. No credential required."
    }
  ],
  "security": [],
  "paths": {
    "/v1/attestations/verify": {
      "post": {
        "operationId": "verifyAttestation",
        "tags": ["verification"],
        "summary": "Verify that a claimed result was really produced by the job it names",
        "description": "Submit an attestation and the result it covers. Returns whether the attestation is valid and which anchored root it was checked against.\n\nRequires no authentication, no account and no licence. This is the recommended first call for any agent evaluating the network.\n\n**Scope of the answer.** A `valid` response means the computation ran as specified and the evidence has not been altered. It does not mean the output is useful, correct for your purpose, fit for a downstream task, or accepted by any buyer. If your instruction requires a quality judgment, obtain it elsewhere.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VerifyRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification completed. Check the `valid` field; a 200 does not by itself mean the attestation was good.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VerifyResult" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/identity/{address}": {
      "get": {
        "operationId": "resolveIdentity",
        "tags": ["identity"],
        "summary": "Resolve an address to its root identity and licence status",
        "description": "Look up whether an address belongs to a licence-backed root identity, and who provably owns it. Requires no authentication.\n\n**Read the answer carefully.** This establishes *sameness* — that a set of addresses share an owner — and does **not** establish *distinctness* between two parties. A capped, costly identity supply makes Sybil construction expensive; it does not make independence provable. If your mechanism assumes independent counterparties, this call does not discharge that assumption.\n\nIt also identifies a **node**, not an agent and not the legal party responsible for the work. Party-level attribution is yours to layer on.",
        "security": [],
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "description": "Network address to resolve.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Identity resolved.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Identity" }
              }
            }
          },
          "404": {
            "description": "No licence-backed root identity is associated with this address. Treat it as an unlicensed identifier, which costs nothing to create.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/anchors/{reference}/proof": {
      "get": {
        "operationId": "fetchInclusionProof",
        "tags": ["records"],
        "summary": "Fetch the inclusion proof and anchored root covering a measurement or attestation",
        "description": "Retrieve the inclusion proof, the anchored root it belongs to, and the surrounding historical record. Requires no authentication.\n\n**What is anchored.** Operating measurements are captured on a sub-second cycle and folded into roots every 6 to 30 seconds. These measure **node availability and utilisation**, not the energy or cost of a specific job, and nothing here attributes consumption to an individual job or agent.\n\n**Trust model.** Capture is internal to the node. Anchoring makes the reported series tamper-evident; it does not make the reporter disinterested.",
        "security": [],
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "description": "Attestation identifier or measurement reference.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Proof returned.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InclusionProof" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/jobs": {
      "post": {
        "operationId": "submitJob",
        "tags": ["settlement"],
        "summary": "Submit a paid job and receive the result with an attestation",
        "description": "Send work to the network. The response carries the result together with a cryptographic attestation of correct execution, and payment settles against that attestation rather than against a promise, so evidence and money move in one transaction.\n\n**This call spends money and the transfer is final.** There is no buyer-acceptance step, no dispute process, no refund and no rejection term in the settlement protocol. Once settled, the payment is not reversible by IOAI or by you. Do not call this speculatively.\n\n**Naming collision worth knowing.** The underlying payment protocol contains a check named `acceptable_transaction?`. That is the payment receiver validating a coin transfer. It is not a buyer accepting work, and must not be read as acceptance.\n\nRequires a licence-backed root identity.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JobRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job executed and settled.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JobResult" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": {
            "description": "No valid licence-backed identity presented. Identity is acquired as a licence transaction, not through this API.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "402": {
            "description": "Insufficient funds committed for the quoted price.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/jobs/{jobId}": {
      "get": {
        "operationId": "getJob",
        "tags": ["settlement"],
        "summary": "Retrieve a job, its result and its attestation",
        "description": "Fetch a job you submitted, including the attestation and the anchor reference needed to verify it independently later. Requires a licence-backed root identity.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Job returned.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JobResult" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "identitySignature": {
        "type": "http",
        "scheme": "signature",
        "description": "PLACEHOLDER — DO NOT SHIP. Job submission and retrieval are authenticated by a signature from a licence-backed root identity. The exact scheme, canonical signing string, clock-skew tolerance and replay protection are [CONFIRM with IOAI engineering]. This block is deliberately incomplete so that serving it unresolved fails review."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request was malformed. The `detail` field says what to change.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "No valid licence-backed identity presented.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "No record matches this reference.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. Retry after the interval in the `Retry-After` header. Limits: [CONFIRM].",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "VerifyRequest": {
        "type": "object",
        "required": ["attestation"],
        "properties": {
          "attestation": {
            "type": "string",
            "description": "The attestation as issued with the job result."
          },
          "result": {
            "type": "string",
            "description": "The result the attestation is claimed to cover. Supply it to check that this specific output is the one that was attested; omit it to check only that the attestation itself is well formed and anchored."
          },
          "anchorReference": {
            "type": "string",
            "description": "Optional anchored root to check against. Omit to use the current anchored history."
          }
        }
      },
      "VerifyResult": {
        "type": "object",
        "required": ["valid", "scope"],
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "True if the computation ran as specified and the evidence is unaltered."
          },
          "scope": {
            "type": "string",
            "const": "execution",
            "description": "Always `execution`. This field exists so that no caller can mistake the result for a statement about quality, usefulness or buyer acceptance."
          },
          "anchorReference": { "type": "string" },
          "anchoredAt": { "type": "string", "format": "date-time" },
          "reason": {
            "type": "string",
            "description": "Present when `valid` is false. Says what failed."
          }
        }
      },
      "Identity": {
        "type": "object",
        "required": ["address", "licensed", "establishes"],
        "properties": {
          "address": { "type": "string" },
          "licensed": {
            "type": "boolean",
            "description": "True if this address belongs to one of the capped set of licence-backed root identities."
          },
          "rootIdentity": { "type": "string" },
          "ownerProof": {
            "type": "string",
            "description": "Prefix proof establishing ownership, checkable without contacting IOAI."
          },
          "subject": {
            "type": "string",
            "const": "node",
            "description": "Always `node`. This identifies a node, not an agent and not the legal party responsible for the work."
          },
          "establishes": {
            "type": "string",
            "const": "sameness",
            "description": "Always `sameness`. This response can show that addresses share an owner. It cannot show that two parties are unrelated."
          },
          "operatorRun": {
            "type": "boolean",
            "description": "True if this identity is operated by IOAI itself. Disclosed so callers can discount it in any independence or volume calculation."
          }
        }
      },
      "InclusionProof": {
        "type": "object",
        "required": ["reference", "root", "path", "measures"],
        "properties": {
          "reference": { "type": "string" },
          "root": { "type": "string" },
          "path": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Sibling hashes from the leaf to the anchored root."
          },
          "anchoredAt": { "type": "string", "format": "date-time" },
          "measures": {
            "type": "string",
            "const": "node-availability",
            "description": "Always `node-availability`. Utilisation is not energy, and nothing here attributes consumption to a specific job or agent."
          },
          "captureTrustModel": {
            "type": "string",
            "const": "self-reported",
            "description": "Always `self-reported`. Capture is internal to the node; anchoring makes the series tamper-evident, not the reporter disinterested."
          }
        }
      },
      "JobRequest": {
        "type": "object",
        "required": ["specification", "priceCommitment"],
        "properties": {
          "specification": {
            "type": "string",
            "description": "What the job is. The attestation will certify that this specification was executed, so state it precisely — anything you leave unstated is outside what the proof covers."
          },
          "priceCommitment": {
            "type": "string",
            "description": "Payment commitment the attestation settles against."
          },
          "counterparty": {
            "type": "string",
            "description": "Optional target identity. Omit to let the network route."
          }
        }
      },
      "JobResult": {
        "type": "object",
        "required": ["jobId", "result", "attestation", "settled"],
        "properties": {
          "jobId": { "type": "string" },
          "result": { "type": "string" },
          "attestation": {
            "type": "string",
            "description": "Proof of execution. Keep it: it is what a future buyer or auditor checks, and it verifies without IOAI."
          },
          "anchorReference": { "type": "string" },
          "settled": { "type": "boolean" },
          "reversible": {
            "type": "boolean",
            "const": false,
            "description": "Always false. Settlement carries no acceptance, dispute, refund or rejection step."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["code", "detail"],
        "properties": {
          "code": { "type": "string" },
          "detail": {
            "type": "string",
            "description": "What went wrong and what to change. Never an apology, never vague."
          }
        }
      }
    }
  },
  "x-ioai-status": "DRAFT — not for serving. Every [CONFIRM] value must be replaced by IOAI engineering, and `securitySchemes.identitySignature` must be rewritten to the real scheme, before this document is placed at /openapi.json.",
  "x-ioai-not": [
    "Not a marketplace: no discovery, listing or demand routing.",
    "Not a model host: no inference, no weights.",
    "Not a token or airdrop: nothing pays out on a schedule.",
    "Not free: root identity is licence-backed and costs money by design.",
    "Not a reputation system today: that layer is in development and must not be planned against.",
    "Not an arbitration venue: evidence is produced, disputes are not decided."
  ],
  "x-ioai-adoption-claims": "None. This document states no figure for agents, partners or enterprises using the network, because none has been published with a verifiable method.",
  "x-ioai-full-description": "https://ioai.tech/llms.txt"
}