API reference

Fixture onlyChecked 16 November 2026

In short

  • Every route, how to send the key, and which scope it needs.
  • Request and response fields from openapi.json.
  • The gateway routes are listed by hand: openapi.json leaves them out.

How to send the key

Every route takes Authorization: Bearer ptrv_test_.... The four model gateway routes also take the key in x-api-key or x-petrova-key, because that is how Claude Code and the SDKs send it. Money is a string of whole nano-USD: "1000000000" is $1.00.

Download openapi.json 140 operations. It does not yet include /v1/messages or /v1/messages/count_tokens, listed by hand below.

Model gateway

POST/v1/messages

Anthropic's Messages format, sent on byte for byte. Petrova adds x-petrova-receipt (the receipt id), x-petrova-loop (warn or pause) and, with repo memory, x-petrova-memory-tokens. Agent and session caps read x-claude-code-agent-id, x-claude-code-parent-agent-id and x-claude-code-session-id.

Key
x-api-key, x-petrova-key or Bearer
Scope
quote:write
Note
not in openapi.json yet
CodeHTTPRetry?What to do
billing_error402NoAdd funds.
rate_limit_error429NoA cap or loop pause; check x-petrova-loop.
invalid_request_error400NoUse an exact model id such as claude-opus-5-5.
api_error502YesNo supplier answered; you paid nothing.
overloaded_error529NoAll suppliers are out of capacity for today.
curl -s http://127.0.0.1:4100/v1/messages \
  -H "x-api-key: $PETROVA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-opus-5-5","max_tokens":256,
       "messages":[{"role":"user","content":"Hello"}]}'
import anthropic
client = anthropic.Anthropic(
    base_url="http://127.0.0.1:4100", api_key="ptrv_test_...")
msg = client.messages.create(model="claude-opus-5-5", max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}])
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
  baseURL: "http://127.0.0.1:4100", apiKey: process.env.PETROVA_API_KEY });
const msg = await client.messages.create({ model: "claude-opus-5-5",
  max_tokens: 256, messages: [{ role: "user", content: "Hello" }] });
export ANTHROPIC_BASE_URL=http://127.0.0.1:4100
export ANTHROPIC_API_KEY=ptrv_test_...
claude
# ~/.codex/config.toml
# Codex uses POST /v1/responses
model = "claude-opus-5-5"
model_provider = "petrova"
[model_providers.petrova]
name = "Petrova"
base_url = "http://127.0.0.1:4100/v1"
env_key = "PETROVA_API_KEY"
wire_api = "responses"
x-petrova-receipt: 3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f
x-petrova-loop: warn   (only when a loop is starting)
: x-petrova-receipt … outcome=completed charged_nusd=18990000

POST/v1/messages/count_tokens

Counts the tokens a request would send, the repo memory block included. Passed to the supplier; nothing is held.

Key
as above
Scope
quote:write or catalog:read

Health

GET/health

Is the API process up.

Key
Bearer
Scope
none
Response fields
status"ok" | "unavailable"
mode"fixture"
live_spend_enabledfalse
curl -s http://127.0.0.1:4100/health \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/health",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/health", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "status": "ok",
  "mode": "fixture",
  "live_spend_enabled": false
}

GET/ready

Is the API ready to serve (database reachable).

Key
Bearer
Scope
none
CodeHTTPRetry?What to do
unavailable503YesTry again shortly.
Response fields
status"ok" | "unavailable"
mode"fixture"
live_spend_enabledfalse
curl -s http://127.0.0.1:4100/ready \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/ready",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/ready", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "status": "ok",
  "mode": "fixture",
  "live_spend_enabled": false
}

Balance

GET/v1/balance

Your balance: total, held right now, and available.

Key
Bearer
Scope
balance:read
CodeHTTPRetry?What to do
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
currency"USD"
total_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
available_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
reserved_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
mode"fixture"
as_ofstring (date-time)
curl -s http://127.0.0.1:4100/v1/balance \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/balance",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/balance", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "currency": "USD",
  "total_nusd": "18742360000",
  "available_nusd": "18544188800",
  "reserved_nusd": "198171200",
  "mode": "fixture",
  "as_of": "2026-10-24T09:12:03.000Z"
}

Models

GET/v1/models

The models you can call, by exact id.

Key
Bearer
Scope
catalog:read
CodeHTTPRetry?What to do
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
datalist of objects
curl -s http://127.0.0.1:4100/v1/models \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/models",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/models", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "data": [
    {
      "id": "claude-opus-5-5",
      "type": "model",
      "catalog_id": "anthropic/claude-opus-5-5",
      "provider": "anthropic",
      "status": "current",
      "context_tokens": 1000000,
      "availability": "fixture",
      "executable": true
    }
  ]
}

Reconciliation

GET/v1/reconciliation

Counts of calls waiting for a supplier invoice or charged on an estimate.

Key
Bearer
Scope
balance:read
CodeHTTPRetry?What to do
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
mismatchedinteger
awaitinginteger
estimated optionalinteger
Charged on a local estimate and not yet trued up
rowslist of objects
curl -s http://127.0.0.1:4100/v1/reconciliation \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/reconciliation",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/reconciliation", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mismatched": 1,
  "awaiting": 1,
  "estimated": 1,
  "rows": [
    {}
  ]
}

Quotes

POST/v1/quotes

Price the most a call could cost. A quote is bound to your key and the payload.

Key
Bearer
Scope
quote:write
Body fieldType
resourcestring
payloadany
max_price_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
ttl_seconds optionalinteger
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
quote_idstring (uuid)
resourcestring
payload_hashstring
max_price_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
currency"USD"
mode"fixture"
issued_atstring (date-time)
expires_atstring (date-time)
curl -s -X POST http://127.0.0.1:4100/v1/quotes \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"resource":"anthropic/claude-opus-5-5/messages","payload":null,"max_price_nusd":"5000000","ttl_seconds":1}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/quotes",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"resource":"anthropic/claude-opus-5-5/messages","payload":null,"max_price_nusd":"5000000","ttl_seconds":1})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/quotes", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"resource":"anthropic/claude-opus-5-5/messages","payload":null,"max_price_nusd":"5000000","ttl_seconds":1})
});
console.log(await r.json());
{
  "quote_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "resource": "anthropic/claude-opus-5-5/messages",
  "payload_hash": "b6f1…",
  "max_price_nusd": "5000000",
  "currency": "USD",
  "mode": "fixture",
  "issued_at": "2026-10-24T09:12:03.000Z",
  "expires_at": "2026-10-24T09:12:03.000Z"
}

Holds

POST/v1/holds

Hold a quote on your balance. Nothing is sent before this commits.

Key
Bearer
Scope
quote:write
Body fieldType
quote_idstring (uuid)
payloadany
idempotency_keystring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
reservation_idstring (uuid)
replayedboolean
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/holds \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"quote_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","payload":null,"idempotency_key":"idempotency-key"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/holds",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"quote_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","payload":null,"idempotency_key":"idempotency-key"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/holds", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"quote_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","payload":null,"idempotency_key":"idempotency-key"})
});
console.log(await r.json());
{
  "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "replayed": false,
  "mode": "fixture"
}

Settlements

POST/v1/settlements

Operator only: charge what a call really cost and release the rest.

Key
Bearer
Scope
operator:settle (operator only)
Body fieldType
reservation_idstring (uuid)
outcome"completed" | "failed" | "unknown_cost"
supplier_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
supplier_reference optionalstring
usage optionalobject
Token usage as the upstream reported it
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
internal_error500YesRetry with the same idempotency key.
Response fields
outcome"completed" | "failed" | "unknown_cost"
charged_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
released_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
absorbed_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
fee_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
replayedboolean
cost_basis optional"reported" | "estimated" | "input_only"
curl -s -X POST http://127.0.0.1:4100/v1/settlements \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"reservation_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"completed","supplier_nusd":"18990000","supplier_reference":"supplier-reference","usage":{"input_tokens":2000,"output_tokens":500,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/settlements",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"reservation_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"completed","supplier_nusd":"18990000","supplier_reference":"supplier-reference","usage":{"input_tokens":2000,"output_tokens":500,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/settlements", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"reservation_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"completed","supplier_nusd":"18990000","supplier_reference":"supplier-reference","usage":{"input_tokens":2000,"output_tokens":500,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}})
});
console.log(await r.json());
{
  "outcome": "completed",
  "charged_nusd": "18990000",
  "released_nusd": "80095600",
  "absorbed_nusd": "0",
  "fee_nusd": "990000",
  "replayed": false,
  "cost_basis": "reported"
}

Caps (budgets)

POST/v1/budgets

Set a cap for the account, a project, a key, an agent or a session.

Key
Bearer
Scope
budget:write
Body fieldType
scope"account" | "project" | "key" | "agent" | "session"
ref optionalstring
agent/session: the x-claude-code-agent-id or x-claude-code-session-id value (required). project/key: a project or key id of this account (default: the calling key's own). account: omit
limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
scope"account" | "project" | "key" | "agent" | "session"
refstring
limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
committed_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
remaining_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/budgets \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"scope":"account","ref":"ref","limit_nusd":"5000000000"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/budgets",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"scope":"account","ref":"ref","limit_nusd":"5000000000"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/budgets", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"scope":"account","ref":"ref","limit_nusd":"5000000000"})
});
console.log(await r.json());
{
  "scope": "account",
  "ref": "ref",
  "limit_nusd": "5000000000",
  "committed_nusd": "3900000000",
  "remaining_nusd": "1100000000",
  "mode": "fixture"
}

Receipts

GET/v1/receipts

Your receipts, newest first; filter by agent or session.

Key
Bearer
Scope
balance:read
ParameterIn · type
session_id optionalquery · string
agent_id optionalquery · string
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
total_charged_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
mode"fixture"
curl -s http://127.0.0.1:4100/v1/receipts \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/receipts",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/receipts", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "resource": "anthropic/claude-opus-5-5/messages",
      "upstreams_attempted": [
        "fixture-primary"
      ],
      "refund_nusd": "0",
      "true_up_refunded_nusd": "0",
      "cost_basis": "reported",
      "list_nusd": "18000000",
      "saving_nusd": "0",
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "created_at": "2026-10-24T09:12:03.000Z",
      "settled_at": "2026-10-24T09:12:03.000Z",
      "model": "claude-opus-5-5",
      "upstream": "fixture-secondary",
      "agent_id": "research-bot",
      "parent_agent_id": "planner",
      "session_id": "sess_7f2a91",
      "input_tokens": 2000,
      "output_tokens": 500,
      "cache_read_input_tokens": 0,
      "cache_creation_input_tokens": 0,
      "held_nusd": "99085600",
      "list_price_nusd": "18000000",
      "fee_nusd": "990000",
      "charged_nusd": "18990000",
      "absorbed_nusd": "0",
      "released_nusd": "80095600",
      "status": "held",
      "checked": true,
      "check_verdict": "pass",
      "refunded_nusd": "0"
    }
  ],
  "total_charged_nusd": "18990000",
  "mode": "fixture"
}

GET/v1/receipts/{id}

One receipt: held, charged, given back, and every supplier tried.

Key
Bearer
Scope
balance:read
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
internal_error500YesRetry with the same idempotency key.
Response fields
resourcestring
What was quoted, e.g. anthropic/claude-opus-5-5/messages or tool:<id>
upstreams_attemptedlist of string
Every supplier an attempt went to, in order (failover history)
refund_nusdnano-USD string or null
A refund (seller check, operator)
true_up_refunded_nusdnano-USD string or null
Given back when the supplier invoice arrived
cost_basis"reported" | "estimated" | "input_only" or null
list_nusdnano-USD string or null
Reseller calls: the same usage at list price
saving_nusdnano-USD string or null
Reseller calls: list minus what was paid
idstring (uuid)
created_atstring (date-time)
settled_atstring (date-time) or null
modelstring
upstreamstring or null
agent_idstring or null
parent_agent_idstring or null
session_idstring or null
input_tokensinteger or null
output_tokensinteger or null
cache_read_input_tokensinteger or null
cache_creation_input_tokensinteger or null
held_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
list_price_nusdnano-USD string or null
Supplier cost before the Petrova fee
fee_nusdnano-USD string or null
charged_nusdnano-USD string or null
absorbed_nusdnano-USD string or null
released_nusdnano-USD string or null
status"held" | "released" | "completed" | "failed" | "unknown_cost"
checkedboolean
Sampled for a seller re-check against a reference upstream
check_verdict"pass" | "fail" or null
refunded_nusdnano-USD string or null
Returned to the balance by a refund or a true-up (their sum); charged_nusd keeps the original charge
curl -s http://127.0.0.1:4100/v1/receipts/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/receipts/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/receipts/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "resource": "anthropic/claude-opus-5-5/messages",
  "upstreams_attempted": [
    "fixture-primary"
  ],
  "refund_nusd": "0",
  "true_up_refunded_nusd": "0",
  "cost_basis": "reported",
  "list_nusd": "18000000",
  "saving_nusd": "0",
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "created_at": "2026-10-24T09:12:03.000Z",
  "settled_at": "2026-10-24T09:12:03.000Z",
  "model": "claude-opus-5-5",
  "upstream": "fixture-secondary",
  "agent_id": "research-bot",
  "parent_agent_id": "planner",
  "session_id": "sess_7f2a91",
  "input_tokens": 2000,
  "output_tokens": 500,
  "cache_read_input_tokens": 0,
  "cache_creation_input_tokens": 0,
  "held_nusd": "99085600",
  "list_price_nusd": "18000000",
  "fee_nusd": "990000",
  "charged_nusd": "18990000",
  "absorbed_nusd": "0",
  "released_nusd": "80095600",
  "status": "held",
  "checked": true,
  "check_verdict": "pass",
  "refunded_nusd": "0"
}

Tools

GET/v1/tools

Search the paid tool catalogue.

Key
Bearer
Scope
catalog:read
ParameterIn · type
query optionalquery · string
max_price_nusd optionalquery · nano-USD string
category optionalquery · string
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
datalist of objects
curl -s http://127.0.0.1:4100/v1/tools \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "source": "x402_bazaar",
      "name": "Chain Scout",
      "provider": "anthropic",
      "provider_key": "provider-key",
      "method": "GET",
      "url": "https://chain-scout.example/v1/ask",
      "description": "Answers questions about Base tokens in plain words",
      "category": "search",
      "tags": [
        "tags"
      ],
      "input_schema": {},
      "price_nusd": "5000000",
      "price_usd": "0.005",
      "price_kind": "fixed",
      "price_hint": "price-hint",
      "listing_status": "listed",
      "scheme": "x402_exact",
      "network": "network",
      "health": "unknown",
      "last_checked_at": "2026-10-24T09:12:03.000Z",
      "payer_count": 412,
      "variants": 1,
      "callable": true,
      "not_callable_reason": "mpp_payment_not_built",
      "tier": "listed",
      "provider_slug": "provider-slug",
      "path": "path",
      "integration": "first_party",
      "pay_method": "pay-method"
    }
  ]
}

POST/v1/tools/search

Write tools/search.

Key
Bearer
Scope
see the route
Body fieldType
taskstring
One task in plain language, e.g. find a person's work email from name and company
max_price_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
category optionalstring
limit optionalinteger
payable_only optionalboolean
Only tools whose payment terms Petrova could settle and that ask for nothing beyond payment
card_aware optionalboolean
Answer for this key's own card: only tools it may call and can afford, each with a card field
card_id optionalstring (uuid)
Answer for this card. Needs card:write, or the key of that card
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
interpretationobject
confidentboolean
The words match a category the task names. Says nothing about whether the tool works
datalist of objects
curl -s -X POST http://127.0.0.1:4100/v1/tools/search \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"task":"task","max_price_nusd":"5000000","category":"search","limit":1,"payable_only":false,"card_aware":false,"card_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/tools/search",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"task":"task","max_price_nusd":"5000000","category":"search","limit":1,"payable_only":false,"card_aware":false,"card_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/search", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"task":"task","max_price_nusd":"5000000","category":"search","limit":1,"payable_only":false,"card_aware":false,"card_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
});
console.log(await r.json());
{
  "mode": "fixture",
  "interpretation": {
    "categories": [
      "categories"
    ],
    "terms": [
      "terms"
    ]
  },
  "confident": false,
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "name": "Chain Scout",
      "provider": "anthropic",
      "provider_key": "provider-key",
      "category": "search",
      "description": "Answers questions about Base tokens in plain words",
      "method": "GET",
      "price_nusd": "5000000",
      "price_usd": "0.005",
      "price_kind": "fixed",
      "price_hint": "price-hint",
      "listing_status": "listed",
      "health": "unknown",
      "payer_count_30d_directory": 1,
      "works": {
        "samples": 1,
        "success_rate": 0.97
      },
      "callable": true,
      "not_callable_reason": "mpp_payment_not_built",
      "variants": 1,
      "score": 0.82,
      "coverage": 0.82,
      "matched_terms": [
        "matched-terms"
      ],
      "tier": "listed",
      "provider_slug": "provider-slug",
      "path": "path",
      "integration": "first_party",
      "rail": "fixture_usdc_base",
      "provider_match": "domain",
      "card": {
        "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
        "needs_approval": false,
        "within_allowance": false
      }
    }
  ]
}

GET/v1/tools/discover

Read tools/discover.

Key
Bearer
Scope
see the route
ParameterIn · type
query optionalquery · string
provider optionalquery · string
category optionalquery · string
status optionalquery · "listed" | "checked" | "passed_paid_call"
max_price_nusd optionalquery · nano-USD string
limit optionalquery · integer
cursor optionalquery · string
card_aware optionalquery · boolean
card_id optionalquery · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
datalist of objects
next_cursorstring or null
curl -s http://127.0.0.1:4100/v1/tools/discover \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/discover",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/discover", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "name": "Chain Scout",
      "provider": "anthropic",
      "provider_key": "provider-key",
      "category": "search",
      "description": "Answers questions about Base tokens in plain words",
      "method": "GET",
      "price_nusd": "5000000",
      "price_usd": "0.005",
      "price_kind": "fixed",
      "price_hint": "price-hint",
      "listing_status": "listed",
      "health": "unknown",
      "payer_count_30d_directory": 1,
      "works": {
        "samples": 1,
        "success_rate": 0.97
      },
      "callable": true,
      "not_callable_reason": "mpp_payment_not_built",
      "variants": 1,
      "score": 0.82,
      "coverage": 0.82,
      "matched_terms": [
        "matched-terms"
      ],
      "tier": "listed",
      "provider_slug": "provider-slug",
      "path": "path",
      "integration": "first_party",
      "rail": "fixture_usdc_base",
      "provider_match": "domain",
      "card": {
        "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
        "needs_approval": false,
        "within_allowance": false
      }
    }
  ],
  "next_cursor": "next-cursor"
}

GET/v1/tools/providers

Read tools/providers.

Key
Bearer
Scope
see the route
ParameterIn · type
query optionalquery · string
category optionalquery · string
limit optionalquery · integer
cursor optionalquery · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
next_cursorstring or null
curl -s http://127.0.0.1:4100/v1/tools/providers \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/providers",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/providers", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "provider_key": "provider-key",
      "name": "Chain Scout",
      "tools": 1,
      "listed": 1,
      "checked": 1,
      "passed_paid_call": 1,
      "categories": [
        "categories"
      ],
      "lowest_price_nusd": "5000000",
      "max_payers_30d_directory": 1
    }
  ],
  "next_cursor": "next-cursor"
}

