Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Nohumans Directory Listings API
version: 1.0.0
contact:
email: hello@nohumans.directory
license:
name: CC-BY-4.0 (directory data)
identifier: CC-BY-4.0
x-guidance: 'Free discovery: GET /v1/discover?q= to find paid x402 services by need, GET /v1/listings/{id} for the full record, GET /v1/resolve?url= when you already hold an endpoint URL. Paid routes (x402 v2, USDC on Base): GET /v1/listings/{id}/verdict $0.005; GET /v1/listings/{id}/purchases $0.01; POST /v1/listings/{id}/verify-now from $0.25 (listing owners only); GET /v1/demand/clusters $5; GET /v1/verdicts $0.10; GET /v1/listings/{id}/owner-report $1 (listing owners only); GET /v1/demand/report $5. Every fact the verdict folds in is free on the listing record. Prefer the MCP server at /mcp if your framework speaks it.'
description: 'Operations tagged Listings across 2 of this provider''s published API definitions: nohumans-directory-openapi.json, openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
tags:
- name: Listings
paths:
/v1/listings/{id}:
get:
summary: Full listing record (schemas, reputation, observed 402 terms, paid verification)
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Listing detail
content:
application/json:
schema:
$ref: '#/components/schemas/ListingDetail'
'404':
description: Not found or delisted
security: []
tags:
- Listings
operationId: getV1ListingsById
x-operation-id-source: derived
patch:
summary: Edit listing metadata (never resets verification)
security:
- claimToken: []
- bearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Updated
'401':
description: 'Teaching 401: names the claim flow'
tags:
- Listings
operationId: patchV1ListingsById
x-operation-id-source: derived
delete:
summary: Self-serve delist (same auth as PATCH)
security:
- claimToken: []
- bearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Delisted
'401':
description: Unauthorized
tags:
- Listings
operationId: deleteV1ListingsById
x-operation-id-source: derived
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings/{id}/history:
get:
summary: Every real status change for one listing, with reasons
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Transition log
security: []
tags:
- Listings
operationId: getV1ListingsByIdHistory
x-operation-id-source: derived
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings:
get:
summary: Enumerate listings (stable order, paginated) — not ranked search
parameters:
- name: limit
in: query
schema:
type: integer
maximum: 200
default: 50
- name: offset
in: query
schema:
type: integer
default: 0
- name: status
in: query
schema:
type: string
enum:
- verified
- unverified
- failing
- delisted
- all
description: Defaults to active (verified, unverified, failing)
responses:
'200':
description: total, count, limit, offset, next_offset, results
security: []
tags:
- Listings
operationId: getV1Listings
x-operation-id-source: derived
post:
summary: Submit a listing (lands unverified; first probe within about two minutes).
description: 'From 2026-10-26 every new listing costs $0.25 USDC on Base, paid over x402 on the same POST: the unpaid POST answers 402 with the terms, and the paid retry returns 201. Check free first: POST /v1/check with the same body; nothing is created or charged. Included: one real purchase of the endpoint by our buyer, with real USDC, within 48 hours of the listing first verifying, if it verifies within 7 days and quotes $0.05 or less per call over HTTP 402. That purchase is graded and published like every other, whatever it finds: the fee buys the purchase, never its outcome, a status, a score or a place in the order. A failure caused by our own client is re-run. An endpoint priced above $0.05 lists the same way for the same fee, with no purchase included; paid verification ($0.25 plus the endpoint''s own price for one purchase, $1 plus four times it for one a week for four weeks, for quotes up to $0.50) buys one, and above $0.50 write to hello@nohumans.directory for a custom plan. Endpoints whose URL path is /mcp or under /mcp/ list free, with no purchase included, because our buyer cannot pay over the MCP transport yet; one that also answers a plain HTTP 402 can be paid over HTTP, so the fee and its purchase apply (from 2026-11-02). Request-capture and mock hosts (webhook.site and the like) are refused: a canned 402 has no service behind it. The submission is validated before any charge, so a rejected submission is never charged. Edits, claims, an endpoint that is already listed, and re-listing an endpoint that was listed before are free; listings already in the directory and listings we index ourselves are unaffected. Before 2026-10-26 the first 5 listings per registered domain were free and each further one cost $0.25 (since 2026-09-28; $0.50 from 2026-09-25).'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- description
- endpoint_url
- category
- price_amount
properties:
name:
type: string
description:
type: string
endpoint_url:
type: string
format: uri
description: https only; private IPs rejected
category:
type: string
price_amount:
type: number
minimum: 0
price_currency:
type: string
default: USDC
chains:
type: array
items:
type: string
default:
- base
request_schema:
type: object
response_schema:
type: object
sample_query:
type: string
description: Free/cheap probe URL; must not equal endpoint_url
submitter_email:
type: string
responses:
'201':
description: 'Created. SAVE claim_token — shown once; it is the edit credential (x-claim-token, x-edit-token, or Authorization: Bearer).'
'400':
description: Validation failure, reason stated
'402':
description: 'Listing fee due: every new listing from 2026-10-26 (before that, beyond the first 5 per registered domain). PaymentRequired (x402 v2, $0.25 USDC on Base) in the PAYMENT-REQUIRED header and the body; retry the same POST with payment and receive the 201. Also returned, uncharged and with an error field, if a paid submission cannot be created.'
'409':
description: endpoint_already_listed
security: []
tags:
- Listings
operationId: postV1Listings
x-operation-id-source: derived
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings/{id}/claim:
get:
summary: Claim flow explained (read-only; issues nothing — since 2026-08-30)
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: origin_status, challenge_active, next, instructions
'404':
description: Not found or delisted
security: []
tags:
- Listings
operationId: getV1ListingsByIdClaim
x-operation-id-source: derived
post:
summary: Verify proof-of-control against the active challenge; on success returns the…
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
responses:
'200':
description: 'ok, origin: claimed, edit_token (send as x-claim-token)'
'403':
description: proof_not_found
'409':
description: no_challenge — request one first
'429':
description: Rate limited
security: []
tags:
- Listings
operationId: postV1ListingsByIdClaim
x-operation-id-source: derived
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings/{id}/claim/challenge:
post:
summary: Mint a proof-of-control challenge token (valid 24h; never a credential…
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: token, valid_for_seconds, instructions
'429':
description: 50 per hour per IP
security: []
tags:
- Listings
operationId: postV1ListingsByIdClaimChallenge
x-operation-id-source: derived
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings/{id}/verdict:
get:
operationId: getVerdict
summary: Pre-spend verdict for one listing (paid, x402, $0.005 USDC on Base)
description: 'Returns pay / caution / avoid with printed reasons and, on caution or avoid, up to three verified alternatives (rule: /methodology#verdict-alternatives), built from probe history, payTo age and stability, our own paid-delivery outcome, and the verb that produced the 402. Unpaid requests receive 402 with PaymentRequired in the PAYMENT-REQUIRED header and the body. Rule: https://nohumans.directory/methodology#verdict'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Listing id as returned by /v1/discover or /v1/listings.
example: 9a8bf56d-2fc
responses:
'200':
description: Verdict (after settlement; PAYMENT-RESPONSE header carries the receipt).
content:
application/json:
schema:
type: object
properties:
listing_id:
type: string
endpoint_url:
type: string
verdict:
type: string
enum:
- pay
- caution
- avoid
reasons:
type: array
items:
type: string
self_referential:
type: boolean
description: nohumans.directory operates this endpoint; the verdict is not independent and never better than caution
as_of:
type: integer
status:
type: string
verified_via:
type:
- string
- 'null'
probe:
type: object
payto:
type: object
onchain_30d:
type: object
paid_verification:
type: object
price:
type: object
rule:
type: string
verification:
type:
- object
- 'null'
description: 'x402 WG draft verifier object (PR #6); our verdict is the recommendation citing it'
verification_schema:
type: object
verification_note:
type: string
required:
- listing_id
- verdict
- reasons
- as_of
- rule
'402':
description: Payment required. PaymentRequired object in the PAYMENT-REQUIRED header and the body, identical. Also returned, with an `error` field and without settlement, when a payment header is present but the listing id is unknown — an unknown id is never charged.
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.005000'
protocols:
- x402: {}
- mpp:
method: evm
intent: charge
offers:
- scheme: exact
network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
amount: '5000'
payTo: '0xA733875f2F7E8A2817040B5c60B63Ae07D58a1d6'
maxTimeoutSeconds: 60
tags:
- Listings
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings/{id}/purchases:
get:
operationId: getPurchaseHistory
summary: Purchase history for one listing (paid, x402, $0.01 USDC on Base)
description: 'Every real USDC purchase the directory has made of this listing, oldest first — outcome, live quote vs listed price, settlement tx on Base, JSON/schema validity, freshness, normalised body hash — plus the consecutive-pair deltas (delivery held/regressed/recovered, price held/moved with quote_delta_usdc, body same/changed/no_hash). The verdict is a rule applied to this series; this is the series. Unpaid call answers 402 with terms in the PAYMENT-REQUIRED header and the body. Rule: https://nohumans.directory/methodology#purchases'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Listing id as returned by /v1/discover or /v1/listings.
example: 0b1cb988-58c
responses:
'200':
description: Paid. { listing_id, endpoint_url, status, as_of, summary, purchases[], pairs[], basis, rule }
'402':
description: Payment required. PaymentRequired object in the PAYMENT-REQUIRED header and the body, identical. Amount 10000 atomic USDC. A paid request for an unknown id answers 402 with error listing_not_found, never charged.
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.010000'
protocols:
- x402: {}
- mpp:
method: evm
intent: charge
offers:
- scheme: exact
network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
amount: '10000'
payTo: '0xA733875f2F7E8A2817040B5c60B63Ae07D58a1d6'
maxTimeoutSeconds: 60
tags:
- Listings
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings/{id}/verify-now:
get:
operationId: verifyNowQuote
summary: Read the paid-verification price for one listing (402 with x402 terms…
description: 'Two plans, both only for listings quoting up to $0.50 per call, each priced as a fee plus the listing''s own price for every purchase (USDC on Base): recheck — one real purchase within 24 hours, $0.25 plus the listing''s price; monthly — four real purchases inside 30 days, the first within 24 hours and then about one a week at times the directory chooses, $1 plus four times the listing''s price. The 402 for a listing carries the exact amount. The plan covers the price the listing quotes when the plan is bought: if the endpoint asks more when a purchase is due, that purchase waits until the price is back at or under it. Choose with ?plan=; omitted means recheck (the old name single is read as recheck; pack ended on 2026-11-14). Sold only to the listing''s owner: the PAID request must carry the seller''s claim token in x-claim-token (401 otherwise); the unpaid request answers an ordinary 402 and anyone may read the price. Every purchase is graded exactly as a wave and published on the record whatever it finds — settlement tx, delivery outcome, failure reason, and the paid-depth rung (paid_verified → 2x → held → Nwk, or failed_rebuy if the endpoint stops delivering). What money buys: WHEN the purchases happen, and how many. What it never buys: the outcome, the rung, status, score, verdict, or rank. The directory''s own waves keep buying from the catalogue whether or not a listing has a plan. A failure caused by the directory''s own client does not count against the plan and is re-run. One open plan per listing at a time. Rule: https://nohumans.directory/methodology#verify-now'
parameters:
- name: id
in: path
required: true
schema:
type: string
example: 9a8bf56d-2fc
- name: plan
in: query
required: false
schema:
type: string
enum:
- recheck
- monthly
default: recheck
description: 'recheck: one purchase, $0.25 + your price per call. monthly: four purchases in 30 days, $1 + 4 x your price per call.'
responses:
'200':
description: 'Queued. { listing_id, plan, purchases, purchases_done, status: ''queued'', request_id, promise: ''first purchase within 24 hours'', fee_usdc, record, rule }. The settlement tx is in the PAYMENT-RESPONSE header. Progress: GET this URL with ?view=status and your x-claim-token header (owner only).'
'400':
description: unknown_plan — ?plan must be recheck or monthly (the body lists both with prices); or no_price_observed — no price has been read from the listing's 402 yet; or scheme_not_buyable — the listing uses the upto scheme; or listing_not_buyable — the listing is failing its probes; or quote_above_plan_cap — the listing quotes above $0.50/call; write to hello@nohumans.directory; or transport_not_buyable — the listing asks for payment over the MCP transport, which our buyer cannot pay yet.
'401':
description: claim_token_required or claim_token_invalid — the paid request must carry the listing owner's claim token in x-claim-token. The body links the claim flow.
'402':
description: 'Payment required. PaymentRequired object in the PAYMENT-REQUIRED header and the body, identical. Amount is the plan price for this listing in atomic USDC: 250000 (recheck) or 1000000 (monthly), plus the listing''s own price once per purchase.'
'409':
description: plan_in_progress — this listing already has purchases pending; the body shows purchases_done of purchases_total.
x-payment-info:
price:
mode: dynamic
currency: USD
min: '0.250000'
max: '3.000000'
note: recheck ($0.25 + your price, one purchase) or monthly ($1 + 4 x your price, four purchases in 30 days); "your price" is the listing's own price per call, up to $0.50
protocols:
- x402: {}
offers:
- scheme: exact
network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
amount: '250000'
payTo: '0xA733875f2F7E8A2817040B5c60B63Ae07D58a1d6'
maxTimeoutSeconds: 60
- scheme: exact
network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
amount: '1000000'
payTo: '0xA733875f2F7E8A2817040B5c60B63Ae07D58a1d6'
maxTimeoutSeconds: 60
tags:
- Listings
post:
operationId: verifyNow
summary: 'Buy paid verification for a listing you own: recheck ($0.25 + your price, one…'
description: 'Two plans, both only for listings quoting up to $0.50 per call, each priced as a fee plus the listing''s own price for every purchase (USDC on Base): recheck — one real purchase within 24 hours, $0.25 plus the listing''s price; monthly — four real purchases inside 30 days, the first within 24 hours and then about one a week at times the directory chooses, $1 plus four times the listing''s price. The 402 for a listing carries the exact amount. The plan covers the price the listing quotes when the plan is bought: if the endpoint asks more when a purchase is due, that purchase waits until the price is back at or under it. Choose with ?plan=; omitted means recheck (the old name single is read as recheck; pack ended on 2026-11-14). Sold only to the listing''s owner: the PAID request must carry the seller''s claim token in x-claim-token (401 otherwise); the unpaid request answers an ordinary 402 and anyone may read the price. Every purchase is graded exactly as a wave and published on the record whatever it finds — settlement tx, delivery outcome, failure reason, and the paid-depth rung (paid_verified → 2x → held → Nwk, or failed_rebuy if the endpoint stops delivering). What money buys: WHEN the purchases happen, and how many. What it never buys: the outcome, the rung, status, score, verdict, or rank. The directory''s own waves keep buying from the catalogue whether or not a listing has a plan. A failure caused by the directory''s own client does not count against the plan and is re-run. One open plan per listing at a time. Rule: https://nohumans.directory/methodology#verify-now'
parameters:
- name: id
in: path
required: true
schema:
type: string
example: 9a8bf56d-2fc
- name: plan
in: query
required: false
schema:
type: string
enum:
- recheck
- monthly
default: recheck
description: 'recheck: one purchase, $0.25 + your price per call. monthly: four purchases in 30 days, $1 + 4 x your price per call.'
responses:
'200':
description: 'Queued. { listing_id, plan, purchases, purchases_done, status: ''queued'', request_id, promise: ''first purchase within 24 hours'', fee_usdc, record, rule }. The settlement tx is in the PAYMENT-RESPONSE header. Progress: GET this URL with ?view=status and your x-claim-token header (owner only).'
'400':
description: unknown_plan — ?plan must be recheck or monthly (the body lists both with prices); or no_price_observed — no price has been read from the listing's 402 yet; or scheme_not_buyable — the listing uses the upto scheme; or listing_not_buyable — the listing is failing its probes; or quote_above_plan_cap — the listing quotes above $0.50/call; write to hello@nohumans.directory; or transport_not_buyable — the listing asks for payment over the MCP transport, which our buyer cannot pay yet.
'401':
description: claim_token_required or claim_token_invalid — the paid request must carry the listing owner's claim token in x-claim-token. The body links the claim flow.
'402':
description: 'Payment required. PaymentRequired object in the PAYMENT-REQUIRED header and the body, identical. Amount is the plan price for this listing in atomic USDC: 250000 (recheck) or 1000000 (monthly), plus the listing''s own price once per purchase.'
'409':
description: plan_in_progress — this listing already has purchases pending; the body shows purchases_done of purchases_total.
x-payment-info:
price:
mode: dynamic
currency: USD
min: '0.250000'
max: '3.000000'
note: recheck ($0.25 + your price, one purchase) or monthly ($1 + 4 x your price, four purchases in 30 days); "your price" is the listing's own price per call, up to $0.50
protocols:
- x402: {}
offers:
- scheme: exact
network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
amount: '250000'
payTo: '0xA733875f2F7E8A2817040B5c60B63Ae07D58a1d6'
maxTimeoutSeconds: 60
- scheme: exact
network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
amount: '1000000'
payTo: '0xA733875f2F7E8A2817040B5c60B63Ae07D58a1d6'
maxTimeoutSeconds: 60
tags:
- Listings
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings/{id}/owner-report:
get:
operationId: getOwnerReport
summary: Owner report for one listing (owner only; the first one per listing free, then…
description: 'Your listing as agents see it: the agent searches you show up for (rank in the first three our search returns), the needs in your kind you miss and who is shown instead, open needs near you, our real USDC purchases of you, your price against verified listings of your kind, and what to fix first. Sold only to the listing''s owner: the paid request must carry the claim token in x-claim-token (401 otherwise, nothing charged); the unpaid request answers an ordinary 402 so anyone can read the price. The owner''s first report per listing is free: the token without a payment returns it (200, with first_report_free); once given, the same request answers the 402. Never affects ranking, status or score. Rule: https://nohumans.directory/sellers#owner-report'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Your listing id.
example: 0b1cb988-58c
- name: x-claim-token
in: header
required: false
schema:
type: string
description: 'Required on the paid request: the listing''s claim token.'
responses:
'200':
description: Paid, or the owner's free first report (then with first_report_free). { listing, as_of, do_next[], demand { you_show_up_for[], not_shown_in_your_kind[], open_needs_in_your_kind[] }, purchases, market, basis, rule }
'401':
description: claim_token_required or claim_token_invalid — nothing charged.
'402':
description: Payment required. PaymentRequired object in the PAYMENT-REQUIRED header and the body, identical. Amount 1000000 atomic USDC.
x-payment-info:
price:
mode: fixed
currency: USD
amount: '1.000000'
protocols:
- x402: {}
offers:
- scheme: exact
network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
amount: '1000000'
payTo: '0xA733875f2F7E8A2817040B5c60B63Ae07D58a1d6'
maxTimeoutSeconds: 60
tags:
- Listings
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
/v1/listings/{id}/owner-report/preview:
get:
operationId: getOwnerReportPreview
summary: 'Free preview of the owner report: counts for anyone; with the listing''s claim…'
description: 'Free, read-only. Without a token: how many needs agents searched in the listing''s kind, how many it was in the first three for, how many went to others (and how many of those are close to what it describes), open needs, our purchases and price position. With the listing''s claim token in x-claim-token: also first_look (the first thing to fix, the closest need shown to others with how many listings were shown instead, the top search it shows up for). The names of other listings, every need and every fix are the owner report (owner only: the first one per listing free, then $1 USDC); with the token, full_report.your_first_report_free_available says whether the free one is still there. Never affects ranking, status or score.'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The listing id.
example: 0b1cb988-58c
- name: x-claim-token
in: header
required: false
schema:
type: string
description: 'Optional: the listing''s claim token, for first_look.'
responses:
'200':
description: '{ listing, as_of_iso, window_days, counts, first_look (owner) | owner_first_look (how to get it), full_report, note, rule }'
'401':
description: claim_token_invalid — a token was sent and it is not this listing's.
'404':
description: listing_not_found (unknown or delisted).
security: []
tags:
- Listings
servers:
- url: https://api.nohumans.directory
- url: https://nohumans.directory
components:
schemas:
ListingDetail:
type: object
additionalProperties: true
description: ListingSummary fields plus request_schema/response_schema, sample_query, origin, paid_verification with tx proof, observed 402 terms
securitySchemes:
claimToken:
type: apiKey
in: header
name: x-claim-token
description: Returned once at submission or via the claim flow; x-edit-token accepted as alias
bearer:
type: http
scheme: bearer
description: 'Same claim token as Authorization: Bearer'
x-refined-from:
- nohumans-directory-openapi.json
- openapi.json
x-mcp:
endpoint: https://api.nohumans.directory/mcp
transport: streamable-http
tools:
- find_paid_service
- get_service_details
- resolve_endpoint
- what_agents_are_asking_for
x-discovery:
version: '2026-09-03'