{ "openapi": "3.1.0", "info": { "title": "Teppi", "description": "The record of what happened when someone paid a machine service. Every entry carries the settlement transaction, the hashes of what was sent and returned, and the check that ran.", "version": "0.1.0" }, "servers": [ { "url": "https://api.teppi.xyz" } ], "paths": { "/v1/check": { "get": { "operationId": "checkBeforePaying", "summary": "Returns what the record holds about any x402 endpoint url before you pay it: the grade if one exists, the price and rails its last 402 offered, and what is wrong with the listing. A url never seen is put in line for a free handshake, so ask again in an hour.", "tags": [ "check", "grade", "x402", "url", "before-paying" ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri", "minLength": 8, "maxLength": 2048 } }, { "name": "method", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GET", "POST" ] } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "what the record holds about the url, signed with the check key", "properties": { "band": { "type": "string", "enum": [ "A", "B", "C", "D", "F", "UNRATED" ], "description": "a letter, or UNRATED when not enough is known" }, "tier": { "type": [ "string", "null" ], "enum": [ "LIVENESS_VERIFIED", "DELIVERY_VERIFIED", "OUTCOME_VERIFIED", null ], "description": "what measured it" }, "composite": { "type": [ "number", "null" ], "description": "the number the letter summarises" }, "why": { "type": "string", "description": "why the grade is what it is, in words" }, "asked": { "type": "string", "description": "the url or id as it was asked" }, "matched": { "type": "string", "enum": [ "exact", "path", "none" ], "description": "how the url met the record: exactly, by path alone, or not at all" }, "defects": { "type": "array", "items": { "type": "object", "properties": { "defect": { "type": "string", "description": "what the listing gets wrong" }, "says": { "type": "string", "description": "the same in words" }, "seenAt": { "type": [ "string", "null" ], "description": "when it was last seen" } }, "required": [ "defect", "says" ] }, "description": "what is wrong with the listing" }, "capabilityId": { "type": "string", "description": "the endpoint in the record, when it is there" }, "url": { "type": "string", "description": "the url the record holds for it" }, "components": { "type": [ "object", "null" ], "description": "every part of the grade, each with its bound and sample count", "properties": { "liveness": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "correctness": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "honesty": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "schema_conformance": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "latency_p95": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "price_stability": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] } } }, "sampleCount": { "type": "integer", "minimum": 0, "description": "samples behind the grade" }, "computedAt": { "type": [ "string", "null" ], "description": "when the grade was computed" }, "observationsSince": { "type": "integer", "minimum": 0, "description": "observations newer than the grade" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "conditions on the grade" }, "observed": { "type": "object", "description": "what the free handshakes saw", "properties": { "probes": { "type": "integer", "minimum": 0, "description": "handshakes" }, "answered": { "type": "integer", "minimum": 0, "description": "handshakes it answered" }, "askedForPayment": { "type": "integer", "minimum": 0, "description": "handshakes answered with a 402" }, "firstSeen": { "type": [ "string", "null" ], "description": "the first handshake" }, "lastSeen": { "type": [ "string", "null" ], "description": "the newest handshake" }, "spanDays": { "type": "number", "description": "days from the first handshake to now" }, "advertised": { "type": [ "object", "null" ], "description": "what its newest 402 asked", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "the price" }, "asset": { "type": "string", "description": "the token" }, "networks": { "type": "array", "items": { "type": "string" }, "description": "CAIP-2 ids" } } }, "distinctPrices": { "type": "integer", "minimum": 0, "description": "prices seen" }, "protocols": { "type": "array", "items": { "type": "string" }, "description": "x402, mpp" } } }, "reproduce": { "type": [ "string", "null" ], "description": "the command that runs the same handshake without us" }, "scorecard": { "type": [ "string", "null" ], "description": "the signed card behind the grade" }, "corrections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "the correction id" }, "fault": { "type": "string", "description": "which of our own faults it names" }, "says": { "type": "string", "description": "what we got wrong" }, "issuedAt": { "type": "string", "description": "when it was issued" }, "recordId": { "type": [ "string", "null" ], "description": "the one record it names, or null for all of them" }, "gradeAt": { "type": [ "string", "null" ], "description": "the one grade it names, or null" } }, "required": [ "id", "fault", "says", "issuedAt" ] }, "description": "what we got wrong about it" }, "queued": { "type": "boolean", "description": "a url never seen, now in line for a handshake" }, "next": { "type": "string", "description": "what to do next about a url the record has not seen" }, "payee": { "type": [ "object", "null" ], "description": "what the record knows about whoever pay_to names", "properties": { "address": { "type": "string", "description": "the payout address" }, "origins": { "type": "array", "items": { "type": "string" }, "description": "origins that pay it" }, "listed": { "type": "integer", "minimum": 0, "description": "active endpoints behind it" }, "graded": { "type": "integer", "minimum": 0, "description": "of those, holding a letter" }, "bestBand": { "type": [ "string", "null" ], "description": "the best letter behind it" }, "withDefects": { "type": "integer", "minimum": 0, "description": "of those, with a listing defect" } } }, "buy": { "type": "object", "description": "how to buy it through Teppi and be charged only if the answer passes", "properties": { "url": { "type": "string", "description": "where to send the call" }, "method": { "type": "string", "description": "GET or POST" }, "seller_price": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "the seller's price" }, "fee": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "Teppi's fee" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what the buyer signs for" }, "asset": { "type": "string", "description": "USDC" }, "guarantee": { "type": "string", "description": "when the buyer is charged" }, "publish": { "type": "string", "description": "the header that puts the call in the record" } } }, "answered_at": { "type": "string", "description": "when this answer was given" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "band", "tier", "composite", "why", "asked", "matched", "defects", "answered_at", "signing_key_id", "signature" ] } } } } } } }, "/v1/trust/{id}": { "get": { "operationId": "getGrade", "summary": "Returns the quality grade for a paid endpoint, with the components behind it and a sample of the evidence. Use before paying an endpoint you have not used.", "tags": [ "grade", "quality", "x402", "endpoint" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cap_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "every published card for the endpoint, deepest first", "properties": { "schema": { "type": "string", "description": "teppi.trust.v1" }, "capability_id": { "type": "string", "description": "the endpoint" }, "scorecards": { "type": "array", "items": { "type": "object", "description": "one signed card: a grade with everything needed to recompute it", "properties": { "schema": { "type": "string", "description": "teppi.scorecard.v1 or v2" }, "capability_id": { "type": "string", "description": "the endpoint graded" }, "tier": { "type": "string", "enum": [ "LIVENESS_VERIFIED", "DELIVERY_VERIFIED", "OUTCOME_VERIFIED" ], "description": "what measured it" }, "band": { "type": "string", "enum": [ "A", "B", "C", "D", "F", "UNRATED" ], "description": "the letter, or UNRATED" }, "composite": { "type": "number", "description": "the weighted sum of the lower bounds" }, "components": { "type": [ "object", "null" ], "description": "every part of the grade, each with its bound and sample count", "properties": { "liveness": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "correctness": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "honesty": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "schema_conformance": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "latency_p95": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "price_stability": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] } } }, "weights_applied": { "type": "object", "description": "the weight each scored part carried" }, "weights_version": { "type": "string", "description": "which weights" }, "sample_count": { "type": "integer", "minimum": 0, "description": "samples behind it" }, "window_days": { "type": "integer", "minimum": 0, "description": "the window it read" }, "window_start": { "type": "string", "description": "where the window starts" }, "computed_at": { "type": "string", "description": "when it was computed" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "conditions on the grade" }, "evidence_sample": { "type": "array", "items": { "type": "string" }, "description": "the evidence hashes it stood on" }, "method": { "type": "string", "description": "the method page it was computed under" }, "verifier_version": { "type": "string", "description": "which verifier scored the samples" }, "signing_key_id": { "type": "string", "description": "the published key that signed it" }, "canonicalization": { "type": "string", "description": "RFC8785" }, "signature": { "type": "string", "description": "ed25519 over the canonical bytes of the card" } }, "required": [ "schema", "capability_id", "tier", "band", "composite", "components", "signature" ] }, "description": "the cards, deepest tier first" }, "disputes": { "type": "array", "items": { "type": "object" }, "description": "the seller's own receipts" }, "corrections": { "type": "array", "items": { "type": "object" }, "description": "what we got wrong" } }, "required": [ "schema", "capability_id", "scorecards", "disputes", "corrections" ] } } } } } } }, "/v1/trust/feed": { "get": { "operationId": "gradeFeed", "summary": "Streams every grade as it is published, newline delimited, resumable from a cursor. Use to mirror the whole record.", "tags": [ "feed", "mirror", "grade", "ndjson" ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/route/plan": { "post": { "operationId": "planOutcome", "summary": "Turns a goal and a budget into a costed chain of endpoints, before any money is spent. Returns the plan and the estimate.", "tags": [ "plan", "budget", "routing", "estimate" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "type": "string" }, "budget_usd": { "type": "string" } }, "required": [ "goal", "budget_usd" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "a costed plan, which moves no money", "properties": { "plan_id": { "type": "string", "pattern": "^pln_[0-9A-HJKMNP-TV-Z]{26}$", "description": "the plan" }, "estimated_usd": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what the plan is expected to cost" }, "budget_usd": { "type": "string", "description": "the budget asked for" }, "expires_at": { "type": "string", "description": "when the quote stops being buyable" }, "ttl_seconds": { "type": "integer", "minimum": 0, "description": "seconds the quote holds" }, "steps": { "type": "array", "description": "the calls, in order", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "description": "its place in the plan" }, "class": { "type": "string", "description": "what kind of call" }, "capability_id": { "type": "string", "description": "the endpoint picked" }, "grade": { "type": "object", "description": "its grade and what measured it", "properties": { "band": { "type": "string", "enum": [ "A", "B", "C", "D", "F", "UNRATED" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "LIVENESS_VERIFIED", "DELIVERY_VERIFIED", "OUTCOME_VERIFIED", null ] } } }, "est_usd": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "its expected price" }, "purpose": { "type": "string", "description": "what the step is for" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "endpoints tried instead, no dearer" } }, "required": [ "index", "class", "capability_id", "est_usd" ] } }, "missing": { "type": "array", "description": "what the goal needed that nothing listed could do", "items": { "type": "object", "properties": { "class": { "type": [ "string", "null" ], "description": "the kind of call" }, "reason": { "type": "string", "description": "why it is missing" } } } }, "guarantee": { "type": "string", "description": "when a buyer of the plan is charged" } }, "required": [ "plan_id", "estimated_usd", "expires_at", "steps", "missing", "guarantee" ] } } } } } } }, "/v1/route/execute": { "post": { "operationId": "executePlan", "summary": "Buys every step of a plan from /v1/route/plan with one payment, and settles it only if every answer came back whole and matching the schema its seller published.", "tags": [ "buy", "plan", "pay-on-delivery", "x402" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "pattern": "^pln_[0-9A-HJKMNP-TV-Z]{26}$" }, "inputs": { "type": "object", "description": "Each step's input by its index. {\"$from\": {\"step\": 0, \"pointer\": \"/id\"}} copies a value out of an earlier step's answer." } }, "required": [ "plan_id" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "payment required: the seller's price plus the fee, in the body and the payment-required header" }, "424": { "description": "the seller could not be bought or its answer failed its checks, and nothing was charged" } }, "x-teppi-fee": { "basis_points": 1000, "minimum": "0.002000", "asset": "USDC", "on": "the seller's price" } } }, "/v1/evaluate": { "post": { "operationId": "evaluateDelivery", "summary": "Checks an answer you already got from a listed endpoint against the schema its seller published, and signs what the checks found. Free, and nothing is written to the record.", "tags": [ "evaluate", "schema", "delivery", "signed" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capability_id": { "type": "string", "pattern": "^cap_[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "type": "integer", "minimum": 100, "maximum": 599 }, "body": { "type": "string", "maxLength": 1000000 } }, "required": [ "capability_id", "status", "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "an answer you hold, judged against its seller's published schema; nothing stored", "properties": { "capability": { "type": "object", "properties": { "id": { "type": "string", "description": "the endpoint" }, "url": { "type": "string", "description": "its url" }, "method": { "type": "string", "description": "GET or POST" } } }, "evaluated": { "type": "object", "description": "the answer judged, by its hash", "properties": { "status": { "type": "integer", "minimum": 0, "description": "its status" }, "body": { "type": "string", "description": "sha256 of its body" } } }, "passed": { "type": "boolean", "description": "whole and matching the schema" }, "checks": { "type": "array", "items": { "type": "object" }, "description": "each check and its result" }, "schema_declared": { "type": "boolean", "description": "the seller published a schema" }, "schema_conformance": { "type": [ "number", "null" ], "description": "share of the schema met" }, "injection_observed": { "type": "boolean", "description": "the body tried to give instructions" }, "honesty": { "type": "null", "description": "not measured: nothing was paid" }, "correctness": { "type": "null", "description": "not measured: nobody holds the right answer" }, "not_measured": { "type": "string", "description": "why" }, "recorded": { "type": "boolean", "const": false, "description": "nothing is written" }, "verifier_version": { "type": "string", "description": "which verifier judged it" }, "answered_at": { "type": "string", "description": "when this answer was given" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "capability", "evaluated", "passed", "checks", "answered_at", "signature" ] } } } } } } }, "/v1/via/{capability_id}": { "get": { "operationId": "buyOnDelivery", "summary": "Buys one call to a listed GET endpoint for you, with the query you send, and settles your payment only if the answer came back whole and matching its published schema.", "tags": [ "buy", "pay-on-delivery", "receipt", "x402" ], "parameters": [ { "name": "capability_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cap_[0-9A-HJKMNP-TV-Z]{26}$", "description": "The endpoint to buy, by the id the record lists it under." } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "payment required: the seller's price plus the fee, in the body and the payment-required header" }, "424": { "description": "the seller could not be bought or its answer failed its checks, and nothing was charged" } }, "x-teppi-fee": { "basis_points": 1000, "minimum": "0.002000", "asset": "USDC", "on": "the seller's price" } }, "post": { "operationId": "buyOnDeliveryPost", "summary": "Buys one call to a listed POST endpoint for you, with the json body you send, and settles your payment only if the answer came back whole and matching its published schema.", "tags": [ "buy", "pay-on-delivery", "receipt", "x402" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The seller's own request body, as its listing describes it." } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "payment required: the seller's price plus the fee, in the body and the payment-required header" }, "424": { "description": "the seller could not be bought or its answer failed its checks, and nothing was charged" } }, "x-teppi-fee": { "basis_points": 1000, "minimum": "0.002000", "asset": "USDC", "on": "the seller's price" } } }, "/v1/orders/{order_id}": { "get": { "operationId": "orderReceipt", "summary": "Returns the signed receipt for one purchase made on delivery: the quote, both payments with their transactions, the checks the answer met, and commitments to the bytes.", "tags": [ "receipt", "order", "signed", "pay-on-delivery" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "a signed receipt for one purchase made on delivery", "properties": { "schema": { "type": "string", "description": "teppi.order.v1" }, "order_id": { "type": "string", "description": "the order" }, "kind": { "type": "string", "enum": [ "via", "plan", "step" ], "description": "a call, a plan or a step" }, "status": { "type": "string", "description": "open, passed, failed or refused" }, "reason": { "type": [ "string", "null" ], "description": "why it did not pass" }, "capability": { "type": [ "object", "null" ], "description": "the endpoint bought, null on a plan", "properties": { "id": { "type": "string", "description": "the endpoint" }, "url": { "type": "string", "description": "its url" }, "method": { "type": "string", "description": "GET or POST" } } }, "plan": { "type": [ "object", "null" ], "description": "every try at every step, on a plan" }, "part_of": { "type": [ "object", "null" ], "description": "the plan a step belongs to" }, "quote": { "type": "object", "description": "what the buyer was quoted", "properties": { "seller_price": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "the seller's price" }, "fee": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "Teppi's fee" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what the buyer signed for" }, "asset": { "type": "string", "description": "USDC" } } }, "buyer": { "type": "string", "description": "the address that bought it" }, "paid": { "type": [ "object", "null" ], "description": "what the buyer paid", "properties": { "receipt_id": { "type": "string", "description": "the receipt" }, "network": { "type": "string", "description": "the chain it settled on, CAIP-2" }, "settled": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "what moved, null until the chain has said" }, "transaction": { "type": [ "string", "null" ], "description": "the transaction" }, "final": { "type": "boolean", "description": "the receipt is closed" } } }, "bought": { "type": [ "object", "null" ], "description": "what Teppi paid the seller", "properties": { "receipt_id": { "type": "string", "description": "the receipt" }, "network": { "type": "string", "description": "the chain it settled on, CAIP-2" }, "settled": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "what moved, null until the chain has said" }, "transaction": { "type": [ "string", "null" ], "description": "the transaction" }, "final": { "type": "boolean", "description": "the receipt is closed" } } }, "request_commitment": { "type": "string", "description": "salted hash of the request" }, "response_commitment": { "type": [ "string", "null" ], "description": "salted hash of the answer" }, "commitment_scheme": { "type": "string", "description": "how to check a commitment with the salt" }, "checks": { "type": [ "array", "null" ], "description": "what the answer was checked against" }, "delivery": { "type": "object", "description": "liveness, schema conformance, honesty" }, "correctness": { "type": "string", "description": "why correctness is not measured on a buyer's own request" }, "published": { "type": "boolean", "description": "the buyer put the call in the record" }, "evidence": { "type": [ "string", "null" ], "description": "the record entry, when published" }, "verifier_version": { "type": [ "string", "null" ], "description": "which verifier checked it" }, "opened_at": { "type": "string", "description": "when it was opened" }, "closed_at": { "type": [ "string", "null" ], "description": "when it closed" }, "issued_at": { "type": "string", "description": "when this receipt was issued" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "schema", "order_id", "kind", "status", "quote", "buyer", "issued_at", "signature" ] } } } } } } }, "/v1/buyers/{address}/orders": { "get": { "operationId": "buyerOrders", "summary": "Lists every purchase an address made on delivery, with what it was charged and what was not charged, when the request is signed by that address.", "tags": [ "ledger", "orders", "buyer", "pay-on-delivery" ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "one buyer's purchases, answered only to that address's signature", "properties": { "buyer": { "type": "string", "description": "the address" }, "totals": { "type": "object", "properties": { "orders": { "type": "integer", "minimum": 0, "description": "orders" }, "passed": { "type": "integer", "minimum": 0, "description": "passed and charged" }, "not_charged": { "type": "integer", "minimum": 0, "description": "failed and not charged" }, "charged": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what the buyer was charged" }, "covered_for_you": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what Teppi paid sellers for answers that failed" } } }, "page": { "type": "integer", "minimum": 0, "description": "the page" }, "orders": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string", "description": "the order" }, "kind": { "type": "string", "description": "via or plan" }, "status": { "type": "string", "description": "its status" }, "reason": { "type": [ "string", "null" ], "description": "why it did not pass" }, "capability": { "type": [ "object", "null" ], "description": "the endpoint" }, "plan_id": { "type": [ "string", "null" ], "description": "the plan" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what it was quoted" }, "charged": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "what was charged" }, "opened_at": { "type": "string", "description": "when it was opened" } } } } }, "required": [ "buyer", "totals", "page", "orders" ] } } } } } } }, "/v1/docs/extract": { "post": { "operationId": "extractDocument", "summary": "Returns structured json extracted from a public pdf or html document url. Use when you have a document link and need typed fields.", "tags": [ "pdf", "extract", "structured-json", "document" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "content_type": { "type": "string" }, "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "bytes": { "type": "integer", "minimum": 0 }, "pages": { "type": [ "integer", "null" ], "minimum": 1 }, "title": { "type": [ "string", "null" ] }, "headings": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1 }, "text": { "type": "string" } }, "required": [ "level", "text" ], "additionalProperties": false } }, "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string" }, "text": { "type": "string" } }, "required": [ "href", "text" ], "additionalProperties": false } }, "text": { "type": "string" }, "text_chars": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" } }, "required": [ "url", "content_type", "sha256", "bytes", "pages", "title", "headings", "links", "text", "text_chars", "truncated" ], "additionalProperties": false } } } }, "402": { "description": "payment required, terms in the body and the payment-required header" } }, "x-x402": { "amount": "0.020000", "asset": "USDC", "scheme": "exact", "networks": [ "eip155:8453" ] } } }, "/v1/companies/lookup": { "post": { "operationId": "lookupCompany", "summary": "Returns legal entities matching a company name or lei, with jurisdiction, status and registered city, as the global lei registry publishes them.", "tags": [ "company", "lei", "legal-entity", "lookup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "source": { "type": "string", "enum": [ "gleif" ] }, "matches": { "type": "array", "items": { "type": "object", "properties": { "lei": { "type": "string", "pattern": "^[A-Z0-9]{20}$" }, "legal_name": { "type": "string" }, "jurisdiction": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "registration_status": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "last_update": { "type": [ "string", "null" ] } }, "required": [ "lei", "legal_name", "jurisdiction", "status", "registration_status", "city", "country", "last_update" ], "additionalProperties": false } } }, "required": [ "query", "source", "matches" ], "additionalProperties": false } } } }, "402": { "description": "payment required, terms in the body and the payment-required header" } }, "x-x402": { "amount": "0.020000", "asset": "USDC", "scheme": "exact", "networks": [ "eip155:8453" ] } } }, "/v1/web/evidence": { "post": { "operationId": "webEvidence", "summary": "Returns source urls and verbatim quotations for a factual query, where every quote can be found at the url it cites.", "tags": [ "search", "citation", "quote", "evidence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 300 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "source": { "type": "string", "enum": [ "brave" ] }, "searched": { "type": "integer", "minimum": 0 }, "fetched": { "type": "integer", "minimum": 0 }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "pattern": "^https:\\/\\/" }, "title": { "type": [ "string", "null" ] }, "quote": { "type": "string", "minLength": 24, "maxLength": 2000 } }, "required": [ "url", "title", "quote" ], "additionalProperties": false } } }, "required": [ "query", "source", "searched", "fetched", "citations" ], "additionalProperties": false } } } }, "402": { "description": "payment required, terms in the body and the payment-required header" } }, "x-x402": { "amount": "0.020000", "asset": "USDC", "scheme": "exact", "networks": [ "eip155:8453" ] } } }, "/v1/research/brief": { "post": { "operationId": "researchBrief", "summary": "Returns a brief on a factual query made only of verbatim quotes from public pages, each numbered to the url it was taken from.", "tags": [ "research", "brief", "citation", "quote" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 300 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "brief": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "pattern": "^https:\\/\\/" }, "title": { "type": [ "string", "null" ] }, "quote": { "type": "string", "minLength": 24, "maxLength": 2000 } }, "required": [ "url", "title", "quote" ], "additionalProperties": false } } }, "required": [ "query", "brief", "citations" ], "additionalProperties": false } } } }, "402": { "description": "payment required, terms in the body and the payment-required header" } }, "x-x402": { "amount": "0.020000", "asset": "USDC", "scheme": "exact", "networks": [ "eip155:8453" ] } } } } }