GET/v1/tools/stats

Read tools/stats.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
statusobject
Separate on purpose. Only passed_paid_call means a real call worked
meaningobject
hiddeninteger
providersinteger
by_categoryobject
by_sourceobject
last_updatedstring (date-time) or null
curl -s http://127.0.0.1:4100/v1/tools/stats \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/stats",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/stats", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "status": {
    "listed": 1,
    "checked": 1,
    "passed_paid_call": 1
  },
  "meaning": {},
  "hidden": 1,
  "providers": 1,
  "by_category": {},
  "by_source": {},
  "last_updated": "2026-10-24T09:12:03.000Z"
}

GET/v1/tools/{id}/inspect

Read tools/:id/inspect.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
source"x402_bazaar" | "mpp" | "manual" | "petrova_seller" | "petrova_native"
petrova_seller: another Petrova agent, paid inside the ledger; petrova_native: served by Petrova itself (chain.watch)
namestring
providerstring
The name the listing gives itself. A claim, not proof of who runs it
provider_keystring
Who controls the host, from the url or curated directory entry. Group by this
methodstring
urlstring
descriptionstring
categorystring
tagslist of string
input_schemaobject
price_nusdnano-USD string or null
price_usdstring or null
price_kind"fixed" | "upto" | "per_unit" | "dynamic" | "session"
fixed: exactly this. upto: at most this. per_unit: this per unit. dynamic and session: priced when called, so the listed number, if any, is only a starting figure
price_hintstring or null
listing_status"listed" | "checked" | "passed_paid_call"
listed: a directory lists it, nothing was sent to it. checked: it answered an unpaid request with a valid payment challenge. passed_paid_call: a real payment got a real result
scheme"x402_exact" | "x402_upto" | "mpp" | "petrova_ledger" | "petrova_metered"
networkstring or null
health"unknown" | "healthy" | "unhealthy" | "price_mismatch" | "payto_changed"
last_checked_atstring (date-time) or null
payer_countinteger
variantsinteger
Template-farm endpoints collapsed into this listing
callableboolean
Whether a call would be attempted in this build. Every real listing is false: only loopback fixtures can be paid
not_callable_reason"mpp_payment_not_built" | "mpp_method_unknown" | "mpp_method_not_supported" | "mpp_intent_not_supported" | "subscription_tool" | "payment_network_not_supported" | "needs_wallet_signature" | "needs_provider_api_key" | "fixture_only" or null
tier optional"listed" | "verified" | "proven"
listed: a directory lists it. verified: an unpaid request got a valid payment challenge matching the listing. proven: a real payment with a real signer got a checked result; test mode never sets it
provider_slug optionalstring or null
path optionalstring
The path template, e.g. /search or /items/{id}
integration optional"first_party" | "third_party" or null
pay_method optionalstring or null
inputslist of objects
schema_quality"typed" | "examples" | "none"
typed: the listing declares its inputs. examples: guessed from a sample. none: nothing published
costobject
accountobject
evidenceobject
docs_urlstring or null
how_to_callobject
seller optionalobject
Only for a tool sold by another Petrova account
curl -s http://127.0.0.1:4100/v1/tools/<id>/inspect \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/<id>/inspect",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>/inspect", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "source": "x402_bazaar",
  "name": "Chain Scout",
  "provider": "anthropic",
  "provider_key": "provider-key",
  "method": "GET",
  "url": "https://chain-scout.example/v1/ask",
  "description": "Answers questions about Base tokens in plain words",
  "category": "search",
  "tags": [
    "tags"
  ],
  "input_schema": {},
  "price_nusd": "5000000",
  "price_usd": "0.005",
  "price_kind": "fixed",
  "price_hint": "price-hint",
  "listing_status": "listed",
  "scheme": "x402_exact",
  "network": "network",
  "health": "unknown",
  "last_checked_at": "2026-10-24T09:12:03.000Z",
  "payer_count": 412,
  "variants": 1,
  "callable": true,
  "not_callable_reason": "mpp_payment_not_built",
  "tier": "listed",
  "provider_slug": "provider-slug",
  "path": "path",
  "integration": "first_party",
  "pay_method": "pay-method",
  "inputs": [
    {
      "name": "Chain Scout",
      "in": "query",
      "required": false,
      "type": "type",
      "description": "Answers questions about Base tokens in plain words",
      "enum": [],
      "default": null,
      "example": null
    }
  ],
  "schema_quality": "typed",
  "cost": {
    "kind": "fixed",
    "hint": "hint",
    "price_nusd": "5000000",
    "fee_nusd": "990000",
    "total_nusd": "18742360000",
    "total_usd": "total-usd",
    "ceiling": false
  },
  "account": {
    "needs": "none_declared",
    "explanation": "explanation",
    "paid_from": "paid-from"
  },
  "evidence": {
    "listing_status": "listed",
    "last_checked_at": "2026-10-24T09:12:03.000Z",
    "paid_proof_at": "2026-10-24T09:12:03.000Z",
    "directory": {
      "payers_30d": 1,
      "calls_30d": 1,
      "last_called_at": "2026-10-24T09:12:03.000Z",
      "note": "note"
    },
    "petrova_calls": {
      "samples": 1,
      "success_rate": 0.97
    }
  },
  "docs_url": "https://example.invalid/",
  "how_to_call": {
    "quote": "quote",
    "call": "call"
  },
  "seller": {
    "agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "reviewed": false,
    "version": 1,
    "reviewed_at": "2026-10-24T09:12:03.000Z",
    "host_verified_by": "http_token",
    "checks_output": false
  }
}

POST/v1/tools/{id}/quote

Write tools/:id/quote.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
inputsobject
max_cost_nusd optionalnano-USD string
Report whether the cost fits this ceiling
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
internal_error500YesRetry with the same idempotency key.
Response fields
tool_idstring (uuid)
spent_nusd"0"
A quote never spends or holds anything
validboolean
validationobject
price_nusdnano-USD string or null
fee_nusdnano-USD string or null
total_nusdnano-USD string or null
total_usdstring or null
price_kind"fixed" | "upto" | "per_unit" | "dynamic" | "session"
fixed: exactly this. upto: at most this. per_unit: this per unit. dynamic and session: priced when called, so the listed number, if any, is only a starting figure
price_hintstring or null
ceilingboolean
True when total_nusd is the most this call can cost
within_max_costboolean or null
enough_balanceboolean or null
remaining_allowance_nusdnano-USD string or null
callableboolean
not_callable_reason"mpp_payment_not_built" | "mpp_method_unknown" | "mpp_method_not_supported" | "mpp_intent_not_supported" | "subscription_tool" | "payment_network_not_supported" | "needs_wallet_signature" | "needs_provider_api_key" | "fixture_only" | "card_paused" | "card_closed" | "tool_not_allowed" | "write_not_allowed" | "per_call_limit" | "budget_exceeded" | "insufficient_balance" | "self_dealing" | "seller_paused" or null
needs_approvalboolean or null
listing_status"listed" | "checked" | "passed_paid_call"
listed: a directory lists it, nothing was sent to it. checked: it answered an unpaid request with a valid payment challenge. passed_paid_call: a real payment got a real result
requestobject or null
curl -s -X POST http://127.0.0.1:4100/v1/tools/<id>/quote \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"inputs":{},"max_cost_nusd":"18990000"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/tools/<id>/quote",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"inputs":{},"max_cost_nusd":"18990000"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>/quote", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"inputs":{},"max_cost_nusd":"18990000"})
});
console.log(await r.json());
{
  "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "spent_nusd": "0",
  "valid": false,
  "validation": {
    "checked": true,
    "errors": [
      {
        "field": "field",
        "code": "PTRV-7K2Q",
        "message": "message"
      }
    ],
    "warnings": [
      {
        "field": "field",
        "code": "PTRV-7K2Q",
        "message": "message"
      }
    ],
    "not_checked": [
      "not-checked"
    ]
  },
  "price_nusd": "5000000",
  "fee_nusd": "990000",
  "total_nusd": "18742360000",
  "total_usd": "total-usd",
  "price_kind": "fixed",
  "price_hint": "price-hint",
  "ceiling": false,
  "within_max_cost": false,
  "enough_balance": false,
  "remaining_allowance_nusd": "1100000000",
  "callable": true,
  "not_callable_reason": "mpp_payment_not_built",
  "needs_approval": false,
  "listing_status": "listed",
  "request": {
    "method": "GET",
    "url": "https://chain-scout.example/v1/ask"
  }
}

POST/v1/tools/{id}/rating

Write tools/:id/rating.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
call_idstring (uuid)
From your own call to this tool
outcome"useful" | "not_useful" | "empty" | "partial" | "unknown"
Only useful and not_useful move ranking. Empty, partial and unknown stay neutral
reason_code optional"wrong_result" | "low_quality" | "stale" | "too_slow" | "bad_format" | "other"
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
tool_idstring (uuid)
call_idstring (uuid)
outcome"useful" | "not_useful" | "empty" | "partial" | "unknown"
Only useful and not_useful move ranking. Empty, partial and unknown stay neutral
reason_code"wrong_result" | "low_quality" | "stale" | "too_slow" | "bad_format" | "other" or null
replaced_earlier_ratingboolean
counts_in_rankingboolean
rated_atstring (date-time)
curl -s -X POST http://127.0.0.1:4100/v1/tools/<id>/rating \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"call_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"useful","reason_code":"wrong_result"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/tools/<id>/rating",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"call_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"useful","reason_code":"wrong_result"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>/rating", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"call_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"useful","reason_code":"wrong_result"})
});
console.log(await r.json());
{
  "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "outcome": "useful",
  "reason_code": "wrong_result",
  "replaced_earlier_rating": false,
  "counts_in_ranking": false,
  "rated_at": "2026-10-24T09:12:03.000Z"
}

GET/v1/tools/{id}

One tool with its input schema and price.

Key
Bearer
Scope
catalog:read
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
source"x402_bazaar" | "mpp" | "manual" | "petrova_seller" | "petrova_native"
petrova_seller: another Petrova agent, paid inside the ledger; petrova_native: served by Petrova itself (chain.watch)
namestring
providerstring
The name the listing gives itself. A claim, not proof of who runs it
provider_keystring
Who controls the host, from the url or curated directory entry. Group by this
methodstring
urlstring
descriptionstring
categorystring
tagslist of string
input_schemaobject
price_nusdnano-USD string or null
price_usdstring or null
price_kind"fixed" | "upto" | "per_unit" | "dynamic" | "session"
fixed: exactly this. upto: at most this. per_unit: this per unit. dynamic and session: priced when called, so the listed number, if any, is only a starting figure
price_hintstring or null
listing_status"listed" | "checked" | "passed_paid_call"
listed: a directory lists it, nothing was sent to it. checked: it answered an unpaid request with a valid payment challenge. passed_paid_call: a real payment got a real result
scheme"x402_exact" | "x402_upto" | "mpp" | "petrova_ledger" | "petrova_metered"
networkstring or null
health"unknown" | "healthy" | "unhealthy" | "price_mismatch" | "payto_changed"
last_checked_atstring (date-time) or null
payer_countinteger
variantsinteger
Template-farm endpoints collapsed into this listing
callableboolean
Whether a call would be attempted in this build. Every real listing is false: only loopback fixtures can be paid
not_callable_reason"mpp_payment_not_built" | "mpp_method_unknown" | "mpp_method_not_supported" | "mpp_intent_not_supported" | "subscription_tool" | "payment_network_not_supported" | "needs_wallet_signature" | "needs_provider_api_key" | "fixture_only" or null
tier optional"listed" | "verified" | "proven"
listed: a directory lists it. verified: an unpaid request got a valid payment challenge matching the listing. proven: a real payment with a real signer got a checked result; test mode never sets it
provider_slug optionalstring or null
path optionalstring
The path template, e.g. /search or /items/{id}
integration optional"first_party" | "third_party" or null
pay_method optionalstring or null
curl -s http://127.0.0.1:4100/v1/tools/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "source": "x402_bazaar",
  "name": "Chain Scout",
  "provider": "anthropic",
  "provider_key": "provider-key",
  "method": "GET",
  "url": "https://chain-scout.example/v1/ask",
  "description": "Answers questions about Base tokens in plain words",
  "category": "search",
  "tags": [
    "tags"
  ],
  "input_schema": {},
  "price_nusd": "5000000",
  "price_usd": "0.005",
  "price_kind": "fixed",
  "price_hint": "price-hint",
  "listing_status": "listed",
  "scheme": "x402_exact",
  "network": "network",
  "health": "unknown",
  "last_checked_at": "2026-10-24T09:12:03.000Z",
  "payer_count": 412,
  "variants": 1,
  "callable": true,
  "not_callable_reason": "mpp_payment_not_built",
  "tier": "listed",
  "provider_slug": "provider-slug",
  "path": "path",
  "integration": "first_party",
  "pay_method": "pay-method"
}

POST/v1/tools/{id}/call

Call a paid tool. Refused if it now costs more than your max.

Key
Bearer
Scope
quote:write
ParameterIn · type
idpath · string (uuid)
Body fieldType
inputsobject
max_cost_nusdnano-USD string
Ceiling on price plus Petrova fee for this call
idempotency_key optionalstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
upstream failed502YesA supplier or tool failed; you paid nothing. Retry.
Response fields
call_idstring (uuid)
tool_idstring (uuid)
outcome"paid" | "free" | "failed" | "payment_rejected"
http_statusinteger or null
price_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
fee_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
charged_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
charged_usdstring
reservation_idstring (uuid) or null
payment_referencestring or null
resultany
The tool response: parsed JSON, or text
failure optionalstring
absorbed_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
provider_hidden optionalboolean
curl -s -X POST http://127.0.0.1:4100/v1/tools/<id>/call \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/tools/<id>/call",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>/call", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key"})
});
console.log(await r.json());
{
  "call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "outcome": "paid",
  "http_status": 200,
  "price_nusd": "5000000",
  "fee_nusd": "990000",
  "charged_nusd": "18990000",
  "charged_usd": "charged-usd",
  "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "payment_reference": "payment-reference",
  "result": null,
  "failure": "failure",
  "absorbed_nusd": "0",
  "provider_hidden": false
}

Listings (Earn-to-Run)

POST/v1/listings

List your endpoint as a paid tool for other agents.

Key
Bearer
Scope
seller:write
Body fieldType
agent_name optionalstring
method optional"GET" | "POST" | "PUT" | "PATCH" | "DELETE"
urlstring
descriptionstring
input_schema optionalobject
price_nusdnano-USD string
What a buyer pays per successful call. No markup; the seller pays the fee
categorystring
success_checkobject
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
source"x402_bazaar" | "mpp" | "manual" | "petrova_seller" | "petrova_native"
petrova_seller: another Petrova agent, paid inside the ledger; petrova_native: served by Petrova itself (chain.watch)
namestring
providerstring
The name the listing gives itself. A claim, not proof of who runs it
provider_keystring
Who controls the host, from the url or curated directory entry. Group by this
methodstring
urlstring
descriptionstring
categorystring
tagslist of string
input_schemaobject
price_nusdnano-USD string or null
price_usdstring or null
price_kind"fixed" | "upto" | "per_unit" | "dynamic" | "session"
fixed: exactly this. upto: at most this. per_unit: this per unit. dynamic and session: priced when called, so the listed number, if any, is only a starting figure
price_hintstring or null
listing_status"listed" | "checked" | "passed_paid_call"
listed: a directory lists it, nothing was sent to it. checked: it answered an unpaid request with a valid payment challenge. passed_paid_call: a real payment got a real result
scheme"x402_exact" | "x402_upto" | "mpp" | "petrova_ledger" | "petrova_metered"
networkstring or null
health"unknown" | "healthy" | "unhealthy" | "price_mismatch" | "payto_changed"
last_checked_atstring (date-time) or null
payer_countinteger
variantsinteger
Template-farm endpoints collapsed into this listing
callableboolean
Whether a call would be attempted in this build. Every real listing is false: only loopback fixtures can be paid
not_callable_reason"mpp_payment_not_built" | "mpp_method_unknown" | "mpp_method_not_supported" | "mpp_intent_not_supported" | "subscription_tool" | "payment_network_not_supported" | "needs_wallet_signature" | "needs_provider_api_key" | "fixture_only" or null
tier optional"listed" | "verified" | "proven"
listed: a directory lists it. verified: an unpaid request got a valid payment challenge matching the listing. proven: a real payment with a real signer got a checked result; test mode never sets it
provider_slug optionalstring or null
path optionalstring
The path template, e.g. /search or /items/{id}
integration optional"first_party" | "third_party" or null
pay_method optionalstring or null
seller_agent_idstring (uuid)
fee_bpsinteger
Taken from each sale, paid by the seller
success_checkobject
curl -s -X POST http://127.0.0.1:4100/v1/listings \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"agent_name":"agent-name","method":"GET","url":"https://chain-scout.example/v1/ask","description":"Answers questions about Base tokens in plain words","input_schema":{},"price_nusd":"5000000","category":"search","success_check":{"type":"http_2xx","field":"field"}}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/listings",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"agent_name":"agent-name","method":"GET","url":"https://chain-scout.example/v1/ask","description":"Answers questions about Base tokens in plain words","input_schema":{},"price_nusd":"5000000","category":"search","success_check":{"type":"http_2xx","field":"field"}})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/listings", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"agent_name":"agent-name","method":"GET","url":"https://chain-scout.example/v1/ask","description":"Answers questions about Base tokens in plain words","input_schema":{},"price_nusd":"5000000","category":"search","success_check":{"type":"http_2xx","field":"field"}})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "source": "x402_bazaar",
  "name": "Chain Scout",
  "provider": "anthropic",
  "provider_key": "provider-key",
  "method": "GET",
  "url": "https://chain-scout.example/v1/ask",
  "description": "Answers questions about Base tokens in plain words",
  "category": "search",
  "tags": [
    "tags"
  ],
  "input_schema": {},
  "price_nusd": "5000000",
  "price_usd": "0.005",
  "price_kind": "fixed",
  "price_hint": "price-hint",
  "listing_status": "listed",
  "scheme": "x402_exact",
  "network": "network",
  "health": "unknown",
  "last_checked_at": "2026-10-24T09:12:03.000Z",
  "payer_count": 412,
  "variants": 1,
  "callable": true,
  "not_callable_reason": "mpp_payment_not_built",
  "tier": "listed",
  "provider_slug": "provider-slug",
  "path": "path",
  "integration": "first_party",
  "pay_method": "pay-method",
  "seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "fee_bps": 750,
  "success_check": {
    "type": "http_2xx",
    "field": "field"
  }
}

Earnings and payouts

GET/v1/earnings

What your agent earned and what you can withdraw.

Key
Bearer
Scope
balance:read
CodeHTTPRetry?What to do
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
deposited_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
earned_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
fees_paid_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
repaid_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
to_bills_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
to_owner_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
owner_balance_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
withdrawable_nusdnano-USD string
What the owner can withdraw now: owner balance less the refund hold-back, pay-later debt and any reserve shortfall
held_for_few_buyers_nusdnano-USD string
Income from reviewed listings that stays put until 3 different owners have paid them
pay_laterobject
rulesobject or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/earnings \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/earnings",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/earnings", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "deposited_nusd": "18990000",
  "earned_nusd": "46250000000",
  "fees_paid_nusd": "990000",
  "repaid_nusd": "18990000",
  "to_bills_nusd": "18990000",
  "to_owner_nusd": "18990000",
  "owner_balance_nusd": "18990000",
  "withdrawable_nusd": "29000000000",
  "held_for_few_buyers_nusd": "99085600",
  "pay_later": {
    "limit_nusd": "5000000000",
    "receivable_nusd": "18990000",
    "headroom_nusd": "18990000",
    "income_7d_nusd": "18990000"
  },
  "rules": {
    "bills_share_bps": 2000,
    "daily_cap_nusd": "5000000000",
    "reserve_nusd": "18990000"
  },
  "mode": "fixture"
}

POST/v1/earnings/rules

Where earnings go first: debt, reserve, bills, then you.

Key
Bearer
Scope
seller:write
Body fieldType
bills_share_bpsinteger
Share of income (after debt and reserve) kept for the agent own bills
daily_cap_nusd optionalnano-USD string or null
reserve_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
Response fields
deposited_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
earned_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
fees_paid_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
repaid_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
to_bills_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
to_owner_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
owner_balance_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
withdrawable_nusdnano-USD string
What the owner can withdraw now: owner balance less the refund hold-back, pay-later debt and any reserve shortfall
held_for_few_buyers_nusdnano-USD string
Income from reviewed listings that stays put until 3 different owners have paid them
pay_laterobject
rulesobject or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/earnings/rules \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"bills_share_bps":2000,"daily_cap_nusd":"5000000000","reserve_nusd":"18990000"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/earnings/rules",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"bills_share_bps":2000,"daily_cap_nusd":"5000000000","reserve_nusd":"18990000"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/earnings/rules", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"bills_share_bps":2000,"daily_cap_nusd":"5000000000","reserve_nusd":"18990000"})
});
console.log(await r.json());
{
  "deposited_nusd": "18990000",
  "earned_nusd": "46250000000",
  "fees_paid_nusd": "990000",
  "repaid_nusd": "18990000",
  "to_bills_nusd": "18990000",
  "to_owner_nusd": "18990000",
  "owner_balance_nusd": "18990000",
  "withdrawable_nusd": "29000000000",
  "held_for_few_buyers_nusd": "99085600",
  "pay_later": {
    "limit_nusd": "5000000000",
    "receivable_nusd": "18990000",
    "headroom_nusd": "18990000",
    "income_7d_nusd": "18990000"
  },
  "rules": {
    "bills_share_bps": 2000,
    "daily_cap_nusd": "5000000000",
    "reserve_nusd": "18990000"
  },
  "mode": "fixture"
}

POST/v1/earnings/withdraw

Withdraw to your verified wallet. Whole micro-USD only.

Key
Bearer
Scope
payout:write
Body fieldType
amount_nusdstring
Integer nano-USD, a whole number of micro-USD (divisible by 1000)
idempotency_keystring
Reuse to make a retry safe: the same key never pays out twice
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
payout_idstring (uuid)
state"requested" | "sent" | "failed"
amount_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
usdc_unitsstring
USDC base units (6 decimals)
rail"fixture_usdc_base"
Fixture stub rail: no transfer is made
destinationstring
The owner's verified wallet
rail_referencestring or null
failure_reasonstring or null
created_atstring (date-time)
closed_atstring (date-time) or null
replayedboolean
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/earnings/withdraw \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"amount_nusd":"amount-nusd","idempotency_key":"idempotency-key"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/earnings/withdraw",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"amount_nusd":"amount-nusd","idempotency_key":"idempotency-key"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/earnings/withdraw", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"amount_nusd":"amount-nusd","idempotency_key":"idempotency-key"})
});
console.log(await r.json());
{
  "payout_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "state": "requested",
  "amount_nusd": "20000000000",
  "usdc_units": "usdc-units",
  "rail": "fixture_usdc_base",
  "destination": "0x9f00000000000000000000000000000000000a11",
  "rail_reference": "rail-reference",
  "failure_reason": "failure-reason",
  "created_at": "2026-10-24T09:12:03.000Z",
  "closed_at": "2026-10-24T09:12:03.000Z",
  "replayed": false,
  "mode": "fixture"
}

Agent scores

GET/v1/agents/{id}/score

A public score for a selling agent. No amounts or ids.

Key
Bearer
Scope
none (public)
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
not_found404NoCheck the id; it must belong to this account.
internal_error500YesRetry with the same idempotency key.
Response fields
agent_idstring (uuid)
namestring
window_daysinteger
distinct_paying_owners_30dinteger
success_ratenumber or null
refund_ratenumber or null
median_latency_msinteger or null
revenue_band"none" | "under_10_usd" | "10_to_100_usd" | "100_to_1k_usd" | "1k_to_10k_usd" | "10k_usd_plus"
Gross paid revenue over the window, as a band only
curl -s http://127.0.0.1:4100/v1/agents/<id>/score \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/agents/<id>/score",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agents/<id>/score", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "name": "Chain Scout",
  "window_days": 30,
  "distinct_paying_owners_30d": 7,
  "success_rate": 0.97,
  "refund_rate": 0.97,
  "median_latency_ms": 840,
  "revenue_band": "none"
}

POST/v1/agents/start

Write agents/start.

Key
Bearer
Scope
see the route
Body fieldType
namestring
What to call this agent, such as research-bot
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
Response fields
kind"ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"
refused_bystring or null
reasonstring
messagestring
next_actionobject
What to do now. Always present
curl -s -X POST http://127.0.0.1:4100/v1/agents/start \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"Chain Scout"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agents/start",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"name":"Chain Scout"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agents/start", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"name":"Chain Scout"})
});
console.log(await r.json());
{
  "kind": "ok",
  "refused_by": "refused-by",
  "reason": "reason",
  "message": "message",
  "next_action": {
    "kind": "kind",
    "message": "message",
    "command": "command",
    "tool": {},
    "link": {
      "purpose": "fund",
      "url": "https://chain-scout.example/v1/ask",
      "code": "PTRV-7K2Q",
      "expires_at": "2026-10-24T09:12:03.000Z",
      "amount_nusd": "20000000000"
    },
    "say_to_person": "say-to-person",
    "accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  }
}

Repo memory

POST/v1/repos

Write repos.

Key
Bearer
Scope
memory:write
Body fieldType
namestring
remote_hash optionalstring
Optional SHA-256 of the remote URL; the URL itself is never sent
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
namestring
remote_hashstring or null
created_atstring (date-time)
createdboolean
curl -s -X POST http://127.0.0.1:4100/v1/repos \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"Chain Scout","remote_hash":"remote-hash"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/repos",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"name":"Chain Scout","remote_hash":"remote-hash"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/repos", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"name":"Chain Scout","remote_hash":"remote-hash"})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "name": "Chain Scout",
  "remote_hash": "remote-hash",
  "created_at": "2026-10-24T09:12:03.000Z",
  "created": false
}

DELETE/v1/repos/{repo}

Delete repos/:repo.

Key
Bearer
Scope
memory:write
ParameterIn · type
repopath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
repostring
erasedtrue
commitsinteger
blobsinteger
File summaries and their symbols deleted (blobs no other repo uses)
memoriesinteger
curl -s -X DELETE http://127.0.0.1:4100/v1/repos/<repo> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/repos/<repo>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>", {
  method: "DELETE",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "repo": "petrova",
  "erased": true,
  "commits": 1,
  "blobs": 1,
  "memories": 1
}

POST/v1/repos/{repo}/missing-blobs

Write repos/:repo/missing-blobs.

Key
Bearer
Scope
memory:write
ParameterIn · type
repopath · string
Body fieldType
blob_shaslist of string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
missinglist of string
curl -s -X POST http://127.0.0.1:4100/v1/repos/<repo>/missing-blobs \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"blob_shas":["blob-shas"]}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/repos/<repo>/missing-blobs",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"blob_shas":["blob-shas"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>/missing-blobs", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"blob_shas":["blob-shas"]})
});
console.log(await r.json());
{
  "missing": [
    "missing"
  ]
}

POST/v1/repos/{repo}/commits/{sha}/index

Write repos/:repo/commits/:sha/index.

Key
Bearer
Scope
memory:write
ParameterIn · type
repopath · string
shapath · string
Body fieldType
parent_sha optionalstring
files optionallist of objects
changes optionalobject
blobs optionallist of objects
Contents of blobs the server does not have (UTF-8 text, at most 256 KiB each)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
upstream failed502YesA supplier or tool failed; you paid nothing. Retry.
Response fields
repostring
commitstring
state"pending" | "indexed" | "failed"
parent_shastring or null
filesinteger
locinteger
new_blobsinteger
renderer_versionstring or null
block_hashstring or null
block_tokensinteger or null
reservation_idstring (uuid) or null
replayedboolean
charged_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
queued optionalboolean
True when the memory worker will summarise, render and settle this commit; poll GET .../commits/{sha}
curl -s -X POST http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>/index \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"parent_sha":"parent-sha","files":[{"path":"path","blob_sha":"blob-sha"}],"changes":{"upsert":[{"path":"path","blob_sha":"blob-sha"}],"delete":["delete"]},"blobs":[{"blob_sha":"blob-sha","content":"content"}]}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>/index",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"parent_sha":"parent-sha","files":[{"path":"path","blob_sha":"blob-sha"}],"changes":{"upsert":[{"path":"path","blob_sha":"blob-sha"}],"delete":["delete"]},"blobs":[{"blob_sha":"blob-sha","content":"content"}]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>/index", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"parent_sha":"parent-sha","files":[{"path":"path","blob_sha":"blob-sha"}],"changes":{"upsert":[{"path":"path","blob_sha":"blob-sha"}],"delete":["delete"]},"blobs":[{"blob_sha":"blob-sha","content":"content"}]})
});
console.log(await r.json());
{
  "repo": "petrova",
  "commit": "4fe0ba0c2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f60",
  "state": "pending",
  "parent_sha": "parent-sha",
  "files": 812,
  "loc": 61234,
  "new_blobs": 1,
  "renderer_version": "1",
  "block_hash": "ab12…",
  "block_tokens": 1180,
  "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "replayed": false,
  "charged_nusd": "18990000",
  "queued": false
}

GET/v1/repos/{repo}/commits/{sha}

Read repos/:repo/commits/:sha.

Key
Bearer
Scope
memory:read
ParameterIn · type
repopath · string
shapath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
repostring
commitstring
state"pending" | "indexed" | "failed"
parent_shastring or null
filesinteger
locinteger
new_blobsinteger
renderer_versionstring or null
block_hashstring or null
block_tokensinteger or null
reservation_idstring (uuid) or null
curl -s http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "repo": "petrova",
  "commit": "4fe0ba0c2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f60",
  "state": "pending",
  "parent_sha": "parent-sha",
  "files": 812,
  "loc": 61234,
  "new_blobs": 1,
  "renderer_version": "1",
  "block_hash": "ab12…",
  "block_tokens": 1180,
  "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
}

GET/v1/repos/{repo}/context

Read repos/:repo/context.

Key
Bearer
Scope
memory:read
ParameterIn · type
repopath · string
commit optionalquery · string
paths optionalquery · string
ancestors optionalquery · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
repostring
requested_commitstring
commitstring
exactboolean
false when answered from the nearest indexed ancestor
renderer_versionstring
block_hashstring
tokensinteger
block_text optionalstring
truncated optionalboolean
files optionallist of objects
curl -s http://127.0.0.1:4100/v1/repos/<repo>/context \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/repos/<repo>/context",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>/context", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "repo": "petrova",
  "requested_commit": "4fe0ba0c2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f60",
  "commit": "4fe0ba0c2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f60",
  "exact": false,
  "renderer_version": "1",
  "block_hash": "ab12…",
  "tokens": 1180,
  "block_text": "block-text",
  "truncated": false,
  "files": [
    {
      "path": "path",
      "lang": "lang",
      "summary": "New token FOO launched with $42,000 liquidity",
      "symbols": [
        {
          "name": null,
          "kind": null,
          "line": null,
          "signature": null
        }
      ]
    }
  ]
}

Saved memories

POST/v1/memories

Save a memory (1 to 1,000 characters).

Key
Bearer
Scope
memory:write
Body fieldType
textstring
kind optional"fact" | "decision" | "convention"
repo optionalstring
pinned optionalboolean
Pinned memories are injected with the repo block
scope optional"account" | "project"
account (default): every key; project: keys of this project
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
kind"fact" | "decision" | "convention"
textstring
pinnedboolean
repostring or null
scope"account" | "project"
created_atstring (date-time)
curl -s -X POST http://127.0.0.1:4100/v1/memories \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"text":"Money is nano-USD bigint, never floats.","kind":"fact","repo":"petrova","pinned":false,"scope":"account"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/memories",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"text":"Money is nano-USD bigint, never floats.","kind":"fact","repo":"petrova","pinned":false,"scope":"account"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/memories", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"text":"Money is nano-USD bigint, never floats.","kind":"fact","repo":"petrova","pinned":false,"scope":"account"})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "kind": "fact",
  "text": "Money is nano-USD bigint, never floats.",
  "pinned": false,
  "repo": "petrova",
  "scope": "account",
  "created_at": "2026-10-24T09:12:03.000Z"
}

GET/v1/memories

Search saved memories.

Key
Bearer
Scope
memory:read
ParameterIn · type
q optionalquery · string
repo optionalquery · string
commit optionalquery · string
pinned optionalquery · boolean
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
search optional"fts+trigram" | "fts+ilike"
symbols optionallist of objects
curl -s http://127.0.0.1:4100/v1/memories \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/memories",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/memories", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "kind": "fact",
      "text": "Money is nano-USD bigint, never floats.",
      "pinned": false,
      "repo": "petrova",
      "scope": "account",
      "created_at": "2026-10-24T09:12:03.000Z",
      "score": 0.82
    }
  ],
  "search": "fts+trigram",
  "symbols": [
    {
      "path": "path",
      "name": "Chain Scout",
      "kind": "kind",
      "line": 1,
      "signature": "signature"
    }
  ]
}

GET/v1/memories/export

Read memories/export.

Key
Bearer
Scope
memory:read
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
curl -s http://127.0.0.1:4100/v1/memories/export \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/memories/export",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/memories/export", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
"value"

DELETE/v1/memories/{id}

Forget a memory: the row, its text and its index.

Key
Bearer
Scope
memory:write
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring
forgottentrue
curl -s -X DELETE http://127.0.0.1:4100/v1/memories/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/memories/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/memories/<id>", {
  method: "DELETE",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "forgotten": true
}

Your own cloud (AWS)

GET/v1/clouds/aws

Read clouds/aws.

Key
Bearer
Scope
cloud:write
CodeHTTPRetry?What to do
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
Response fields
provider"aws"
state"pending" | "connected" | "verified" | "failed"
external_idstring
Issued by Petrova. Put it in the CloudFormation stack; the role trusts only this value.
petrova_principal_arnstring
regionstring
aws_account_hintstring or null
template_urlstring
quick_create_urlstring
inference_profilesobject
Anthropic model id -> Bedrock inference profile id found in your account
last_checkany
Outcome of the last verification, or null
verified_atstring (date-time) or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/clouds/aws \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/clouds/aws",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/clouds/aws", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "provider": "aws",
  "state": "pending",
  "external_id": "ptrv-ext-3c9a1f",
  "petrova_principal_arn": "petrova-principal-arn",
  "region": "us-east-1",
  "aws_account_hint": "aws-account-hint",
  "template_url": "https://example.invalid/",
  "quick_create_url": "https://example.invalid/",
  "inference_profiles": {},
  "last_check": null,
  "verified_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

POST/v1/clouds/aws

Write clouds/aws.

Key
Bearer
Scope
cloud:write
Body fieldType
role_arnstring
external_idstring
region optionalstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
Response fields
provider"aws"
state"pending" | "connected" | "verified" | "failed"
external_idstring
Issued by Petrova. Put it in the CloudFormation stack; the role trusts only this value.
petrova_principal_arnstring
regionstring
aws_account_hintstring or null
template_urlstring
quick_create_urlstring
inference_profilesobject
Anthropic model id -> Bedrock inference profile id found in your account
last_checkany
Outcome of the last verification, or null
verified_atstring (date-time) or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/clouds/aws \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"role_arn":"role-arn","external_id":"ptrv-ext-3c9a1f","region":"us-east-1"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/clouds/aws",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"role_arn":"role-arn","external_id":"ptrv-ext-3c9a1f","region":"us-east-1"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/clouds/aws", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"role_arn":"role-arn","external_id":"ptrv-ext-3c9a1f","region":"us-east-1"})
});
console.log(await r.json());
{
  "provider": "aws",
  "state": "pending",
  "external_id": "ptrv-ext-3c9a1f",
  "petrova_principal_arn": "petrova-principal-arn",
  "region": "us-east-1",
  "aws_account_hint": "aws-account-hint",
  "template_url": "https://example.invalid/",
  "quick_create_url": "https://example.invalid/",
  "inference_profiles": {},
  "last_check": null,
  "verified_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

DELETE/v1/clouds/aws

Delete clouds/aws.

Key
Bearer
Scope
cloud:write
CodeHTTPRetry?What to do
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
Response fields
provider"aws"
state"disconnected"
mode"fixture"
curl -s -X DELETE http://127.0.0.1:4100/v1/clouds/aws \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/clouds/aws",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/clouds/aws", {
  method: "DELETE",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "provider": "aws",
  "state": "disconnected",
  "mode": "fixture"
}

POST/v1/clouds/aws/verify

Write clouds/aws/verify.

Key
Bearer
Scope
cloud:write
CodeHTTPRetry?What to do
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
Response fields
provider"aws"
state"pending" | "connected" | "verified" | "failed"
external_idstring
Issued by Petrova. Put it in the CloudFormation stack; the role trusts only this value.
petrova_principal_arnstring
regionstring
aws_account_hintstring or null
template_urlstring
quick_create_urlstring
inference_profilesobject
Anthropic model id -> Bedrock inference profile id found in your account
last_checkany
Outcome of the last verification, or null
verified_atstring (date-time) or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/clouds/aws/verify \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/clouds/aws/verify",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/clouds/aws/verify", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "provider": "aws",
  "state": "pending",
  "external_id": "ptrv-ext-3c9a1f",
  "petrova_principal_arn": "petrova-principal-arn",
  "region": "us-east-1",
  "aws_account_hint": "aws-account-hint",
  "template_url": "https://example.invalid/",
  "quick_create_url": "https://example.invalid/",
  "inference_profiles": {},
  "last_check": null,
  "verified_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

Chat Completions (OpenAI)

POST/v1/chat/completions

OpenAI Chat Completions, translated and run through the same caps and holds.

Key
Bearer, x-api-key or x-petrova-key
Scope
quote:write
Body fieldType
modelstring
messageslist of objects
stream optionalboolean
max_tokens optionalinteger
max_completion_tokens optionalinteger
tools optionallist of objects
user optionalstring
Agent id for agent caps when no header names one
metadata optionalobject
agent_id, parent_agent_id, session_id for caps
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
conflict409NoThe state changed (used, expired or already decided). Read it again.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
upstream failed502YesA supplier or tool failed; you paid nothing. Retry.
unavailable503YesTry again shortly.
Response fields
idstring
object"chat.completion"
createdinteger
modelstring
choiceslist of objects
usageobject
curl -s -X POST http://127.0.0.1:4100/v1/chat/completions \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"model":"claude-opus-5-5","messages":[{}],"stream":false,"max_tokens":1,"max_completion_tokens":1,"tools":[{}],"user":"user","metadata":{}}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/chat/completions",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"model":"claude-opus-5-5","messages":[{}],"stream":false,"max_tokens":1,"max_completion_tokens":1,"tools":[{}],"user":"user","metadata":{}})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/chat/completions", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"model":"claude-opus-5-5","messages":[{}],"stream":false,"max_tokens":1,"max_completion_tokens":1,"tools":[{}],"user":"user","metadata":{}})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "object": "chat.completion",
  "created": 1,
  "model": "claude-opus-5-5",
  "choices": [
    {}
  ],
  "usage": {}
}

Responses (OpenAI)

POST/v1/responses

OpenAI Responses (what Codex uses), same caps and holds.

Key
Bearer, x-api-key or x-petrova-key
Scope
quote:write
Body fieldType
modelstring
inputany
instructions optionalstring
stream optionalboolean
max_output_tokens optionalinteger
tools optionallist of objects
metadata optionalobject
agent_id, parent_agent_id, session_id for caps
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
conflict409NoThe state changed (used, expired or already decided). Read it again.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
upstream failed502YesA supplier or tool failed; you paid nothing. Retry.
unavailable503YesTry again shortly.
Response fields
idstring
object"response"
statusstring
modelstring
outputlist of objects
usageobject
curl -s -X POST http://127.0.0.1:4100/v1/responses \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"model":"claude-opus-5-5","input":null,"instructions":"instructions","stream":false,"max_output_tokens":1,"tools":[{}],"metadata":{}}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/responses",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"model":"claude-opus-5-5","input":null,"instructions":"instructions","stream":false,"max_output_tokens":1,"tools":[{}],"metadata":{}})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/responses", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"model":"claude-opus-5-5","input":null,"instructions":"instructions","stream":false,"max_output_tokens":1,"tools":[{}],"metadata":{}})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "object": "response",
  "status": "status",
  "model": "claude-opus-5-5",
  "output": [
    {}
  ],
  "usage": {}
}

chain.watch

POST/v1/chain/watch

Start a stream of Base chain events. Pay per event delivered.

Key
Bearer
Scope
quote:write
Body fieldType
filter optionalobject
query optionalstring
Optional plain-language filter, e.g. "swaps over $50k of 0x..."; filter fields win
hold_events optionalinteger
Events held per hold; unused ones are released at settle
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
tool_idstring (uuid)
chain"base"
state"active" | "stopped"
filterobject
querystring or null
price_per_event_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
price_per_event_usdstring
hold_eventsinteger
delivered_eventsinteger
cursorstring
Sequence number of the last delivered event
charged_nusdnano-USD string
Settled charges
pending_nusdnano-USD string
Delivered against the open hold, settled when it closes
held_nusdnano-USD string
Size of the open hold
created_atstring (date-time)
stopped_atstring (date-time) or null
events_urlstring
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/chain/watch \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"filter":{"types":["token_launch"],"addresses":["addresses"],"wallets":["wallets"],"min_usd_nusd":"18990000"},"query":"new tokens with more than $40k liquidity","hold_events":100}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/chain/watch",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"filter":{"types":["token_launch"],"addresses":["addresses"],"wallets":["wallets"],"min_usd_nusd":"18990000"},"query":"new tokens with more than $40k liquidity","hold_events":100})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/chain/watch", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"filter":{"types":["token_launch"],"addresses":["addresses"],"wallets":["wallets"],"min_usd_nusd":"18990000"},"query":"new tokens with more than $40k liquidity","hold_events":100})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "chain": "base",
  "state": "active",
  "filter": {
    "types": [
      "token_launch"
    ],
    "addresses": [
      "addresses"
    ],
    "wallets": [
      "wallets"
    ],
    "min_usd_nusd": "18990000"
  },
  "query": "new tokens with more than $40k liquidity",
  "price_per_event_nusd": "5000000",
  "price_per_event_usd": "price-per-event-usd",
  "hold_events": 100,
  "delivered_events": 3,
  "cursor": "12",
  "charged_nusd": "18990000",
  "pending_nusd": "18990000",
  "held_nusd": "99085600",
  "created_at": "2026-10-24T09:12:03.000Z",
  "stopped_at": "2026-10-24T09:12:03.000Z",
  "events_url": "https://example.invalid/",
  "mode": "fixture"
}

GET/v1/chain/watch/{id}

Read chain/watch/:id.

Key
Bearer
Scope
quote:write
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
tool_idstring (uuid)
chain"base"
state"active" | "stopped"
filterobject
querystring or null
price_per_event_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
price_per_event_usdstring
hold_eventsinteger
delivered_eventsinteger
cursorstring
Sequence number of the last delivered event
charged_nusdnano-USD string
Settled charges
pending_nusdnano-USD string
Delivered against the open hold, settled when it closes
held_nusdnano-USD string
Size of the open hold
created_atstring (date-time)
stopped_atstring (date-time) or null
events_urlstring
mode"fixture"
curl -s http://127.0.0.1:4100/v1/chain/watch/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/chain/watch/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/chain/watch/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "chain": "base",
  "state": "active",
  "filter": {
    "types": [
      "token_launch"
    ],
    "addresses": [
      "addresses"
    ],
    "wallets": [
      "wallets"
    ],
    "min_usd_nusd": "18990000"
  },
  "query": "new tokens with more than $40k liquidity",
  "price_per_event_nusd": "5000000",
  "price_per_event_usd": "price-per-event-usd",
  "hold_events": 100,
  "delivered_events": 3,
  "cursor": "12",
  "charged_nusd": "18990000",
  "pending_nusd": "18990000",
  "held_nusd": "99085600",
  "created_at": "2026-10-24T09:12:03.000Z",
  "stopped_at": "2026-10-24T09:12:03.000Z",
  "events_url": "https://example.invalid/",
  "mode": "fixture"
}

DELETE/v1/chain/watch/{id}

Delete chain/watch/:id.

Key
Bearer
Scope
quote:write
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
tool_idstring (uuid)
chain"base"
state"active" | "stopped"
filterobject
querystring or null
price_per_event_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
price_per_event_usdstring
hold_eventsinteger
delivered_eventsinteger
cursorstring
Sequence number of the last delivered event
charged_nusdnano-USD string
Settled charges
pending_nusdnano-USD string
Delivered against the open hold, settled when it closes
held_nusdnano-USD string
Size of the open hold
created_atstring (date-time)
stopped_atstring (date-time) or null
events_urlstring
mode"fixture"
curl -s -X DELETE http://127.0.0.1:4100/v1/chain/watch/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/chain/watch/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/chain/watch/<id>", {
  method: "DELETE",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "chain": "base",
  "state": "active",
  "filter": {
    "types": [
      "token_launch"
    ],
    "addresses": [
      "addresses"
    ],
    "wallets": [
      "wallets"
    ],
    "min_usd_nusd": "18990000"
  },
  "query": "new tokens with more than $40k liquidity",
  "price_per_event_nusd": "5000000",
  "price_per_event_usd": "price-per-event-usd",
  "hold_events": 100,
  "delivered_events": 3,
  "cursor": "12",
  "charged_nusd": "18990000",
  "pending_nusd": "18990000",
  "held_nusd": "99085600",
  "created_at": "2026-10-24T09:12:03.000Z",
  "stopped_at": "2026-10-24T09:12:03.000Z",
  "events_url": "https://example.invalid/",
  "mode": "fixture"
}

GET/v1/chain/watch/{id}/events

Read chain/watch/:id/events.

Key
Bearer
Scope
quote:write
ParameterIn · type
idpath · string (uuid)
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
curl -s http://127.0.0.1:4100/v1/chain/watch/<id>/events \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/chain/watch/<id>/events",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/chain/watch/<id>/events", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
"value"

GET/v1/chain/watch/{id}/poll

Fetch new events since a cursor.

Key
Bearer
Scope
quote:write
ParameterIn · type
idpath · string (uuid)
cursor optionalquery · string
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
watch_idstring (uuid)
state"active" | "stopped"
eventslist of objects
cursorstring
charged_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
price_per_event_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
errorobject or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/chain/watch/<id>/poll \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/chain/watch/<id>/poll",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/chain/watch/<id>/poll", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "watch_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "state": "active",
  "events": [
    {
      "seq": 1,
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "type": "token_launch",
      "summary": "New token FOO launched with $42,000 liquidity"
    }
  ],
  "cursor": "12",
  "charged_nusd": "18990000",
  "price_per_event_nusd": "5000000",
  "error": {
    "type": "type",
    "message": "message"
  },
  "mode": "fixture"
}

Plans

GET/v1/plans

Monthly plans, bonus tiers and the referral share (example numbers).

Key
Bearer
Scope
catalog:read
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
planslist of objects
bonus_tierslist of objects
Volume bonus on a top-up: the highest tier reached applies
referralobject
curl -s http://127.0.0.1:4100/v1/plans \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/plans",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/plans", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "plans": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "name": "Chain Scout",
      "price_nusd": "5000000",
      "credits_nusd": "115000000000",
      "period": "calendar_month_utc"
    }
  ],
  "bonus_tiers": [
    {
      "min_nusd": "18990000",
      "bonus_bps": 500
    }
  ],
  "referral": {
    "share_bps": 1000,
    "months": 12
  }
}

POST/v1/plans/subscribe

Write plans/subscribe.

Key
Bearer
Scope
plan:write
Body fieldType
plan_idstring
auto_renew optionalboolean
Renew from the balance at each month start (default true)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
replayedboolean
This plan was already bought this month; nothing was charged
mode"fixture"
as_ofstring (date-time)
total_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
plan_nusdnano-USD string
Unspent plan credits this month (spent first; expire at month end)
bought_nusdnano-USD string
Unspent bought credits (spent last; never expire)
bonus_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
other_nusdnano-USD string
Balance from elsewhere: funding, seller income, referral rewards
planobject or null
subscriptionobject or null
curl -s -X POST http://127.0.0.1:4100/v1/plans/subscribe \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"plan_id":"builder","auto_renew":false}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/plans/subscribe",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"plan_id":"builder","auto_renew":false})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/plans/subscribe", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"plan_id":"builder","auto_renew":false})
});
console.log(await r.json());
{
  "replayed": false,
  "mode": "fixture",
  "as_of": "2026-10-24T09:12:03.000Z",
  "total_nusd": "18742360000",
  "plan_nusd": "18990000",
  "bought_nusd": "18990000",
  "bonus_nusd": "25000000000",
  "other_nusd": "18990000",
  "plan": {
    "plan_id": "builder",
    "credits_nusd": "115000000000",
    "remaining_nusd": "1100000000",
    "expires_at": "2026-10-24T09:12:03.000Z"
  },
  "subscription": {
    "plan_id": "builder",
    "auto_renew": false,
    "lapsed_reason": "lapsed-reason"
  }
}

POST/v1/plans/cancel

Write plans/cancel.

Key
Bearer
Scope
plan:write
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
as_ofstring (date-time)
total_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
plan_nusdnano-USD string
Unspent plan credits this month (spent first; expire at month end)
bought_nusdnano-USD string
Unspent bought credits (spent last; never expire)
bonus_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
other_nusdnano-USD string
Balance from elsewhere: funding, seller income, referral rewards
planobject or null
subscriptionobject or null
curl -s -X POST http://127.0.0.1:4100/v1/plans/cancel \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/plans/cancel",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/plans/cancel", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "as_of": "2026-10-24T09:12:03.000Z",
  "total_nusd": "18742360000",
  "plan_nusd": "18990000",
  "bought_nusd": "18990000",
  "bonus_nusd": "25000000000",
  "other_nusd": "18990000",
  "plan": {
    "plan_id": "builder",
    "credits_nusd": "115000000000",
    "remaining_nusd": "1100000000",
    "expires_at": "2026-10-24T09:12:03.000Z"
  },
  "subscription": {
    "plan_id": "builder",
    "auto_renew": false,
    "lapsed_reason": "lapsed-reason"
  }
}

Top-ups

GET/v1/topups/quote

Preview a top-up: what you pay and the bonus. Send amount_nusd.

Key
Bearer
Scope
catalog:read
ParameterIn · type
amount_nusd optionalquery · nano-USD string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
amount_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
bonus_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
bonus_bpsinteger
credits_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
tierslist of objects
curl -s http://127.0.0.1:4100/v1/topups/quote \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/topups/quote",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/topups/quote", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "amount_nusd": "20000000000",
  "bonus_nusd": "25000000000",
  "bonus_bps": 500,
  "credits_nusd": "115000000000",
  "tiers": [
    {
      "min_nusd": "18990000",
      "bonus_bps": 500
    }
  ]
}

POST/v1/topups/onchain

Write topups/onchain.

Key
Bearer
Scope
none (wallet-signed message)
Body fieldType
messagestring
public_keystring
Uncompressed secp256k1 public key, hex
signaturestring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
tx_hashstring
state"pending" | "awaiting_approval" | "credited" | "rejected"
reasonstring or null
amount_nusdnano-USD string or null
confirmationsinteger
confirmations_requiredinteger
approval_idstring (uuid) or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/topups/onchain \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"message":"message","public_key":"public-key","signature":"signature"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/topups/onchain",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"message":"message","public_key":"public-key","signature":"signature"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/topups/onchain", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"message":"message","public_key":"public-key","signature":"signature"})
});
console.log(await r.json());
{
  "tx_hash": "0xaaa1c0ffee",
  "state": "pending",
  "reason": "reason",
  "amount_nusd": "20000000000",
  "confirmations": 12,
  "confirmations_required": 12,
  "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "mode": "fixture"
}

GET/v1/topups/approvals

Agent top-ups waiting for your OK.

Key
Bearer
Scope
budget:write
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/topups/approvals \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/topups/approvals",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/topups/approvals", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "tx_hash": "0xaaa1c0ffee",
      "amount_nusd": "20000000000",
      "nonce": "n-91f2",
      "state": "pending",
      "decided_by": "decided-by",
      "message_to_sign": "message-to-sign"
    }
  ],
  "mode": "fixture"
}

POST/v1/topups/approvals/{id}/decide

Approve or reject an agent top-up.

Key
Bearer
Scope
budget:write
ParameterIn · type
idpath · string (uuid)
Body fieldType
decision"approve" | "reject"
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
tx_hashstring
state"pending" | "awaiting_approval" | "credited" | "rejected"
reasonstring or null
amount_nusdnano-USD string or null
confirmationsinteger
confirmations_requiredinteger
approval_idstring (uuid) or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/topups/approvals/<id>/decide \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"decision":"approve"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/topups/approvals/<id>/decide",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"decision":"approve"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/topups/approvals/<id>/decide", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"decision":"approve"})
});
console.log(await r.json());
{
  "tx_hash": "0xaaa1c0ffee",
  "state": "pending",
  "reason": "reason",
  "amount_nusd": "20000000000",
  "confirmations": 12,
  "confirmations_required": 12,
  "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "mode": "fixture"
}

POST/v1/topups/approvals/{id}/decide-signed

Write topups/approvals/:id/decide-signed.

Key
Bearer
Scope
none (operator wallet-signed message)
ParameterIn · type
idpath · string (uuid)
Body fieldType
messagestring
public_keystring
Uncompressed secp256k1 public key, hex
signaturestring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
tx_hashstring
state"pending" | "awaiting_approval" | "credited" | "rejected"
reasonstring or null
amount_nusdnano-USD string or null
confirmationsinteger
confirmations_requiredinteger
approval_idstring (uuid) or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/topups/approvals/<id>/decide-signed \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"message":"message","public_key":"public-key","signature":"signature"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/topups/approvals/<id>/decide-signed",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"message":"message","public_key":"public-key","signature":"signature"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/topups/approvals/<id>/decide-signed", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"message":"message","public_key":"public-key","signature":"signature"})
});
console.log(await r.json());
{
  "tx_hash": "0xaaa1c0ffee",
  "state": "pending",
  "reason": "reason",
  "amount_nusd": "20000000000",
  "confirmations": 12,
  "confirmations_required": 12,
  "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "mode": "fixture"
}

GET/v1/topups/info

Read topups/info.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
real_moneyfalse
how_to_add_test_fundsstring
onchainobject
curl -s http://127.0.0.1:4100/v1/topups/info \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/topups/info",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/topups/info", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "real_money": false,
  "how_to_add_test_funds": "how-to-add-test-funds",
  "onchain": {
    "network": "network",
    "token": "token",
    "deposit_address": "deposit-address",
    "confirmations": 12,
    "note": "note"
  }
}

Credits

GET/v1/credits

Which credits you have and the order they are spent in.

Key
Bearer
Scope
balance:read
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
as_ofstring (date-time)
total_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
plan_nusdnano-USD string
Unspent plan credits this month (spent first; expire at month end)
bought_nusdnano-USD string
Unspent bought credits (spent last; never expire)
bonus_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
other_nusdnano-USD string
Balance from elsewhere: funding, seller income, referral rewards
planobject or null
subscriptionobject or null
curl -s http://127.0.0.1:4100/v1/credits \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/credits",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/credits", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "as_of": "2026-10-24T09:12:03.000Z",
  "total_nusd": "18742360000",
  "plan_nusd": "18990000",
  "bought_nusd": "18990000",
  "bonus_nusd": "25000000000",
  "other_nusd": "18990000",
  "plan": {
    "plan_id": "builder",
    "credits_nusd": "115000000000",
    "remaining_nusd": "1100000000",
    "expires_at": "2026-10-24T09:12:03.000Z"
  },
  "subscription": {
    "plan_id": "builder",
    "auto_renew": false,
    "lapsed_reason": "lapsed-reason"
  }
}

Referrals

GET/v1/referrals

Read referrals.

Key
Bearer
Scope
balance:read
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
mode"fixture"
codestring or null
referred_by_someoneboolean
referred_accountsinteger
earned_nusdnano-USD string
Rewards opened so far, credited to the balance as the referred accounts spent
pending_nusdnano-USD string
Rewards that open only as the referred accounts spend what they paid for
reversed_rewardsinteger
clawback_owed_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
curl -s http://127.0.0.1:4100/v1/referrals \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/referrals",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/referrals", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "mode": "fixture",
  "code": "PTRV-7K2Q",
  "referred_by_someone": false,
  "referred_accounts": 3,
  "earned_nusd": "46250000000",
  "pending_nusd": "18990000",
  "reversed_rewards": 1,
  "clawback_owed_nusd": "18990000"
}

POST/v1/referrals/code

Write referrals/code.

Key
Bearer
Scope
referral:write
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
codestring
curl -s -X POST http://127.0.0.1:4100/v1/referrals/code \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/referrals/code",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/referrals/code", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "code": "PTRV-7K2Q"
}

POST/v1/referrals/claim

Write referrals/claim.

Key
Bearer
Scope
referral:write
Body fieldType
codestring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
referredtrue
share_bpsinteger
rewards_untilstring (date-time)
curl -s -X POST http://127.0.0.1:4100/v1/referrals/claim \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"code":"PTRV-7K2Q"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/referrals/claim",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"code":"PTRV-7K2Q"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/referrals/claim", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"code":"PTRV-7K2Q"})
});
console.log(await r.json());
{
  "referred": true,
  "share_bps": 1000,
  "rewards_until": "2026-10-24T09:12:03.000Z"
}

Agent wallets

POST/v1/agent-wallets

Register an agent’s wallet with a cap and an approval threshold.

Key
Bearer
Scope
budget:write
Body fieldType
addressstring
agent_idstring
default_cap_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_threshold_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
operator_public_key optionalstring
Uncompressed secp256k1 public key, hex
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
wallet_idstring (uuid)
addressstring
agent_idstring
default_cap_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_threshold_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/agent-wallets \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"address":"0x5ab1000000000000000000000000000000c3d2","agent_id":"research-bot","default_cap_nusd":"5000000000","approval_threshold_nusd":"18990000","operator_public_key":"operator-public-key"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent-wallets",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"address":"0x5ab1000000000000000000000000000000c3d2","agent_id":"research-bot","default_cap_nusd":"5000000000","approval_threshold_nusd":"18990000","operator_public_key":"operator-public-key"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent-wallets", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"address":"0x5ab1000000000000000000000000000000c3d2","agent_id":"research-bot","default_cap_nusd":"5000000000","approval_threshold_nusd":"18990000","operator_public_key":"operator-public-key"})
});
console.log(await r.json());
{
  "wallet_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "address": "0x5ab1000000000000000000000000000000c3d2",
  "agent_id": "research-bot",
  "default_cap_nusd": "5000000000",
  "approval_threshold_nusd": "18990000",
  "mode": "fixture"
}

POST/v1/agent-wallets/status

Write agent-wallets/status.

Key
Bearer
Scope
none (wallet-signed message)
Body fieldType
messagestring
public_keystring
Uncompressed secp256k1 public key, hex
signaturestring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
addressstring
agent_idstring
default_cap_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_threshold_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
depositobject
credited_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
active_keysinteger
balanceobject
topupslist of objects
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/agent-wallets/status \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"message":"message","public_key":"public-key","signature":"signature"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent-wallets/status",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"message":"message","public_key":"public-key","signature":"signature"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent-wallets/status", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"message":"message","public_key":"public-key","signature":"signature"})
});
console.log(await r.json());
{
  "address": "0x5ab1000000000000000000000000000000c3d2",
  "agent_id": "research-bot",
  "default_cap_nusd": "5000000000",
  "approval_threshold_nusd": "18990000",
  "deposit": {
    "chain_id": 1,
    "token": "token",
    "address": "0x5ab1000000000000000000000000000000c3d2",
    "confirmations": 12
  },
  "credited_nusd": "18990000",
  "active_keys": 1,
  "balance": {
    "currency": "USD",
    "total_nusd": "18742360000",
    "available_nusd": "18544188800",
    "reserved_nusd": "198171200",
    "mode": "fixture",
    "as_of": "2026-10-24T09:12:03.000Z"
  },
  "topups": [
    {
      "tx_hash": "0xaaa1c0ffee",
      "state": "pending",
      "reason": "reason",
      "amount_nusd": "20000000000",
      "confirmations": 12,
      "confirmations_required": 12,
      "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "mode": "fixture"
    }
  ],
  "mode": "fixture"
}

POST/v1/agent-wallets/keys

Write agent-wallets/keys.

Key
Bearer
Scope
none (wallet-signed message)
Body fieldType
messagestring
public_keystring
Uncompressed secp256k1 public key, hex
signaturestring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
key_idstring (uuid)
secretstring
Shown once. Store it; Petrova keeps only its hash.
agent_idstring
scopeslist of string
cap_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/agent-wallets/keys \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"message":"message","public_key":"public-key","signature":"signature"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent-wallets/keys",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"message":"message","public_key":"public-key","signature":"signature"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent-wallets/keys", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"message":"message","public_key":"public-key","signature":"signature"})
});
console.log(await r.json());
{
  "key_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "secret": "secret",
  "agent_id": "research-bot",
  "scopes": [
    "scopes"
  ],
  "cap_nusd": "5000000000",
  "mode": "fixture"
}

Cards

POST/v1/cards

Write cards.

Key
Bearer
Scope
see the route
Body fieldType
namestring
monthly_allowance_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
per_call_limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_over_nusd optionalnano-USD string or null
A call whose hold is above this waits for a person. Null: never
allowed_tools optionallist of string (uuid) or null
Null: any tool. With allowed_services, a tool in either list may be called
allowed_services optionallist of string or null
Provider names
permission optional"read" | "write"
Default read
shared_budget_id optionalstring (uuid) or null
project_id optionalstring (uuid)
request_id optionalstring
Reuse to make a retry safe. A replay returns the card without a key
allowed_connections optionallist of string (uuid) or null
Your own provider accounts this card may use. Null: none
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
cardobject
keyobject or null
replayedboolean
curl -s -X POST http://127.0.0.1:4100/v1/cards \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","request_id":"request-id","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/cards",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","request_id":"request-id","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/cards", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","request_id":"request-id","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]})
});
console.log(await r.json());
{
  "card": {
    "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "name": "Chain Scout",
    "state": "active",
    "project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "permission": "read",
    "monthly_allowance_nusd": "18990000",
    "committed_this_month_nusd": "3900000000",
    "held_nusd": "99085600",
    "available_nusd": "18544188800",
    "per_call_limit_nusd": "5000000000",
    "approval_over_nusd": "18990000",
    "allowed_tools": [
      "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
    ],
    "allowed_services": [
      "allowed-services"
    ],
    "shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "allowed_connections": [
      "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
    ],
    "application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "budgets_above": [
      {
        "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
        "limit_nusd": "5000000000",
        "committed_nusd": "3900000000"
      }
    ],
    "key_prefix": "key-prefix",
    "created_at": "2026-10-24T09:12:03.000Z",
    "closed_at": "2026-10-24T09:12:03.000Z",
    "mode": "fixture"
  },
  "key": {
    "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "secret": "secret",
    "scopes": [
      "scopes"
    ]
  },
  "replayed": false
}

GET/v1/cards

Read cards.

Key
Bearer
Scope
see the route
ParameterIn · type
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/cards \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/cards",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/cards", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "name": "Chain Scout",
      "state": "active",
      "project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "permission": "read",
      "monthly_allowance_nusd": "18990000",
      "committed_this_month_nusd": "3900000000",
      "held_nusd": "99085600",
      "available_nusd": "18544188800",
      "per_call_limit_nusd": "5000000000",
      "approval_over_nusd": "18990000",
      "allowed_tools": [
        "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
      ],
      "allowed_services": [
        "allowed-services"
      ],
      "shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "allowed_connections": [
        "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
      ],
      "application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "budgets_above": [
        {
          "id": null,
          "limit_nusd": null,
          "committed_nusd": null
        }
      ],
      "key_prefix": "key-prefix",
      "created_at": "2026-10-24T09:12:03.000Z",
      "closed_at": "2026-10-24T09:12:03.000Z",
      "mode": "fixture"
    }
  ],
  "mode": "fixture"
}

GET/v1/cards/me

Read cards/me.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
namestring
state"active" | "paused" | "closed"
project_idstring (uuid)
permission"read" | "write"
read: GET tools only. write: any method
monthly_allowance_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
committed_this_month_nusdnano-USD string
Held plus charged this calendar month, UTC
held_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
available_nusdnano-USD string
The most a new hold could be under this card and every shared budget above it. The wallet may have less
per_call_limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_over_nusdnano-USD string or null
allowed_toolslist of string (uuid) or null
allowed_serviceslist of string or null
shared_budget_idstring (uuid) or null
allowed_connections optionallist of string (uuid) or null
application_id optionalstring (uuid) or null
budgets_abovelist of objects
key_prefixstring or null
created_atstring (date-time)
closed_atstring (date-time) or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/cards/me \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/cards/me",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/cards/me", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "name": "Chain Scout",
  "state": "active",
  "project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "permission": "read",
  "monthly_allowance_nusd": "18990000",
  "committed_this_month_nusd": "3900000000",
  "held_nusd": "99085600",
  "available_nusd": "18544188800",
  "per_call_limit_nusd": "5000000000",
  "approval_over_nusd": "18990000",
  "allowed_tools": [
    "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  ],
  "allowed_services": [
    "allowed-services"
  ],
  "shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "allowed_connections": [
    "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  ],
  "application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "budgets_above": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "limit_nusd": "5000000000",
      "committed_nusd": "3900000000"
    }
  ],
  "key_prefix": "key-prefix",
  "created_at": "2026-10-24T09:12:03.000Z",
  "closed_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

GET/v1/cards/{id}

Read cards/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
namestring
state"active" | "paused" | "closed"
project_idstring (uuid)
permission"read" | "write"
read: GET tools only. write: any method
monthly_allowance_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
committed_this_month_nusdnano-USD string
Held plus charged this calendar month, UTC
held_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
available_nusdnano-USD string
The most a new hold could be under this card and every shared budget above it. The wallet may have less
per_call_limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_over_nusdnano-USD string or null
allowed_toolslist of string (uuid) or null
allowed_serviceslist of string or null
shared_budget_idstring (uuid) or null
allowed_connections optionallist of string (uuid) or null
application_id optionalstring (uuid) or null
budgets_abovelist of objects
key_prefixstring or null
created_atstring (date-time)
closed_atstring (date-time) or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/cards/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/cards/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "name": "Chain Scout",
  "state": "active",
  "project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "permission": "read",
  "monthly_allowance_nusd": "18990000",
  "committed_this_month_nusd": "3900000000",
  "held_nusd": "99085600",
  "available_nusd": "18544188800",
  "per_call_limit_nusd": "5000000000",
  "approval_over_nusd": "18990000",
  "allowed_tools": [
    "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  ],
  "allowed_services": [
    "allowed-services"
  ],
  "shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "allowed_connections": [
    "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  ],
  "application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "budgets_above": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "limit_nusd": "5000000000",
      "committed_nusd": "3900000000"
    }
  ],
  "key_prefix": "key-prefix",
  "created_at": "2026-10-24T09:12:03.000Z",
  "closed_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

PATCH/v1/cards/{id}

Write cards/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
name optionalstring
monthly_allowance_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
per_call_limit_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_over_nusd optionalnano-USD string or null
allowed_tools optionallist of string (uuid) or null
allowed_services optionallist of string or null
permission optional"read" | "write"
shared_budget_id optionalstring (uuid) or null
state optional"active" | "paused"
allowed_connections optionallist of string (uuid) or null
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
namestring
state"active" | "paused" | "closed"
project_idstring (uuid)
permission"read" | "write"
read: GET tools only. write: any method
monthly_allowance_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
committed_this_month_nusdnano-USD string
Held plus charged this calendar month, UTC
held_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
available_nusdnano-USD string
The most a new hold could be under this card and every shared budget above it. The wallet may have less
per_call_limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_over_nusdnano-USD string or null
allowed_toolslist of string (uuid) or null
allowed_serviceslist of string or null
shared_budget_idstring (uuid) or null
allowed_connections optionallist of string (uuid) or null
application_id optionalstring (uuid) or null
budgets_abovelist of objects
key_prefixstring or null
created_atstring (date-time)
closed_atstring (date-time) or null
mode"fixture"
curl -s -X PATCH http://127.0.0.1:4100/v1/cards/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","state":"active","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]}'
import os, requests
r = requests.patch("http://127.0.0.1:4100/v1/cards/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","state":"active","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>", {
  method: "PATCH",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","state":"active","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "name": "Chain Scout",
  "state": "active",
  "project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "permission": "read",
  "monthly_allowance_nusd": "18990000",
  "committed_this_month_nusd": "3900000000",
  "held_nusd": "99085600",
  "available_nusd": "18544188800",
  "per_call_limit_nusd": "5000000000",
  "approval_over_nusd": "18990000",
  "allowed_tools": [
    "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  ],
  "allowed_services": [
    "allowed-services"
  ],
  "shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "allowed_connections": [
    "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  ],
  "application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "budgets_above": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "limit_nusd": "5000000000",
      "committed_nusd": "3900000000"
    }
  ],
  "key_prefix": "key-prefix",
  "created_at": "2026-10-24T09:12:03.000Z",
  "closed_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

POST/v1/cards/{id}/close

Write cards/:id/close.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
namestring
state"active" | "paused" | "closed"
project_idstring (uuid)
permission"read" | "write"
read: GET tools only. write: any method
monthly_allowance_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
committed_this_month_nusdnano-USD string
Held plus charged this calendar month, UTC
held_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
available_nusdnano-USD string
The most a new hold could be under this card and every shared budget above it. The wallet may have less
per_call_limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_over_nusdnano-USD string or null
allowed_toolslist of string (uuid) or null
allowed_serviceslist of string or null
shared_budget_idstring (uuid) or null
allowed_connections optionallist of string (uuid) or null
application_id optionalstring (uuid) or null
budgets_abovelist of objects
key_prefixstring or null
created_atstring (date-time)
closed_atstring (date-time) or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/cards/<id>/close \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/cards/<id>/close",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>/close", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "name": "Chain Scout",
  "state": "active",
  "project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "permission": "read",
  "monthly_allowance_nusd": "18990000",
  "committed_this_month_nusd": "3900000000",
  "held_nusd": "99085600",
  "available_nusd": "18544188800",
  "per_call_limit_nusd": "5000000000",
  "approval_over_nusd": "18990000",
  "allowed_tools": [
    "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  ],
  "allowed_services": [
    "allowed-services"
  ],
  "shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "allowed_connections": [
    "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  ],
  "application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "budgets_above": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "limit_nusd": "5000000000",
      "committed_nusd": "3900000000"
    }
  ],
  "key_prefix": "key-prefix",
  "created_at": "2026-10-24T09:12:03.000Z",
  "closed_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

POST/v1/cards/{id}/keys

Write cards/:id/keys.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
secretstring
Shown once. Only a hash is stored
scopeslist of string
curl -s -X POST http://127.0.0.1:4100/v1/cards/<id>/keys \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/cards/<id>/keys",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>/keys", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "secret": "secret",
  "scopes": [
    "scopes"
  ]
}

DELETE/v1/cards/{id}/keys

Delete cards/:id/keys.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
card_idstring (uuid)
revokedboolean
mode"fixture"
curl -s -X DELETE http://127.0.0.1:4100/v1/cards/<id>/keys \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/cards/<id>/keys",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>/keys", {
  method: "DELETE",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "revoked": false,
  "mode": "fixture"
}

Shared-budgets

POST/v1/shared-budgets

Write shared-budgets.

Key
Bearer
Scope
see the route
Body fieldType
namestring
limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
period optional"month" | "lifetime"
Default month (UTC)
parent_id optionalstring (uuid) or null
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
namestring
limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
period"month" | "lifetime"
parent_idstring (uuid) or null
committed_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
remaining_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
mode optional"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/shared-budgets \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"Chain Scout","limit_nusd":"5000000000","period":"month","parent_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/shared-budgets",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"name":"Chain Scout","limit_nusd":"5000000000","period":"month","parent_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/shared-budgets", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"name":"Chain Scout","limit_nusd":"5000000000","period":"month","parent_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "name": "Chain Scout",
  "limit_nusd": "5000000000",
  "period": "month",
  "parent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "committed_nusd": "3900000000",
  "remaining_nusd": "1100000000",
  "mode": "fixture"
}

GET/v1/shared-budgets

Read shared-budgets.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/shared-budgets \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/shared-budgets",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/shared-budgets", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "name": "Chain Scout",
      "limit_nusd": "5000000000",
      "period": "month",
      "parent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "committed_nusd": "3900000000",
      "remaining_nusd": "1100000000",
      "mode": "fixture"
    }
  ],
  "mode": "fixture"
}

PATCH/v1/shared-budgets/{id}

Write shared-budgets/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
name optionalstring
limit_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
parent_id optionalstring (uuid) or null
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
namestring
limit_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
period"month" | "lifetime"
parent_idstring (uuid) or null
committed_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
remaining_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
mode optional"fixture"
curl -s -X PATCH http://127.0.0.1:4100/v1/shared-budgets/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"Chain Scout","limit_nusd":"5000000000","parent_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"}'
import os, requests
r = requests.patch("http://127.0.0.1:4100/v1/shared-budgets/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"name":"Chain Scout","limit_nusd":"5000000000","parent_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/shared-budgets/<id>", {
  method: "PATCH",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"name":"Chain Scout","limit_nusd":"5000000000","parent_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "name": "Chain Scout",
  "limit_nusd": "5000000000",
  "period": "month",
  "parent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "committed_nusd": "3900000000",
  "remaining_nusd": "1100000000",
  "mode": "fixture"
}

Calls

POST/v1/calls

Write calls.

Key
Bearer
Scope
see the route
Body fieldType
tool_idstring (uuid)
inputsobject
max_cost_nusdnano-USD string
Ceiling on price plus Petrova fee for this call
idempotency_key optionalstring
Send one, and reuse it after a dropped connection. Without one, the response gives you the one it made
run_id optionalstring
wait_ms optionalinteger
How long to wait for an answer before returning the call as it stands. Default 20000. The call keeps going either way
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
tool_idstring (uuid)
card_idstring (uuid) or null
run_idstring or null
idempotency_keystring
Keep this. The same key and inputs always find this call; a new key is new work
state"queued" | "running" | "waiting" | "succeeded" | "failed" | "unknown" | "cancelled"
unknown: the service restarted after the payment may have left. Charged nothing, but the tool may have done the work
waiting_for"approval" | "terms" or null
approval_idstring (uuid) or null
outcome"paid" | "free" | "failed" | "payment_rejected" | "customer_account" or null
errorobject or null
failurestring or null
http_statusinteger or null
price_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
fee_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
held_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
charged_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
charged_usdstring
absorbed_nusdnano-USD string
What Petrova paid and did not charge you
payment_referencestring or null
payment_sentboolean
cancel_requestedboolean
reservation_idstring (uuid) or null
resultany
The tool response, until result_expires_at. Never returned for a call that was not charged because its answer failed a check
result_availableboolean
result_expires_atstring (date-time) or null
result_checkobject or null
provider_hiddenboolean or null
replayedboolean
True when this request found an earlier call instead of starting one
created_atstring (date-time)
finished_atstring (date-time) or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/calls \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key","run_id":"run-id","wait_ms":1}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/calls",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key","run_id":"run-id","wait_ms":1})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/calls", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key","run_id":"run-id","wait_ms":1})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "run_id": "run-id",
  "idempotency_key": "idempotency-key",
  "state": "queued",
  "waiting_for": "approval",
  "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "outcome": "paid",
  "error": {
    "code": "PTRV-7K2Q",
    "message": "message"
  },
  "failure": "failure",
  "http_status": 200,
  "price_nusd": "5000000",
  "fee_nusd": "990000",
  "held_nusd": "99085600",
  "charged_nusd": "18990000",
  "charged_usd": "charged-usd",
  "absorbed_nusd": "0",
  "payment_reference": "payment-reference",
  "payment_sent": false,
  "cancel_requested": false,
  "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "result": null,
  "result_available": false,
  "result_expires_at": "2026-10-24T09:12:03.000Z",
  "result_check": {},
  "provider_hidden": false,
  "replayed": false,
  "created_at": "2026-10-24T09:12:03.000Z",
  "finished_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

GET/v1/calls

Read calls.

Key
Bearer
Scope
see the route
ParameterIn · type
state optionalquery · "queued" | "running" | "waiting" | "succeeded" | "failed" | "unknown" | "cancelled"
tool_id optionalquery · string (uuid)
run_id optionalquery · string
card_id optionalquery · string (uuid)
idempotency_key optionalquery · string
limit optionalquery · integer
cursor optionalquery · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
next_cursorstring or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/calls \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/calls",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/calls", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "run_id": "run-id",
      "idempotency_key": "idempotency-key",
      "state": "queued",
      "waiting_for": "approval",
      "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "outcome": "paid",
      "error": {
        "code": "PTRV-7K2Q",
        "message": "message"
      },
      "failure": "failure",
      "http_status": 200,
      "price_nusd": "5000000",
      "fee_nusd": "990000",
      "held_nusd": "99085600",
      "charged_nusd": "18990000",
      "charged_usd": "charged-usd",
      "absorbed_nusd": "0",
      "payment_reference": "payment-reference",
      "payment_sent": false,
      "cancel_requested": false,
      "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "result": null,
      "result_available": false,
      "result_expires_at": "2026-10-24T09:12:03.000Z",
      "result_check": {},
      "provider_hidden": false,
      "replayed": false,
      "created_at": "2026-10-24T09:12:03.000Z",
      "finished_at": "2026-10-24T09:12:03.000Z",
      "mode": "fixture"
    }
  ],
  "next_cursor": "next-cursor",
  "mode": "fixture"
}

GET/v1/calls/{id}

Read calls/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
tool_idstring (uuid)
card_idstring (uuid) or null
run_idstring or null
idempotency_keystring
Keep this. The same key and inputs always find this call; a new key is new work
state"queued" | "running" | "waiting" | "succeeded" | "failed" | "unknown" | "cancelled"
unknown: the service restarted after the payment may have left. Charged nothing, but the tool may have done the work
waiting_for"approval" | "terms" or null
approval_idstring (uuid) or null
outcome"paid" | "free" | "failed" | "payment_rejected" | "customer_account" or null
errorobject or null
failurestring or null
http_statusinteger or null
price_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
fee_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
held_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
charged_nusdnano-USD string
Integer nano-USD, 1 USD = 1000000000
charged_usdstring
absorbed_nusdnano-USD string
What Petrova paid and did not charge you
payment_referencestring or null
payment_sentboolean
cancel_requestedboolean
reservation_idstring (uuid) or null
resultany
The tool response, until result_expires_at. Never returned for a call that was not charged because its answer failed a check
result_availableboolean
result_expires_atstring (date-time) or null
result_checkobject or null
provider_hiddenboolean or null
replayedboolean
True when this request found an earlier call instead of starting one
created_atstring (date-time)
finished_atstring (date-time) or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/calls/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/calls/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/calls/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "run_id": "run-id",
  "idempotency_key": "idempotency-key",
  "state": "queued",
  "waiting_for": "approval",
  "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "outcome": "paid",
  "error": {
    "code": "PTRV-7K2Q",
    "message": "message"
  },
  "failure": "failure",
  "http_status": 200,
  "price_nusd": "5000000",
  "fee_nusd": "990000",
  "held_nusd": "99085600",
  "charged_nusd": "18990000",
  "charged_usd": "charged-usd",
  "absorbed_nusd": "0",
  "payment_reference": "payment-reference",
  "payment_sent": false,
  "cancel_requested": false,
  "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "result": null,
  "result_available": false,
  "result_expires_at": "2026-10-24T09:12:03.000Z",
  "result_check": {},
  "provider_hidden": false,
  "replayed": false,
  "created_at": "2026-10-24T09:12:03.000Z",
  "finished_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

POST/v1/calls/{id}/cancel

Write calls/:id/cancel.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
effect"cancelled" | "requested" | "too_late" | "already_finished"
too_late: the payment went out, so the work may finish and be charged. Read the call again for the final answer
callobject
curl -s -X POST http://127.0.0.1:4100/v1/calls/<id>/cancel \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/calls/<id>/cancel",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/calls/<id>/cancel", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "effect": "cancelled",
  "call": {
    "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "run_id": "run-id",
    "idempotency_key": "idempotency-key",
    "state": "queued",
    "waiting_for": "approval",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "outcome": "paid",
    "error": {
      "code": "PTRV-7K2Q",
      "message": "message"
    },
    "failure": "failure",
    "http_status": 200,
    "price_nusd": "5000000",
    "fee_nusd": "990000",
    "held_nusd": "99085600",
    "charged_nusd": "18990000",
    "charged_usd": "charged-usd",
    "absorbed_nusd": "0",
    "payment_reference": "payment-reference",
    "payment_sent": false,
    "cancel_requested": false,
    "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "result": null,
    "result_available": false,
    "result_expires_at": "2026-10-24T09:12:03.000Z",
    "result_check": {},
    "provider_hidden": false,
    "replayed": false,
    "created_at": "2026-10-24T09:12:03.000Z",
    "finished_at": "2026-10-24T09:12:03.000Z",
    "mode": "fixture"
  }
}

Runs

GET/v1/runs/{id}

Read runs/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
run_idstring
callsinteger
statesobject
total_charged_nusdnano-USD string
What this run cost, less anything given back
held_nusdnano-USD string
Still held for calls in flight
first_call_atstring (date-time) or null
last_call_atstring (date-time) or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/runs/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/runs/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/runs/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "run_id": "run-id",
  "calls": 1,
  "states": {},
  "total_charged_nusd": "18990000",
  "held_nusd": "99085600",
  "first_call_at": "2026-10-24T09:12:03.000Z",
  "last_call_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

Approvals

GET/v1/approvals

Read approvals.

Key
Bearer
Scope
see the route
ParameterIn · type
state optionalquery · "pending" | "approved" | "rejected" | "expired" | "cancelled"
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/approvals \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/approvals",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/approvals", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "state": "pending",
      "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "provider": "anthropic",
      "run_id": "run-id",
      "price_nusd": "5000000",
      "fee_nusd": "990000",
      "amount_nusd": "20000000000",
      "amount_usd": "amount-usd",
      "inputs": null,
      "expires_at": "2026-10-24T09:12:03.000Z",
      "decided_at": "2026-10-24T09:12:03.000Z",
      "created_at": "2026-10-24T09:12:03.000Z",
      "mode": "fixture"
    }
  ],
  "mode": "fixture"
}

POST/v1/approvals/{id}/decide

Write approvals/:id/decide.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
decision"approve" | "reject"
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
approvalobject
callobject
curl -s -X POST http://127.0.0.1:4100/v1/approvals/<id>/decide \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"decision":"approve"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/approvals/<id>/decide",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"decision":"approve"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/approvals/<id>/decide", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"decision":"approve"})
});
console.log(await r.json());
{
  "approval": {
    "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "state": "pending",
    "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "provider": "anthropic",
    "run_id": "run-id",
    "price_nusd": "5000000",
    "fee_nusd": "990000",
    "amount_nusd": "20000000000",
    "amount_usd": "amount-usd",
    "inputs": null,
    "expires_at": "2026-10-24T09:12:03.000Z",
    "decided_at": "2026-10-24T09:12:03.000Z",
    "created_at": "2026-10-24T09:12:03.000Z",
    "mode": "fixture"
  },
  "call": {
    "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "run_id": "run-id",
    "idempotency_key": "idempotency-key",
    "state": "queued",
    "waiting_for": "approval",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "outcome": "paid",
    "error": {
      "code": "PTRV-7K2Q",
      "message": "message"
    },
    "failure": "failure",
    "http_status": 200,
    "price_nusd": "5000000",
    "fee_nusd": "990000",
    "held_nusd": "99085600",
    "charged_nusd": "18990000",
    "charged_usd": "charged-usd",
    "absorbed_nusd": "0",
    "payment_reference": "payment-reference",
    "payment_sent": false,
    "cancel_requested": false,
    "reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "result": null,
    "result_available": false,
    "result_expires_at": "2026-10-24T09:12:03.000Z",
    "result_check": {},
    "provider_hidden": false,
    "replayed": false,
    "created_at": "2026-10-24T09:12:03.000Z",
    "finished_at": "2026-10-24T09:12:03.000Z",
    "mode": "fixture"
  }
}

Agent

POST/v1/agent/search

Write agent/search.

Key
Bearer
Scope
see the route
Body fieldType
query optionalstring
What you need, in plain words. Omit to browse
provider optionalstring
Only this provider slug, e.g. exa
limit optionalinteger
tiers optionallist of "listed" | "verified" | "proven"
max_price optionalstring
Highest price per call in USD, e.g. "0.05"
cursor optionalstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
kind"ok"
reason"found" | "nothing_found"
messagestring
next_actionobject
What to do now. Always present
itemslist of objects
next_cursorstring or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/agent/search \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"query":"new tokens with more than $40k liquidity","provider":"anthropic","limit":1,"tiers":["listed"],"max_price":"max-price","cursor":"12"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/search",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"query":"new tokens with more than $40k liquidity","provider":"anthropic","limit":1,"tiers":["listed"],"max_price":"max-price","cursor":"12"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent/search", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"query":"new tokens with more than $40k liquidity","provider":"anthropic","limit":1,"tiers":["listed"],"max_price":"max-price","cursor":"12"})
});
console.log(await r.json());
{
  "kind": "ok",
  "reason": "found",
  "message": "message",
  "next_action": {
    "kind": "kind",
    "message": "message",
    "command": "command",
    "tool": {},
    "link": {
      "purpose": "fund",
      "url": "https://chain-scout.example/v1/ask",
      "code": "PTRV-7K2Q",
      "expires_at": "2026-10-24T09:12:03.000Z",
      "amount_nusd": "20000000000"
    },
    "say_to_person": "say-to-person",
    "accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  },
  "items": [
    {
      "provider": "anthropic",
      "method": "GET",
      "path": "path",
      "tier": "listed",
      "availability": "priced",
      "pricing": {
        "kind": "fixed",
        "summary": "New token FOO launched with $42,000 liquidity"
      }
    }
  ],
  "next_cursor": "next-cursor",
  "mode": "fixture"
}

POST/v1/agent/inspect

Write agent/inspect.

Key
Bearer
Scope
see the route
Body fieldType
tool_id optionalstring (uuid)
Call by id instead of provider and path
provider optionalstring
Provider slug from search, e.g. exa
path optionalstring
Path template from search, e.g. /search. Put {placeholder} values in path_params
method optional"GET" | "POST" | "PUT" | "PATCH" | "DELETE"
Optional when the path serves one method
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
kind"ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"
ok: the answer, its cost and a receipt. needs_funding: no money or not enough, a link for the person. over_limit: over a limit only the person can raise. needs_approval: the person must say yes. price_changed: new terms (accept with accept_terms, or a new key and a higher maximum). failed: the tool failed, charged $0. pending: read it again with the same key. paused: the person paused this agent. refused: stopped, see refused_by. not_started: nothing began with that key
refused_by"auth" | "person" | "policy" | "balance" | "budget" | "cap" | "resolution" | "request" | "listing" | "payment" | "provider" or null
reasonstring
A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ...
messagestring
The same in plain words, always saying what was charged
next_actionobject
What to do now. Always present
receipt optionalobject or null
balance optionalobject
What is left: balance, monthly limit, what the next call can spend
warnings optionallist of objects
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/agent/inspect \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/inspect",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent/inspect", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET"})
});
console.log(await r.json());
{
  "kind": "ok",
  "refused_by": "auth",
  "reason": "reason",
  "message": "message",
  "next_action": {
    "kind": "kind",
    "message": "message",
    "command": "command",
    "tool": {},
    "link": {
      "purpose": "fund",
      "url": "https://chain-scout.example/v1/ask",
      "code": "PTRV-7K2Q",
      "expires_at": "2026-10-24T09:12:03.000Z",
      "amount_nusd": "20000000000"
    },
    "say_to_person": "say-to-person",
    "accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  },
  "receipt": {
    "call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "idempotency_key": "idempotency-key",
    "charged_nusd": "18990000",
    "charge_status": "pending"
  },
  "balance": {},
  "warnings": [
    {
      "kind": "low_balance"
    }
  ],
  "mode": "fixture"
}

POST/v1/agent/calls

Write agent/calls.

Key
Bearer
Scope
see the route
Body fieldType
tool_id optionalstring (uuid)
Call by id instead of provider and path
provider optionalstring
Provider slug from search, e.g. exa
path optionalstring
Path template from search, e.g. /search. Put {placeholder} values in path_params
method optional"GET" | "POST" | "PUT" | "PATCH" | "DELETE"
Optional when the path serves one method
inputs optionalobject
One object checked against the tool's input schema. Or give path_params, query, headers and body
path_params optionalobject
query optionalobject
headers optionalobject
body optionalany
idempotency_keystring
New for each new call. Reuse it to retry, recover, or accept terms for the same call
max_cost optionalstring
Most this call may charge, fee included, in USD. Default "1.00"
max_cost_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
accept_terms optionalstring (uuid)
From next_action.accept_terms of a price_changed answer. Repeat the original arguments unchanged, with the same key
credential_mode optional"wallet" | "customer"
customer: call on your own provider account (connection_id). Never falls back to the wallet
connection_id optionalstring (uuid)
run_id optionalstring
wait_ms optionalinteger
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
kind"ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"
ok: the answer, its cost and a receipt. needs_funding: no money or not enough, a link for the person. over_limit: over a limit only the person can raise. needs_approval: the person must say yes. price_changed: new terms (accept with accept_terms, or a new key and a higher maximum). failed: the tool failed, charged $0. pending: read it again with the same key. paused: the person paused this agent. refused: stopped, see refused_by. not_started: nothing began with that key
refused_by"auth" | "person" | "policy" | "balance" | "budget" | "cap" | "resolution" | "request" | "listing" | "payment" | "provider" or null
reasonstring
A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ...
messagestring
The same in plain words, always saying what was charged
next_actionobject
What to do now. Always present
receipt optionalobject or null
balance optionalobject
What is left: balance, monthly limit, what the next call can spend
warnings optionallist of objects
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/agent/calls \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null,"idempotency_key":"idempotency-key","max_cost":"max-cost","max_cost_nusd":"18990000","accept_terms":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","credential_mode":"wallet","connection_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","run_id":"run-id","wait_ms":1}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/calls",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null,"idempotency_key":"idempotency-key","max_cost":"max-cost","max_cost_nusd":"18990000","accept_terms":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","credential_mode":"wallet","connection_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","run_id":"run-id","wait_ms":1})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent/calls", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null,"idempotency_key":"idempotency-key","max_cost":"max-cost","max_cost_nusd":"18990000","accept_terms":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","credential_mode":"wallet","connection_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","run_id":"run-id","wait_ms":1})
});
console.log(await r.json());
{
  "kind": "ok",
  "refused_by": "auth",
  "reason": "reason",
  "message": "message",
  "next_action": {
    "kind": "kind",
    "message": "message",
    "command": "command",
    "tool": {},
    "link": {
      "purpose": "fund",
      "url": "https://chain-scout.example/v1/ask",
      "code": "PTRV-7K2Q",
      "expires_at": "2026-10-24T09:12:03.000Z",
      "amount_nusd": "20000000000"
    },
    "say_to_person": "say-to-person",
    "accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  },
  "receipt": {
    "call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "idempotency_key": "idempotency-key",
    "charged_nusd": "18990000",
    "charge_status": "pending"
  },
  "balance": {},
  "warnings": [
    {
      "kind": "low_balance"
    }
  ],
  "mode": "fixture"
}

GET/v1/agent/calls

Read agent/calls.

Key
Bearer
Scope
see the route
ParameterIn · type
idempotency_key optionalquery · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
kind"ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"
ok: the answer, its cost and a receipt. needs_funding: no money or not enough, a link for the person. over_limit: over a limit only the person can raise. needs_approval: the person must say yes. price_changed: new terms (accept with accept_terms, or a new key and a higher maximum). failed: the tool failed, charged $0. pending: read it again with the same key. paused: the person paused this agent. refused: stopped, see refused_by. not_started: nothing began with that key
refused_by"auth" | "person" | "policy" | "balance" | "budget" | "cap" | "resolution" | "request" | "listing" | "payment" | "provider" or null
reasonstring
A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ...
messagestring
The same in plain words, always saying what was charged
next_actionobject
What to do now. Always present
receipt optionalobject or null
balance optionalobject
What is left: balance, monthly limit, what the next call can spend
warnings optionallist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/agent/calls \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/agent/calls",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent/calls", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "kind": "ok",
  "refused_by": "auth",
  "reason": "reason",
  "message": "message",
  "next_action": {
    "kind": "kind",
    "message": "message",
    "command": "command",
    "tool": {},
    "link": {
      "purpose": "fund",
      "url": "https://chain-scout.example/v1/ask",
      "code": "PTRV-7K2Q",
      "expires_at": "2026-10-24T09:12:03.000Z",
      "amount_nusd": "20000000000"
    },
    "say_to_person": "say-to-person",
    "accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  },
  "receipt": {
    "call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "idempotency_key": "idempotency-key",
    "charged_nusd": "18990000",
    "charge_status": "pending"
  },
  "balance": {},
  "warnings": [
    {
      "kind": "low_balance"
    }
  ],
  "mode": "fixture"
}

GET/v1/agent/calls/{id}

Read agent/calls/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
kind"ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"
ok: the answer, its cost and a receipt. needs_funding: no money or not enough, a link for the person. over_limit: over a limit only the person can raise. needs_approval: the person must say yes. price_changed: new terms (accept with accept_terms, or a new key and a higher maximum). failed: the tool failed, charged $0. pending: read it again with the same key. paused: the person paused this agent. refused: stopped, see refused_by. not_started: nothing began with that key
refused_by"auth" | "person" | "policy" | "balance" | "budget" | "cap" | "resolution" | "request" | "listing" | "payment" | "provider" or null
reasonstring
A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ...
messagestring
The same in plain words, always saying what was charged
next_actionobject
What to do now. Always present
receipt optionalobject or null
balance optionalobject
What is left: balance, monthly limit, what the next call can spend
warnings optionallist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/agent/calls/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/agent/calls/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent/calls/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "kind": "ok",
  "refused_by": "auth",
  "reason": "reason",
  "message": "message",
  "next_action": {
    "kind": "kind",
    "message": "message",
    "command": "command",
    "tool": {},
    "link": {
      "purpose": "fund",
      "url": "https://chain-scout.example/v1/ask",
      "code": "PTRV-7K2Q",
      "expires_at": "2026-10-24T09:12:03.000Z",
      "amount_nusd": "20000000000"
    },
    "say_to_person": "say-to-person",
    "accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  },
  "receipt": {
    "call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "idempotency_key": "idempotency-key",
    "charged_nusd": "18990000",
    "charge_status": "pending"
  },
  "balance": {},
  "warnings": [
    {
      "kind": "low_balance"
    }
  ],
  "mode": "fixture"
}

POST/v1/agent/calls/{id}/outcome

Write agent/calls/:id/outcome.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
outcome"succeeded" | "failed" | "not-useful"
reason_code optional"wrong_result" | "low_quality" | "stale" | "too_slow" | "bad_format" | "other"
note optionalstring
Accepted and not stored: reports are codes only
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
acceptedboolean
duplicateboolean
True when this call was already reported. The first report stands
invocation_idstring (uuid)
counts_in_rankingboolean
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/agent/calls/<id>/outcome \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"outcome":"succeeded","reason_code":"wrong_result","note":"note"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/calls/<id>/outcome",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"outcome":"succeeded","reason_code":"wrong_result","note":"note"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent/calls/<id>/outcome", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"outcome":"succeeded","reason_code":"wrong_result","note":"note"})
});
console.log(await r.json());
{
  "accepted": false,
  "duplicate": false,
  "invocation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "counts_in_ranking": false,
  "mode": "fixture"
}

GET/v1/agent/status

Read agent/status.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
Response fields
kind"ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"
refused_bystring or null
reasonstring
messagestring
next_actionobject
What to do now. Always present
curl -s http://127.0.0.1:4100/v1/agent/status \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/agent/status",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent/status", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "kind": "ok",
  "refused_by": "refused-by",
  "reason": "reason",
  "message": "message",
  "next_action": {
    "kind": "kind",
    "message": "message",
    "command": "command",
    "tool": {},
    "link": {
      "purpose": "fund",
      "url": "https://chain-scout.example/v1/ask",
      "code": "PTRV-7K2Q",
      "expires_at": "2026-10-24T09:12:03.000Z",
      "amount_nusd": "20000000000"
    },
    "say_to_person": "say-to-person",
    "accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  }
}

POST/v1/agent/links

Write agent/links.

Key
Bearer
Scope
see the route
Body fieldType
amount_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
Response fields
kind"ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"
refused_bystring or null
reasonstring
messagestring
next_actionobject
What to do now. Always present
curl -s -X POST http://127.0.0.1:4100/v1/agent/links \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"amount_nusd":"20000000000"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/links",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"amount_nusd":"20000000000"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/agent/links", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"amount_nusd":"20000000000"})
});
console.log(await r.json());
{
  "kind": "ok",
  "refused_by": "refused-by",
  "reason": "reason",
  "message": "message",
  "next_action": {
    "kind": "kind",
    "message": "message",
    "command": "command",
    "tool": {},
    "link": {
      "purpose": "fund",
      "url": "https://chain-scout.example/v1/ask",
      "code": "PTRV-7K2Q",
      "expires_at": "2026-10-24T09:12:03.000Z",
      "amount_nusd": "20000000000"
    },
    "say_to_person": "say-to-person",
    "accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
  }
}

Applications

POST/v1/applications

Write applications.

Key
Bearer
Scope
see the route
Body fieldType
external_idstring
Your id for the customer company. The same id returns the same application
labelstring
cap_nusdnano-USD string
Spending cap for every key of this application together
period optional"lifetime" | "month"
Default lifetime: it never resets
per_call_limit_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
confirmation optional"require" | "unattended"
require: a person approves every paid call. Default unattended, within the caps
project_id optionalstring (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
applicationobject
createdboolean
curl -s -X POST http://127.0.0.1:4100/v1/applications \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"external_id":"ptrv-ext-3c9a1f","label":"label","cap_nusd":"5000000000","period":"lifetime","per_call_limit_nusd":"5000000000","confirmation":"require","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/applications",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"external_id":"ptrv-ext-3c9a1f","label":"label","cap_nusd":"5000000000","period":"lifetime","per_call_limit_nusd":"5000000000","confirmation":"require","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/applications", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"external_id":"ptrv-ext-3c9a1f","label":"label","cap_nusd":"5000000000","period":"lifetime","per_call_limit_nusd":"5000000000","confirmation":"require","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
});
console.log(await r.json());
{
  "application": {
    "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "external_id": "ptrv-ext-3c9a1f",
    "label": "label",
    "state": "active",
    "confirmation": "require",
    "cap": {},
    "keys": [
      {}
    ],
    "mode": "fixture"
  },
  "created": false
}

GET/v1/applications

Read applications.

Key
Bearer
Scope
see the route
ParameterIn · type
external_id optionalquery · string
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/applications \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/applications",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/applications", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "external_id": "ptrv-ext-3c9a1f",
      "label": "label",
      "state": "active",
      "confirmation": "require",
      "cap": {},
      "keys": [
        {}
      ],
      "mode": "fixture"
    }
  ],
  "mode": "fixture"
}

GET/v1/applications/{id}

Read applications/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
external_idstring
labelstring
state"active" | "disabled"
confirmation optional"require" | "unattended"
capobject
keyslist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/applications/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/applications/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "external_id": "ptrv-ext-3c9a1f",
  "label": "label",
  "state": "active",
  "confirmation": "require",
  "cap": {},
  "keys": [
    {}
  ],
  "mode": "fixture"
}

PATCH/v1/applications/{id}

Write applications/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
label optionalstring
cap_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
confirmation optional"require" | "unattended"
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
external_idstring
labelstring
state"active" | "disabled"
confirmation optional"require" | "unattended"
capobject
keyslist of objects
mode"fixture"
curl -s -X PATCH http://127.0.0.1:4100/v1/applications/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"label":"label","cap_nusd":"5000000000","confirmation":"require"}'
import os, requests
r = requests.patch("http://127.0.0.1:4100/v1/applications/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"label":"label","cap_nusd":"5000000000","confirmation":"require"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>", {
  method: "PATCH",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"label":"label","cap_nusd":"5000000000","confirmation":"require"})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "external_id": "ptrv-ext-3c9a1f",
  "label": "label",
  "state": "active",
  "confirmation": "require",
  "cap": {},
  "keys": [
    {}
  ],
  "mode": "fixture"
}

POST/v1/applications/{id}/disable

Write applications/:id/disable.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
external_idstring
labelstring
state"active" | "disabled"
confirmation optional"require" | "unattended"
capobject
keyslist of objects
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/applications/<id>/disable \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/applications/<id>/disable",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>/disable", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "external_id": "ptrv-ext-3c9a1f",
  "label": "label",
  "state": "active",
  "confirmation": "require",
  "cap": {},
  "keys": [
    {}
  ],
  "mode": "fixture"
}

POST/v1/applications/{id}/keys

Write applications/:id/keys.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
keyobject or null
replayedboolean
applicationobject
curl -s -X POST http://127.0.0.1:4100/v1/applications/<id>/keys \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d 'null'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/applications/<id>/keys",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json=null)
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>/keys", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify(null)
});
console.log(await r.json());
{
  "key": {
    "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "secret": "secret",
    "scopes": [
      "scopes"
    ]
  },
  "replayed": false,
  "application": {
    "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
    "external_id": "ptrv-ext-3c9a1f",
    "label": "label",
    "state": "active",
    "confirmation": "require",
    "cap": {},
    "keys": [
      {}
    ],
    "mode": "fixture"
  }
}

DELETE/v1/applications/{id}/keys/{card}

Delete applications/:id/keys/:card.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
cardpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
external_idstring
labelstring
state"active" | "disabled"
confirmation optional"require" | "unattended"
capobject
keyslist of objects
mode"fixture"
curl -s -X DELETE http://127.0.0.1:4100/v1/applications/<id>/keys/<card> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/applications/<id>/keys/<card>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>/keys/<card>", {
  method: "DELETE",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "external_id": "ptrv-ext-3c9a1f",
  "label": "label",
  "state": "active",
  "confirmation": "require",
  "cap": {},
  "keys": [
    {}
  ],
  "mode": "fixture"
}

GET/v1/applications/{id}/calls

Read applications/:id/calls.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
partition optionalquery · string
limit optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
curl -s http://127.0.0.1:4100/v1/applications/<id>/calls \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/applications/<id>/calls",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>/calls", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{}

Connections

POST/v1/connections

Write connections.

Key
Bearer
Scope
see the route
Body fieldType
providerstring
Provider slug, e.g. exa
labelstring
base_urlstring
Where the provider's own API lives, e.g. https://api.exa.ai
auth_header optionalstring
Default authorization
auth_prefix optionalstring
Default "Bearer " for authorization, empty otherwise
secretstring
Your provider API key. Stored encrypted, never returned
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
provider_keystring
provider_slugstring or null
labelstring
base_urlstring
auth_headerstring
hintstring or null
state"active" | "revoked"
created_atstring (date-time)
revoked_atstring (date-time) or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/connections \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"provider":"anthropic","label":"label","base_url":"https://example.invalid/","auth_header":"auth-header","auth_prefix":"auth-prefix","secret":"secret"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/connections",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"provider":"anthropic","label":"label","base_url":"https://example.invalid/","auth_header":"auth-header","auth_prefix":"auth-prefix","secret":"secret"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/connections", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"provider":"anthropic","label":"label","base_url":"https://example.invalid/","auth_header":"auth-header","auth_prefix":"auth-prefix","secret":"secret"})
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "provider_key": "provider-key",
  "provider_slug": "provider-slug",
  "label": "label",
  "base_url": "https://example.invalid/",
  "auth_header": "auth-header",
  "hint": "hint",
  "state": "active",
  "created_at": "2026-10-24T09:12:03.000Z",
  "revoked_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

GET/v1/connections

Read connections.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/connections \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/connections",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/connections", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "provider_key": "provider-key",
      "provider_slug": "provider-slug",
      "label": "label",
      "base_url": "https://example.invalid/",
      "auth_header": "auth-header",
      "hint": "hint",
      "state": "active",
      "created_at": "2026-10-24T09:12:03.000Z",
      "revoked_at": "2026-10-24T09:12:03.000Z",
      "mode": "fixture"
    }
  ],
  "mode": "fixture"
}

GET/v1/connections/{id}

Read connections/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
provider_keystring
provider_slugstring or null
labelstring
base_urlstring
auth_headerstring
hintstring or null
state"active" | "revoked"
created_atstring (date-time)
revoked_atstring (date-time) or null
mode"fixture"
curl -s http://127.0.0.1:4100/v1/connections/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/connections/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/connections/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "provider_key": "provider-key",
  "provider_slug": "provider-slug",
  "label": "label",
  "base_url": "https://example.invalid/",
  "auth_header": "auth-header",
  "hint": "hint",
  "state": "active",
  "created_at": "2026-10-24T09:12:03.000Z",
  "revoked_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

DELETE/v1/connections/{id}

Delete connections/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
provider_keystring
provider_slugstring or null
labelstring
base_urlstring
auth_headerstring
hintstring or null
state"active" | "revoked"
created_atstring (date-time)
revoked_atstring (date-time) or null
mode"fixture"
curl -s -X DELETE http://127.0.0.1:4100/v1/connections/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/connections/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/connections/<id>", {
  method: "DELETE",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "provider_key": "provider-key",
  "provider_slug": "provider-slug",
  "label": "label",
  "base_url": "https://example.invalid/",
  "auth_header": "auth-header",
  "hint": "hint",
  "state": "active",
  "created_at": "2026-10-24T09:12:03.000Z",
  "revoked_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

Operator

GET/v1/operator/tool-economics

Read operator/tool-economics.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
arithmeticobject
totalobject
providerslist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/operator/tool-economics \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/operator/tool-economics",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/operator/tool-economics", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "arithmetic": {},
  "total": {},
  "providers": [
    {}
  ],
  "mode": "fixture"
}

GET/v1/operator/listings

Read operator/listings.

Key
Bearer
Scope
see the route
ParameterIn · type
state optionalquery · "in_review" | "changes_requested" | "approved" | "superseded" | "rejected" | "withdrawn" | "draft"
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/operator/listings \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/operator/listings",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/operator/listings", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "version_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "listing": "listing",
      "number": 1,
      "state": "state",
      "product_state": "product-state",
      "seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "host": "host",
      "host_verified": false,
      "host_verified_by": "host-verified-by",
      "local_fixture": false,
      "preview": {
        "listing_id": "listing-id",
        "name": "Chain Scout",
        "category": "search",
        "host": "host",
        "auth": "none",
        "auth_header": "auth-header",
        "fee_bps": 750,
        "endpoints": [
          null
        ],
        "confirm_hash": "confirm-hash"
      },
      "changes": [
        {
          "endpoint": null,
          "field": null,
          "from": null,
          "to": null,
          "material": null
        }
      ],
      "material_change": false,
      "contact_email": "contact-email",
      "review_notes": "review-notes",
      "submitted_at": "2026-10-24T09:12:03.000Z",
      "reviewed_at": "2026-10-24T09:12:03.000Z",
      "mode": "fixture"
    }
  ],
  "mode": "fixture"
}

GET/v1/operator/listings/versions/{id}

Read operator/listings/versions/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
version_idstring (uuid)
listing_idstring (uuid)
listingstring
numberinteger
statestring
product_statestring
seller_agent_idstring (uuid)
hoststring
host_verifiedboolean
host_verified_bystring or null
local_fixtureboolean
previewobject
changeslist of objects
material_changeboolean
contact_emailstring
review_notesstring or null
submitted_atstring (date-time) or null
reviewed_atstring (date-time) or null
mode"fixture"
filestring
curl -s http://127.0.0.1:4100/v1/operator/listings/versions/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/operator/listings/versions/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/operator/listings/versions/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "version_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "listing": "listing",
  "number": 1,
  "state": "state",
  "product_state": "product-state",
  "seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "host": "host",
  "host_verified": false,
  "host_verified_by": "host-verified-by",
  "local_fixture": false,
  "preview": {
    "listing_id": "listing-id",
    "name": "Chain Scout",
    "category": "search",
    "host": "host",
    "auth": "none",
    "auth_header": "auth-header",
    "fee_bps": 750,
    "endpoints": [
      {
        "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
        "name": "Chain Scout",
        "method": "GET",
        "url": "https://chain-scout.example/v1/ask",
        "inputs": [
          null
        ],
        "required": [
          null
        ],
        "success": "success",
        "checks_output": false,
        "buyer_pays_nusd": "18990000",
        "buyer_pays_usd": "buyer-pays-usd",
        "fee_nusd": "990000",
        "you_keep_nusd": "18990000"
      }
    ],
    "confirm_hash": "confirm-hash"
  },
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "material_change": false,
  "contact_email": "contact-email",
  "review_notes": "review-notes",
  "submitted_at": "2026-10-24T09:12:03.000Z",
  "reviewed_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture",
  "file": "file"
}

POST/v1/operator/listings/versions/{id}/decide

Write operator/listings/versions/:id/decide.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
decision"approve" | "request_changes" | "reject"
notes optionalstring
Required unless approving. The seller reads this
attest_host optionalboolean
You checked this seller controls the host yourself, because this build cannot contact a real one
take_over optionalboolean
Give the seller a URL a directory already lists. Never another seller's
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
version_idstring (uuid)
listing_idstring (uuid)
listingstring
numberinteger
statestring
product_statestring
seller_agent_idstring (uuid)
hoststring
host_verifiedboolean
host_verified_bystring or null
local_fixtureboolean
previewobject
changeslist of objects
material_changeboolean
contact_emailstring
review_notesstring or null
submitted_atstring (date-time) or null
reviewed_atstring (date-time) or null
mode"fixture"
filestring
curl -s -X POST http://127.0.0.1:4100/v1/operator/listings/versions/<id>/decide \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"decision":"approve","notes":"notes","attest_host":false,"take_over":false}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/operator/listings/versions/<id>/decide",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"decision":"approve","notes":"notes","attest_host":false,"take_over":false})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/operator/listings/versions/<id>/decide", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"decision":"approve","notes":"notes","attest_host":false,"take_over":false})
});
console.log(await r.json());
{
  "version_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "listing": "listing",
  "number": 1,
  "state": "state",
  "product_state": "product-state",
  "seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "host": "host",
  "host_verified": false,
  "host_verified_by": "host-verified-by",
  "local_fixture": false,
  "preview": {
    "listing_id": "listing-id",
    "name": "Chain Scout",
    "category": "search",
    "host": "host",
    "auth": "none",
    "auth_header": "auth-header",
    "fee_bps": 750,
    "endpoints": [
      {
        "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
        "name": "Chain Scout",
        "method": "GET",
        "url": "https://chain-scout.example/v1/ask",
        "inputs": [
          null
        ],
        "required": [
          null
        ],
        "success": "success",
        "checks_output": false,
        "buyer_pays_nusd": "18990000",
        "buyer_pays_usd": "buyer-pays-usd",
        "fee_nusd": "990000",
        "you_keep_nusd": "18990000"
      }
    ],
    "confirm_hash": "confirm-hash"
  },
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "material_change": false,
  "contact_email": "contact-email",
  "review_notes": "review-notes",
  "submitted_at": "2026-10-24T09:12:03.000Z",
  "reviewed_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture",
  "file": "file"
}

POST/v1/operator/listings/{id}/suspend

Write operator/listings/:id/suspend.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
reasonstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
version optionalinteger
statestring
replayed optionalboolean
warning optionalstring or null
changes optionallist of objects or null
reason optionalstring or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/operator/listings/<id>/suspend \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"reason":"reason"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/operator/listings/<id>/suspend",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"reason":"reason"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/operator/listings/<id>/suspend", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"reason":"reason"})
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "version": 1,
  "state": "state",
  "replayed": false,
  "warning": "warning",
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "reason": "reason",
  "mode": "fixture"
}

POST/v1/operator/listings/{id}/reinstate

Write operator/listings/:id/reinstate.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
version optionalinteger
statestring
replayed optionalboolean
warning optionalstring or null
changes optionallist of objects or null
reason optionalstring or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/operator/listings/<id>/reinstate \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/operator/listings/<id>/reinstate",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/operator/listings/<id>/reinstate", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "version": 1,
  "state": "state",
  "replayed": false,
  "warning": "warning",
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "reason": "reason",
  "mode": "fixture"
}

Me

GET/v1/me

Read me.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
key_idstring (uuid)
scopeslist of string
card_idstring (uuid) or null
kind"card" | "owner" | "operator"
mode"fixture"
live_spend_enabledfalse
curl -s http://127.0.0.1:4100/v1/me \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/me",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/me", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "key_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "scopes": [
    "scopes"
  ],
  "card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "kind": "card",
  "mode": "fixture",
  "live_spend_enabled": false
}

Seller

POST/v1/seller/validate

Write seller/validate.

Key
Bearer
Scope
see the route
Body fieldType
filestring
The text of petrova.yaml. JSON is YAML, so JSON works too
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
validboolean
errorslist of objects
warningslist of objects
previewobject or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/seller/validate \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"file":"file"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/validate",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"file":"file"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/validate", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"file":"file"})
});
console.log(await r.json());
{
  "valid": false,
  "errors": [
    {
      "path": "path",
      "code": "PTRV-7K2Q",
      "message": "message",
      "fix": "fix"
    }
  ],
  "warnings": [
    {
      "path": "path",
      "code": "PTRV-7K2Q",
      "message": "message",
      "fix": "fix"
    }
  ],
  "preview": {
    "listing_id": "listing-id",
    "name": "Chain Scout",
    "category": "search",
    "host": "host",
    "auth": "none",
    "auth_header": "auth-header",
    "fee_bps": 750,
    "endpoints": [
      {
        "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
        "name": "Chain Scout",
        "method": "GET",
        "url": "https://chain-scout.example/v1/ask",
        "inputs": [
          null
        ],
        "required": [
          null
        ],
        "success": "success",
        "checks_output": false,
        "buyer_pays_nusd": "18990000",
        "buyer_pays_usd": "buyer-pays-usd",
        "fee_nusd": "990000",
        "you_keep_nusd": "18990000"
      }
    ],
    "confirm_hash": "confirm-hash"
  },
  "mode": "fixture"
}

POST/v1/seller/from-openapi

Write seller/from-openapi.

Key
Bearer
Scope
see the route
Body fieldType
openapistring
The OpenAPI file, as JSON or YAML text
price_usd optionalstring
One price for every endpoint. Without it every price says TODO
base_url optionalstring
id optionalstring
category optionalstring
contact_email optionalstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
filestring
A first petrova.yaml. Read it, and set what it marks TODO
skippedlist of objects
warningslist of string
endpointsinteger
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/seller/from-openapi \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"openapi":"openapi","price_usd":"0.005","base_url":"https://example.invalid/","id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","category":"search","contact_email":"contact-email"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/from-openapi",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"openapi":"openapi","price_usd":"0.005","base_url":"https://example.invalid/","id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","category":"search","contact_email":"contact-email"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/from-openapi", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"openapi":"openapi","price_usd":"0.005","base_url":"https://example.invalid/","id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","category":"search","contact_email":"contact-email"})
});
console.log(await r.json());
{
  "file": "file",
  "skipped": [
    {
      "operation": "operation",
      "reason": "reason"
    }
  ],
  "warnings": [
    "warnings"
  ],
  "endpoints": 1,
  "mode": "fixture"
}

POST/v1/seller/listings

Write seller/listings.

Key
Bearer
Scope
see the route
Body fieldType
filestring
The text of petrova.yaml. JSON is YAML, so JSON works too
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
listingstring
versioninteger
statestring
replayedboolean
The same file again: nothing new was saved
warningslist of objects
previewobject
changeslist of objects
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"file":"file"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"file":"file"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"file":"file"})
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "listing": "listing",
  "version": 1,
  "state": "state",
  "replayed": false,
  "warnings": [
    {
      "path": "path",
      "code": "PTRV-7K2Q",
      "message": "message",
      "fix": "fix"
    }
  ],
  "preview": {
    "listing_id": "listing-id",
    "name": "Chain Scout",
    "category": "search",
    "host": "host",
    "auth": "none",
    "auth_header": "auth-header",
    "fee_bps": 750,
    "endpoints": [
      {
        "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
        "name": "Chain Scout",
        "method": "GET",
        "url": "https://chain-scout.example/v1/ask",
        "inputs": [
          null
        ],
        "required": [
          null
        ],
        "success": "success",
        "checks_output": false,
        "buyer_pays_nusd": "18990000",
        "buyer_pays_usd": "buyer-pays-usd",
        "fee_nusd": "990000",
        "you_keep_nusd": "18990000"
      }
    ],
    "confirm_hash": "confirm-hash"
  },
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "mode": "fixture"
}

GET/v1/seller/listings

Read seller/listings.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
datalist of objects
mode"fixture"
curl -s http://127.0.0.1:4100/v1/seller/listings \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/seller/listings",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "data": [
    {
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "listing": "listing",
      "seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "status": "draft",
      "suspended_reason": "suspended-reason",
      "host": {
        "host": "host",
        "verified": false,
        "verified_by": "http_token"
      },
      "credential": {
        "stored": false,
        "hint": "hint",
        "updated_at": "2026-10-24T09:12:03.000Z"
      },
      "live_version": 1,
      "latest_version": 1,
      "tools": [
        {
          "tool_id": null,
          "endpoint": null,
          "hidden": null
        }
      ],
      "versions": [
        {
          "number": null,
          "id": null,
          "state": null,
          "content_hash": null,
          "fee_bps": null,
          "review_notes": null,
          "changes": null,
          "submitted_at": null,
          "reviewed_at": null,
          "created_at": null
        }
      ],
      "created_at": "2026-10-24T09:12:03.000Z",
      "mode": "fixture"
    }
  ],
  "mode": "fixture"
}

GET/v1/seller/listings/{id}

Read seller/listings/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
idstring (uuid)
listingstring
seller_agent_idstring (uuid)
status"draft" | "in_review" | "changes_requested" | "live" | "live_new_version_in_review" | "live_changes_requested" | "unlisted" | "suspended"
suspended_reasonstring or null
hostobject or null
credentialobject
live_versioninteger or null
latest_versioninteger or null
toolslist of objects
versionslist of objects
created_atstring (date-time)
mode"fixture"
curl -s http://127.0.0.1:4100/v1/seller/listings/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/seller/listings/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "listing": "listing",
  "seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "status": "draft",
  "suspended_reason": "suspended-reason",
  "host": {
    "host": "host",
    "verified": false,
    "verified_by": "http_token"
  },
  "credential": {
    "stored": false,
    "hint": "hint",
    "updated_at": "2026-10-24T09:12:03.000Z"
  },
  "live_version": 1,
  "latest_version": 1,
  "tools": [
    {
      "tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "endpoint": "endpoint",
      "hidden": false
    }
  ],
  "versions": [
    {
      "number": 1,
      "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
      "state": "draft",
      "content_hash": "content-hash",
      "fee_bps": 750,
      "review_notes": "review-notes",
      "changes": [
        {
          "endpoint": null,
          "field": null,
          "from": null,
          "to": null,
          "material": null
        }
      ],
      "submitted_at": "2026-10-24T09:12:03.000Z",
      "reviewed_at": "2026-10-24T09:12:03.000Z",
      "created_at": "2026-10-24T09:12:03.000Z"
    }
  ],
  "created_at": "2026-10-24T09:12:03.000Z",
  "mode": "fixture"
}

GET/v1/seller/listings/{id}/file

Read seller/listings/:id/file.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
version optionalquery · integer
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
versioninteger
statestring
filestring
previewobject
mode"fixture"
curl -s http://127.0.0.1:4100/v1/seller/listings/<id>/file \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/seller/listings/<id>/file",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/file", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "version": 1,
  "state": "state",
  "file": "file",
  "preview": {
    "listing_id": "listing-id",
    "name": "Chain Scout",
    "category": "search",
    "host": "host",
    "auth": "none",
    "auth_header": "auth-header",
    "fee_bps": 750,
    "endpoints": [
      {
        "id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
        "name": "Chain Scout",
        "method": "GET",
        "url": "https://chain-scout.example/v1/ask",
        "inputs": [
          null
        ],
        "required": [
          null
        ],
        "success": "success",
        "checks_output": false,
        "buyer_pays_nusd": "18990000",
        "buyer_pays_usd": "buyer-pays-usd",
        "fee_nusd": "990000",
        "you_keep_nusd": "18990000"
      }
    ],
    "confirm_hash": "confirm-hash"
  },
  "mode": "fixture"
}

GET/v1/seller/listings/{id}/host

Read seller/listings/:id/host.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
hoststring
verifiedboolean
verified_by"http_token" | "operator_attest" or null
verified_atstring (date-time) or null
provider_keystring
Your identity in the catalog, from the host. Cards allow services by this
proofobject
checked optional"found" | "already_verified" | "blocked_by_fixture_boundary"
blocked_by_fixture_boundary: this build cannot contact a real host. A reviewer can check it and attest
mode"fixture"
curl -s http://127.0.0.1:4100/v1/seller/listings/<id>/host \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/seller/listings/<id>/host",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/host", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "host": "host",
  "verified": false,
  "verified_by": "http_token",
  "verified_at": "2026-10-24T09:12:03.000Z",
  "provider_key": "provider-key",
  "proof": {
    "put_this_text": "put-this-text",
    "at_this_url": "https://example.invalid/"
  },
  "checked": "found",
  "mode": "fixture"
}

POST/v1/seller/listings/{id}/host/verify

Write seller/listings/:id/host/verify.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
hoststring
verifiedboolean
verified_by"http_token" | "operator_attest" or null
verified_atstring (date-time) or null
provider_keystring
Your identity in the catalog, from the host. Cards allow services by this
proofobject
checked optional"found" | "already_verified" | "blocked_by_fixture_boundary"
blocked_by_fixture_boundary: this build cannot contact a real host. A reviewer can check it and attest
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/host/verify \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/host/verify",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/host/verify", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "host": "host",
  "verified": false,
  "verified_by": "http_token",
  "verified_at": "2026-10-24T09:12:03.000Z",
  "provider_key": "provider-key",
  "proof": {
    "put_this_text": "put-this-text",
    "at_this_url": "https://example.invalid/"
  },
  "checked": "found",
  "mode": "fixture"
}

PUT/v1/seller/listings/{id}/credential

Write seller/listings/:id/credential.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
Body fieldType
api_keystring
Your API key for your own API. Stored encrypted. Never returned, and never in petrova.yaml
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
storedboolean
hintstring or null
mode"fixture"
curl -s -X PUT http://127.0.0.1:4100/v1/seller/listings/<id>/credential \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"api_key":"api-key"}'
import os, requests
r = requests.put("http://127.0.0.1:4100/v1/seller/listings/<id>/credential",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"api_key":"api-key"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/credential", {
  method: "PUT",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"api_key":"api-key"})
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "stored": false,
  "hint": "hint",
  "mode": "fixture"
}

DELETE/v1/seller/listings/{id}/credential

Delete seller/listings/:id/credential.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
storedboolean
hintstring or null
mode"fixture"
curl -s -X DELETE http://127.0.0.1:4100/v1/seller/listings/<id>/credential \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/seller/listings/<id>/credential",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/credential", {
  method: "DELETE",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "stored": false,
  "hint": "hint",
  "mode": "fixture"
}

POST/v1/seller/listings/{id}/submit

Write seller/listings/:id/submit.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
Body fieldType
confirm_hashstring
version optionalinteger
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
version optionalinteger
statestring
replayed optionalboolean
warning optionalstring or null
changes optionallist of objects or null
reason optionalstring or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/submit \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"confirm_hash":"confirm-hash","version":1}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/submit",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"confirm_hash":"confirm-hash","version":1})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/submit", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"confirm_hash":"confirm-hash","version":1})
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "version": 1,
  "state": "state",
  "replayed": false,
  "warning": "warning",
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "reason": "reason",
  "mode": "fixture"
}

POST/v1/seller/listings/{id}/withdraw

Write seller/listings/:id/withdraw.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
version optionalinteger
statestring
replayed optionalboolean
warning optionalstring or null
changes optionallist of objects or null
reason optionalstring or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/withdraw \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/withdraw",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/withdraw", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "version": 1,
  "state": "state",
  "replayed": false,
  "warning": "warning",
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "reason": "reason",
  "mode": "fixture"
}

POST/v1/seller/listings/{id}/unlist

Write seller/listings/:id/unlist.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
version optionalinteger
statestring
replayed optionalboolean
warning optionalstring or null
changes optionallist of objects or null
reason optionalstring or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/unlist \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/unlist",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/unlist", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "version": 1,
  "state": "state",
  "replayed": false,
  "warning": "warning",
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "reason": "reason",
  "mode": "fixture"
}

POST/v1/seller/listings/{id}/relist

Write seller/listings/:id/relist.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
internal_error500YesRetry with the same idempotency key.
Response fields
listing_idstring (uuid)
version optionalinteger
statestring
replayed optionalboolean
warning optionalstring or null
changes optionallist of objects or null
reason optionalstring or null
mode"fixture"
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/relist \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/relist",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/relist", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{
  "listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
  "version": 1,
  "state": "state",
  "replayed": false,
  "warning": "warning",
  "changes": [
    {
      "endpoint": "endpoint",
      "field": "field",
      "from": null,
      "to": null,
      "material": false
    }
  ],
  "reason": "reason",
  "mode": "fixture"
}

POST/v1/links/view

Write links/view.

Key
Bearer
Scope
see the route
Body fieldType
tokenstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/links/view \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"token":"token"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/view",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"token":"token"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/links/view", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"token":"token"})
});
console.log(await r.json());
{}

POST/v1/links/pay

Write links/pay.

Key
Bearer
Scope
see the route
Body fieldType
tokenstring
csrfstring
agent_idstring
amount_nusdstring
code optionalstring
The 6-digit code the agent gave its person with the link. Needed for a fund link and for an approval; a top-up link needs none
monthly_limit_nusd optionalstring
approval_over_nusd optionalstring
provider"fixture" | "card" | "usdc_topup"
confirm optionalstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/links/pay \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd","provider":"fixture","confirm":"confirm"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/pay",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd","provider":"fixture","confirm":"confirm"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/links/pay", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd","provider":"fixture","confirm":"confirm"})
});
console.log(await r.json());
{}

POST/v1/links/decide

Write links/decide.

Key
Bearer
Scope
see the route
Body fieldType
tokenstring
csrfstring
agent_idstring
amount_nusdstring
code optionalstring
The 6-digit code the agent gave its person with the link. Needed for a fund link and for an approval; a top-up link needs none
decision"approve" | "reject"
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/links/decide \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","decision":"approve"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/decide",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","decision":"approve"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/links/decide", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","decision":"approve"})
});
console.log(await r.json());
{}

POST/v1/links/deposit

Write links/deposit.

Key
Bearer
Scope
see the route
Body fieldType
tokenstring
csrfstring
agent_idstring
amount_nusdstring
code optionalstring
The 6-digit code the agent gave its person with the link. Needed for a fund link before the address is shown
monthly_limit_nusd optionalstring
approval_over_nusd optionalstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/links/deposit \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/deposit",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/links/deposit", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd"})
});
console.log(await r.json());
{}

POST/v1/links/deposit/status

Write links/deposit/status.

Key
Bearer
Scope
see the route
Body fieldType
tokenstring
csrfstring
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/links/deposit/status \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"token":"token","csrf":"csrf"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/deposit/status",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"token":"token","csrf":"csrf"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/links/deposit/status", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"token":"token","csrf":"csrf"})
});
console.log(await r.json());
{}

Owner

GET/v1/owner/me

Read owner/me.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s http://127.0.0.1:4100/v1/owner/me \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/owner/me",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/me", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{}

GET/v1/owner/feed

Read owner/feed.

Key
Bearer
Scope
see the route
ParameterIn · type
limit optionalquery · integer
cursor optionalquery · string
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s http://127.0.0.1:4100/v1/owner/feed \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/owner/feed",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/feed", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{}

GET/v1/owner/agents

Read owner/agents.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s http://127.0.0.1:4100/v1/owner/agents \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/owner/agents",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/agents", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{}

PATCH/v1/owner/agents/{id}

Write owner/agents/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
monthly_limit_nusd optionalnano-USD string
Integer nano-USD, 1 USD = 1000000000
approval_over_nusd optionalnano-USD string or null
state optional"active" | "paused"
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X PATCH http://127.0.0.1:4100/v1/owner/agents/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"monthly_limit_nusd":"5000000000","approval_over_nusd":"18990000","state":"active"}'
import os, requests
r = requests.patch("http://127.0.0.1:4100/v1/owner/agents/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"monthly_limit_nusd":"5000000000","approval_over_nusd":"18990000","state":"active"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/agents/<id>", {
  method: "PATCH",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"monthly_limit_nusd":"5000000000","approval_over_nusd":"18990000","state":"active"})
});
console.log(await r.json());
{}

POST/v1/owner/calls/{id}/decide

Write owner/calls/:id/decide.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
decision"approve" | "reject"
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/owner/calls/<id>/decide \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"decision":"approve"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/calls/<id>/decide",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"decision":"approve"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/calls/<id>/decide", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"decision":"approve"})
});
console.log(await r.json());
{}

POST/v1/owner/agents/{id}/remove

Write owner/agents/:id/remove.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/owner/agents/<id>/remove \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/agents/<id>/remove",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/agents/<id>/remove", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{}

POST/v1/owner/signin

Write owner/signin.

Key
Bearer
Scope
see the route
Body fieldType
recovery_codestring
The recovery code the person was shown when they first paid. Never given to an agent
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/owner/signin \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"recovery_code":"recovery-code"}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/signin",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"recovery_code":"recovery-code"})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/signin", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"recovery_code":"recovery-code"})
});
console.log(await r.json());
{}

POST/v1/owner/recovery

Write owner/recovery.

Key
Bearer
Scope
see the route
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/owner/recovery \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/recovery",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/recovery", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{}

POST/v1/owner/pause-all

Write owner/pause-all.

Key
Bearer
Scope
see the route
Body fieldType
pausedboolean
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/owner/pause-all \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"paused":false}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/pause-all",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"paused":false})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/owner/pause-all", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"paused":false})
});
console.log(await r.json());
{}

X402

POST/v1/x402/tools/{id}/call

Write x402/tools/:id/call.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
Body fieldType
inputsobject
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
upstream failed502YesA supplier or tool failed; you paid nothing. Retry.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/x402/tools/<id>/call \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"inputs":{}}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/x402/tools/<id>/call",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"inputs":{}})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/x402/tools/<id>/call", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"inputs":{}})
});
console.log(await r.json());
{}

POST/v1/x402/call

Write x402/call.

Key
Bearer
Scope
see the route
Body fieldType
providerstring
Provider slug from search, e.g. exa
pathstring
Path from search, e.g. /search
method optional"GET" | "POST" | "PUT" | "PATCH" | "DELETE"
inputs optionalobject
path_params optionalobject
query optionalobject
headers optionalobject
body optionalany
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
upstream failed502YesA supplier or tool failed; you paid nothing. Retry.
unavailable503YesTry again shortly.
curl -s -X POST http://127.0.0.1:4100/v1/x402/call \
  -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null}'
import os, requests
r = requests.post("http://127.0.0.1:4100/v1/x402/call",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
    json={"provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/x402/call", {
  method: "POST",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({"provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null})
});
console.log(await r.json());
{}

GET/v1/x402/payments/{id}

Read x402/payments/:id.

Key
Bearer
Scope
see the route
ParameterIn · type
idpath · string (uuid)
CodeHTTPRetry?What to do
invalid_request400NoFix the field named in the message.
unauthorized401NoSend a valid key: Authorization: Bearer ptrv_test_…
insufficient_balance402NoAdd funds, or lower the amount.
scope_denied403NoUse a key that has the scope shown above.
not_found404NoCheck the id; it must belong to this account.
conflict409NoThe state changed (used, expired or already decided). Read it again.
error410NoSee the message.
rate_limit / spend limit429NoA cap or loop pause stopped it. Raise the cap or fix the loop.
internal_error500YesRetry with the same idempotency key.
unavailable503YesTry again shortly.
curl -s http://127.0.0.1:4100/v1/x402/payments/<id> \
  -H "authorization: Bearer $PETROVA_API_KEY"
import os, requests
r = requests.get("http://127.0.0.1:4100/v1/x402/payments/<id>",
    headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())
const r = await fetch("http://127.0.0.1:4100/v1/x402/payments/<id>", {
  method: "GET",
  headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());
{}