Mekler AIAPI reference.
Each operation has a specific input, output, price and scope. Choose an operation below to inspect its exact schema and response definitions. Schema references resolve against the shared definitions at the end of this page.
Download the complete OpenAPI contract (JSON)
Create a durable agent mailbox with optional incoming email
POST /v1/messaging/mailboxes/create-mailbox
2 USDC per 30-day receiving term; 1,000 messages and explicitly bounded recovery
Service scope, examples and recovery →
Give an agent a durable private mailbox for messages, HTTP callbacks and optional incoming email. A 2 USDC purchase opens 30 days of receiving with 1,000 messages; each accepted message is retained for 30 days. Recover unfinished work after disconnects using scoped access, processing claims and an outbound notification connector. No customer public server is required. No outbound email or hosted agent execution.
Input fields
request_idRequired · string- See the complete request schema for values and bounds.
owner_keyRequired · string- See the complete request schema for values and bounds.
email_enabledOptional · boolean- See the complete request schema for values and bounds.
webhook_urlOptional · string- See the complete request schema for values and bounds.
Response status
200- Finalized receiving term and original-proof recovery receipt. PAYMENT-RESPONSE confirms settlement.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- Input-bound x402 v2 quote for valid creation input. Empty unsigned JSON is nonpayable preflight; supply request_id and a private access_key before signing.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Decoded JSON request exceeds 8192 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"owner_key"
],
"properties": {
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"owner_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$"
},
"email_enabled": {
"type": "boolean",
"default": false
},
"webhook_url": {
"type": "string",
"format": "uri",
"maxLength": 2048
}
}
},
"example": {
"request_id": "mekler-mail-example-01",
"owner_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE",
"email_enabled": true
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Finalized receiving term and original-proof recovery receipt. PAYMENT-RESPONSE confirms settlement.",
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"mailbox_id",
"purchase_id",
"email_address",
"receiving_term_seconds",
"next_step",
"receiving_term"
],
"properties": {
"status": {
"const": "ok"
},
"mailbox_id": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"purchase_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"email_address": {
"type": "string",
"format": "email"
},
"receiving_term_seconds": {
"const": 2592000
},
"next_step": {
"type": "string"
},
"receiving_term": {
"type": "object",
"additionalProperties": false,
"required": [
"starts_at",
"ends_at"
],
"properties": {
"starts_at": {
"type": "integer"
},
"ends_at": {
"type": "integer"
}
}
}
}
},
"example": {
"status": "ok",
"mailbox_id": "1c2dee1d4ee689f629f57d2ba1ac2f40",
"purchase_id": "10f56926c6b832c25b1c9edc9e22c8481db8f1e761a1ff2b7f6b258ff9fa52df",
"email_address": "1c2dee1d4ee689f629f57d2ba1ac2f40@mail.mekler.ai",
"receiving_term_seconds": 2592000,
"next_step": "Retrieve mailbox status with your owner key after settlement.",
"receiving_term": {
"starts_at": 1792886400,
"ends_at": 1795478400
}
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "Input-bound x402 v2 quote for valid creation input. Empty unsigned JSON is nonpayable preflight; supply request_id and a private access_key before signing.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "2.000000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Decoded JSON request exceeds 8192 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Create a private temporary inbox and read incoming email
POST /v1/email/inboxes/create-private-inbox
0.05 USDC per private 24 hour inbox; capability reads and deletion are free
Service scope, examples and recovery →
Create a private receive-only email inbox for an agent. Read incoming confirmation mail and attachments for 24 hours, up to 25 messages of 128 KiB each, and optionally receive signed arrival webhooks. Creation costs 0.05 USDC; capability-authorized reads and deletion are free. No outbound email, permanent address or guarantee that websites accept the address.
Input fields
request_idRequired · string- Caller-selected idempotency identity; retain unchanged with the same access key.
access_keyRequired · string- Privately generated canonical base64url of 32 random bytes, without padding. The published example is synthetic; never use it as a real secret.
webhook_urlOptional · string- Optional public HTTPS metadata on port 443; callback, no credentials/fragment. Private DNS/IP destinations and redirects are never called; delivery is best effort.
Response status
200- Finalized private inbox creation; original expires_at never changes during recovery. PAYMENT-RESPONSE confirms settlement.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- Input-bound x402 v2 quote for valid creation input. Empty unsigned JSON is nonpayable preflight; supply request_id and a private access_key before signing.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Decoded JSON request exceeds 8192 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"access_key"
],
"properties": {
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Caller-selected idempotency identity; retain unchanged with the same access key."
},
"access_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$",
"description": "Privately generated canonical base64url of 32 random bytes, without padding. The published example is synthetic; never use it as a real secret."
},
"webhook_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Optional public HTTPS metadata on port 443; callback, no credentials/fragment. Private DNS/IP destinations and redirects are never called; delivery is best effort."
}
}
},
"example": {
"request_id": "mekler-synthetic-request-01",
"access_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Finalized private inbox creation; original expires_at never changes during recovery. PAYMENT-RESPONSE confirms settlement.",
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"inbox_id",
"address",
"created_at",
"expires_at",
"limits"
],
"properties": {
"status": {
"const": "ok"
},
"inbox_id": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"address": {
"type": "string",
"format": "email"
},
"created_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"limits": {
"type": "object",
"additionalProperties": false,
"required": [
"messages",
"raw_message_bytes"
],
"properties": {
"messages": {
"const": 25
},
"raw_message_bytes": {
"const": 131072
}
}
},
"webhook_secret": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
}
}
},
"example": {
"status": "ok",
"inbox_id": "ed157de6233b2dbbb69d46c26189a7c5",
"address": "ed157de6233b2dbbb69d46c26189a7c5@inbox.mekler.ai",
"created_at": 1792252800,
"expires_at": 1792339200,
"limits": {
"messages": 25,
"raw_message_bytes": 131072
}
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "Input-bound x402 v2 quote for valid creation input. Empty unsigned JSON is nonpayable preflight; supply request_id and a private access_key before signing.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.050000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Decoded JSON request exceeds 8192 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Generate task-routed model completions
POST /v1/compute/inference/generate-completions
Example: 0.002796 USDC per completed purchase; example shown, exact quote required
Service scope, examples and recovery →
Compare exact prices across eight models: GPT-6 Luna, GPT-6.1 Sol, Ministral 3B/8B/14B, Nemotron 3 Nano and Qwen3 Next/Coder Next. Review a recommendation and supported model/effort alternatives, then accept one quote or use automatic selection. Generate text or JSON with one USDC payment and no supplier account. Recover private results after completion. Recommendations use task rules, not a quality guarantee. No tools, browsing or streaming.
Input fields
tasksRequired · array- See the complete request schema for values and bounds.
max_price_usdcRequired · string- See the complete request schema for values and bounds.
idempotency_keyOptional · string- See the complete request schema for values and bounds.
Response status
200- All completions stored and delivered; receipt reports payment finality separately.
202- Work or payment is pending. Retain original proof.
400- Invalid request or proof.
402- Input-bound fixed quote; no supplier work performed.
409- Payment or idempotency conflict.
410- Uncharged failed work or expired private recovery; inspect response.
413- Input too large.
415- Expected application/json.
422- Selected work exceeds spending limit; no silent model downgrade.
429- Admission capacity unavailable; no payment started.
503- Unavailable; retain original proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"minItems": 1,
"maxItems": 16,
"items": {
"type": "object",
"properties": {
"role": {
"enum": [
"system",
"user",
"assistant"
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 16000
}
},
"required": [
"role",
"content"
],
"additionalProperties": false
}
},
"model": {
"enum": [
"auto",
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
],
"default": "auto",
"description": "Gemma is only eligible for a checked contract with current qualification and supplier authorization."
},
"task": {
"enum": [
"auto",
"extract",
"classify",
"summarize",
"translate",
"write",
"code",
"analyze",
"plan"
],
"default": "auto"
},
"priority": {
"enum": [
"balanced",
"economy",
"quality",
"speed"
],
"default": "balanced"
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096,
"default": 1000,
"description": "Total billed output ceiling, including reasoning and non-visible tokens. Small ceilings can truncate a response; truncated work is uncharged."
},
"response_format": {
"enum": [
"text",
"json_object"
],
"default": "text"
},
"contract": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "extract_fields"
},
"fields": {
"type": "object",
"minProperties": 1,
"maxProperties": 3,
"propertyNames": {
"pattern": "^[a-z][a-z0-9_]{0,31}$",
"not": {
"const": "abstain"
}
},
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
}
},
"required": [
"kind",
"fields"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "classify"
},
"labels": {
"type": "object",
"minProperties": 2,
"maxProperties": 3,
"propertyNames": {
"pattern": "^[a-z][a-z0-9_]{0,31}$",
"not": {
"const": "abstain"
}
},
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
}
},
"required": [
"kind",
"labels"
],
"additionalProperties": false
}
],
"description": "Optional checked workflow for one English user-message source, at most 8000 UTF-8 bytes. Requires json_object and at least the qualified model output allowance (currently 2048). Returns 422 when no current qualified candidate fits. Field values and evidence are verbatim source spans; missing/ambiguous fields are null. Classification can abstain. Validation does not prove semantic correctness."
}
},
"required": [
"messages"
],
"additionalProperties": false
}
},
"max_price_usdc": {
"type": "string",
"minLength": 1,
"maxLength": 8,
"pattern": "^(?:0(?:\\.[0-9]{1,6})?|1(?:\\.0{1,6})?)$"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9_-]{22,128}$"
}
},
"required": [
"tasks",
"max_price_usdc"
],
"additionalProperties": false
},
"example": {
"tasks": [
{
"messages": [
{
"role": "user",
"content": "Summarize: the meeting starts at noon."
}
],
"task": "summarize",
"max_output_tokens": 64
}
],
"max_price_usdc": "0.003"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "All completions stored and delivered; receipt reports payment finality separately.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"state": {
"enum": [
"complete",
"delivered",
"delivered-payment-failed"
]
},
"plan": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"models": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"model": {
"enum": [
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
]
},
"provider_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"reasoning_effort": {
"enum": [
"none",
"low",
"high",
null
]
},
"input_token_allowance": {
"type": "integer",
"minimum": 1
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096
},
"response_format": {
"enum": [
"text",
"json_object"
]
},
"provider": {
"enum": [
"openai",
"bedrock_mantle"
]
},
"region": {
"const": "us-east-1"
},
"json_policy": {
"const": "strict-object-or-one-outer-fence-v1"
},
"qualification": {
"type": "object",
"properties": {
"policy": {
"const": "qualified-value-v1"
},
"profile": {
"enum": [
"extract_fields",
"classify"
]
},
"prompt_version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"evidence_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[0-9a-f]{64}$"
},
"observed_passed": {
"type": "integer",
"minimum": 0
},
"observed_total": {
"type": "integer",
"minimum": 60
},
"observed_p95_seconds": {
"type": "number",
"minimum": 0,
"maximum": 30
},
"qualified_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"selection_basis": {
"enum": [
"caller_pin",
"highest_observed_lower_bound",
"lowest_observed_p95",
"lowest_qualified_supplier_allowance"
]
},
"scope": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"policy",
"profile",
"prompt_version",
"evidence_id",
"observed_passed",
"observed_total",
"observed_p95_seconds",
"qualified_at",
"expires_at",
"selection_basis",
"scope"
],
"additionalProperties": false
}
},
"required": [
"index",
"model",
"provider_model",
"reason",
"reasoning_effort",
"input_token_allowance",
"max_output_tokens",
"response_format"
],
"additionalProperties": false
}
},
"price_micros": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"processing": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"output_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"delivery_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"version",
"models",
"price_micros",
"processing",
"output_policy"
],
"additionalProperties": false
},
"recovery_token": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"expires_at": {
"type": "integer"
},
"retry": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"results": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"model": {
"enum": [
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
]
},
"provider_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"reported_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 65536
},
"finish_reason": {
"const": "stop"
},
"usage": {
"type": "object",
"properties": {
"prompt_tokens": {
"type": "integer",
"minimum": 0
},
"completion_tokens": {
"type": "integer",
"minimum": 0
},
"total_tokens": {
"type": "integer",
"minimum": 0
}
},
"required": [
"prompt_tokens",
"completion_tokens",
"total_tokens"
],
"additionalProperties": false
},
"validation": {
"type": "object",
"properties": {
"profile": {
"enum": [
"extract_fields",
"classify"
]
},
"prompt_version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"checks_passed": {
"type": "array",
"items": {
"enum": [
"json_shape",
"allowed_fields_or_labels",
"literal_source_evidence"
]
}
},
"semantic_correctness_guaranteed": {
"const": false
}
},
"required": [
"profile",
"prompt_version",
"checks_passed",
"semantic_correctness_guaranteed"
],
"additionalProperties": false
}
},
"required": [
"index",
"model",
"provider_model",
"reported_model",
"content",
"finish_reason",
"usage"
],
"additionalProperties": false
}
},
"receipt": {
"type": "object",
"properties": {
"network": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"transaction": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"price_micros": {
"type": "integer"
},
"finalized": {
"type": "boolean"
}
},
"required": [
"network",
"transaction",
"price_micros",
"finalized"
],
"additionalProperties": false
}
},
"required": [
"job_id",
"state",
"plan",
"recovery_token",
"expires_at",
"retry",
"results",
"receipt"
],
"additionalProperties": false
},
"example": {
"job_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "complete",
"plan": {
"version": "inference-v4-purchase",
"models": [
{
"index": 0,
"model": "gpt-6-luna",
"provider_model": "gpt-6-luna",
"reason": "bounded_general_task",
"reasoning_effort": "none",
"input_token_allowance": 326,
"max_output_tokens": 64,
"response_format": "text"
}
],
"price_micros": 2796,
"delivery_policy": "Stored results delivered after independently verified payment inclusion; finality reconciles separately.",
"processing": "OpenAI direct API; store=false; standard processing",
"output_policy": "Complete text or JSON object; refusals, truncation and any failed item are uncharged."
},
"recovery_token": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"expires_at": 1794528000,
"retry": "Recover with the original proof or private token. Do not pay again.",
"results": [
{
"index": 0,
"model": "gpt-6-luna",
"provider_model": "gpt-6-luna",
"reported_model": "gpt-6-luna",
"content": "The meeting starts at noon.",
"finish_reason": "stop",
"usage": {
"prompt_tokens": 18,
"completion_tokens": 7,
"total_tokens": 25
}
}
],
"receipt": {
"network": "eip155:8453",
"transaction": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"price_micros": 2796,
"finalized": true
}
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 x402 finalized payment receipt.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 16384
}
}
}
},
"202": {
"description": "Work or payment is pending. Retain original proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"state": {
"enum": [
"queued",
"running",
"settlement-pending"
]
},
"plan": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"models": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"model": {
"enum": [
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
]
},
"provider_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"reasoning_effort": {
"enum": [
"none",
"low",
"high",
null
]
},
"input_token_allowance": {
"type": "integer",
"minimum": 1
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096
},
"response_format": {
"enum": [
"text",
"json_object"
]
},
"provider": {
"enum": [
"openai",
"bedrock_mantle"
]
},
"region": {
"const": "us-east-1"
},
"json_policy": {
"const": "strict-object-or-one-outer-fence-v1"
},
"qualification": {
"type": "object",
"properties": {
"policy": {
"const": "qualified-value-v1"
},
"profile": {
"enum": [
"extract_fields",
"classify"
]
},
"prompt_version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"evidence_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[0-9a-f]{64}$"
},
"observed_passed": {
"type": "integer",
"minimum": 0
},
"observed_total": {
"type": "integer",
"minimum": 60
},
"observed_p95_seconds": {
"type": "number",
"minimum": 0,
"maximum": 30
},
"qualified_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"selection_basis": {
"enum": [
"caller_pin",
"highest_observed_lower_bound",
"lowest_observed_p95",
"lowest_qualified_supplier_allowance"
]
},
"scope": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"policy",
"profile",
"prompt_version",
"evidence_id",
"observed_passed",
"observed_total",
"observed_p95_seconds",
"qualified_at",
"expires_at",
"selection_basis",
"scope"
],
"additionalProperties": false
}
},
"required": [
"index",
"model",
"provider_model",
"reason",
"reasoning_effort",
"input_token_allowance",
"max_output_tokens",
"response_format"
],
"additionalProperties": false
}
},
"price_micros": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"processing": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"output_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"delivery_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"version",
"models",
"price_micros",
"processing",
"output_policy"
],
"additionalProperties": false
},
"recovery_token": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"expires_at": {
"type": "integer"
},
"retry": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"job_id",
"state",
"plan",
"recovery_token",
"expires_at",
"retry"
],
"additionalProperties": false
},
"example": {
"job_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "queued",
"plan": {
"version": "inference-v4-purchase",
"models": [
{
"index": 0,
"model": "gpt-6-luna",
"provider_model": "gpt-6-luna",
"reason": "bounded_general_task",
"reasoning_effort": "none",
"input_token_allowance": 326,
"max_output_tokens": 64,
"response_format": "text"
}
],
"price_micros": 2796,
"delivery_policy": "Stored results delivered after independently verified payment inclusion; finality reconciles separately.",
"processing": "OpenAI direct API; store=false; standard processing",
"output_policy": "Complete text or JSON object; refusals, truncation and any failed item are uncharged."
},
"recovery_token": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"expires_at": 1794528000,
"retry": "Recover with the original proof or private token. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid request or proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "Input-bound fixed quote; no supplier work performed.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 x402 offers bound to the exact input and routing plan.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 16384
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"const": "payment_required"
},
"price_usdc": {
"type": "string",
"minLength": 1,
"maxLength": 16
},
"plan": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"models": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"model": {
"enum": [
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
]
},
"provider_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"reasoning_effort": {
"enum": [
"none",
"low",
"high",
null
]
},
"input_token_allowance": {
"type": "integer",
"minimum": 1
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096
},
"response_format": {
"enum": [
"text",
"json_object"
]
},
"provider": {
"enum": [
"openai",
"bedrock_mantle"
]
},
"region": {
"const": "us-east-1"
},
"json_policy": {
"const": "strict-object-or-one-outer-fence-v1"
},
"qualification": {
"type": "object",
"properties": {
"policy": {
"const": "qualified-value-v1"
},
"profile": {
"enum": [
"extract_fields",
"classify"
]
},
"prompt_version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"evidence_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[0-9a-f]{64}$"
},
"observed_passed": {
"type": "integer",
"minimum": 0
},
"observed_total": {
"type": "integer",
"minimum": 60
},
"observed_p95_seconds": {
"type": "number",
"minimum": 0,
"maximum": 30
},
"qualified_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"selection_basis": {
"enum": [
"caller_pin",
"highest_observed_lower_bound",
"lowest_observed_p95",
"lowest_qualified_supplier_allowance"
]
},
"scope": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"policy",
"profile",
"prompt_version",
"evidence_id",
"observed_passed",
"observed_total",
"observed_p95_seconds",
"qualified_at",
"expires_at",
"selection_basis",
"scope"
],
"additionalProperties": false
}
},
"required": [
"index",
"model",
"provider_model",
"reason",
"reasoning_effort",
"input_token_allowance",
"max_output_tokens",
"response_format"
],
"additionalProperties": false
}
},
"price_micros": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"processing": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"output_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"delivery_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"version",
"models",
"price_micros",
"processing",
"output_policy"
],
"additionalProperties": false
},
"flow": {
"const": "quote-first-async"
},
"menu": {
"type": "object",
"properties": {
"options": {
"type": "array",
"maxItems": 9,
"items": {
"type": "object",
"properties": {
"option_id": {
"type": "string",
"minLength": 1,
"maxLength": 24
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"recommended": {
"type": "boolean"
},
"request": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"minItems": 1,
"maxItems": 16,
"items": {
"type": "object",
"properties": {
"role": {
"enum": [
"system",
"user",
"assistant"
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 16000
}
},
"required": [
"role",
"content"
],
"additionalProperties": false
}
},
"model": {
"enum": [
"auto",
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
],
"default": "auto",
"description": "Gemma is only eligible for a checked contract with current qualification and supplier authorization."
},
"task": {
"enum": [
"auto",
"extract",
"classify",
"summarize",
"translate",
"write",
"code",
"analyze",
"plan"
],
"default": "auto"
},
"priority": {
"enum": [
"balanced",
"economy",
"quality",
"speed"
],
"default": "balanced"
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096,
"default": 1000,
"description": "Total billed output ceiling, including reasoning and non-visible tokens. Small ceilings can truncate a response; truncated work is uncharged."
},
"response_format": {
"enum": [
"text",
"json_object"
],
"default": "text"
},
"contract": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "extract_fields"
},
"fields": {
"type": "object",
"minProperties": 1,
"maxProperties": 3,
"propertyNames": {
"pattern": "^[a-z][a-z0-9_]{0,31}$",
"not": {
"const": "abstain"
}
},
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
}
},
"required": [
"kind",
"fields"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "classify"
},
"labels": {
"type": "object",
"minProperties": 2,
"maxProperties": 3,
"propertyNames": {
"pattern": "^[a-z][a-z0-9_]{0,31}$",
"not": {
"const": "abstain"
}
},
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
}
},
"required": [
"kind",
"labels"
],
"additionalProperties": false
}
],
"description": "Optional checked workflow for one English user-message source, at most 8000 UTF-8 bytes. Requires json_object and at least the qualified model output allowance (currently 2048). Returns 422 when no current qualified candidate fits. Field values and evidence are verbatim source spans; missing/ambiguous fields are null. Classification can abstain. Validation does not prove semantic correctness."
}
},
"required": [
"messages"
],
"additionalProperties": false
}
},
"max_price_usdc": {
"type": "string",
"minLength": 1,
"maxLength": 8,
"pattern": "^(?:0(?:\\.[0-9]{1,6})?|1(?:\\.0{1,6})?)$"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9_-]{22,128}$"
}
},
"required": [
"tasks",
"max_price_usdc"
],
"additionalProperties": false
},
"plan": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"models": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"model": {
"enum": [
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
]
},
"provider_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"reasoning_effort": {
"enum": [
"none",
"low",
"high",
null
]
},
"input_token_allowance": {
"type": "integer",
"minimum": 1
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096
},
"response_format": {
"enum": [
"text",
"json_object"
]
},
"provider": {
"enum": [
"openai",
"bedrock_mantle"
]
},
"region": {
"const": "us-east-1"
},
"json_policy": {
"const": "strict-object-or-one-outer-fence-v1"
},
"qualification": {
"type": "object",
"properties": {
"policy": {
"const": "qualified-value-v1"
},
"profile": {
"enum": [
"extract_fields",
"classify"
]
},
"prompt_version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"evidence_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[0-9a-f]{64}$"
},
"observed_passed": {
"type": "integer",
"minimum": 0
},
"observed_total": {
"type": "integer",
"minimum": 60
},
"observed_p95_seconds": {
"type": "number",
"minimum": 0,
"maximum": 30
},
"qualified_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"selection_basis": {
"enum": [
"caller_pin",
"highest_observed_lower_bound",
"lowest_observed_p95",
"lowest_qualified_supplier_allowance"
]
},
"scope": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"policy",
"profile",
"prompt_version",
"evidence_id",
"observed_passed",
"observed_total",
"observed_p95_seconds",
"qualified_at",
"expires_at",
"selection_basis",
"scope"
],
"additionalProperties": false
}
},
"required": [
"index",
"model",
"provider_model",
"reason",
"reasoning_effort",
"input_token_allowance",
"max_output_tokens",
"response_format"
],
"additionalProperties": false
}
},
"price_micros": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"processing": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"output_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"delivery_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"version",
"models",
"price_micros",
"processing",
"output_policy"
],
"additionalProperties": false
},
"payment_required": {
"type": "object",
"description": "Complete x402 PaymentRequired object for this exact option request."
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"option_id",
"label",
"recommended",
"request",
"plan",
"payment_required",
"reason"
],
"additionalProperties": false
}
},
"assessment": {
"type": "object",
"properties": {
"basis": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input_bytes": {
"type": "integer",
"minimum": 0
},
"tasks": {
"type": "array",
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer"
},
"recommended_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"rule": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"index",
"recommended_model",
"rule"
],
"additionalProperties": false
}
},
"quality_prediction": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"latency_estimate_seconds": {
"type": "null"
}
},
"required": [
"basis",
"input_bytes",
"tasks",
"quality_prediction",
"latency_estimate_seconds"
],
"additionalProperties": false
},
"choose": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"options",
"assessment",
"choose"
],
"additionalProperties": false
},
"referral": {
"type": "object",
"properties": {
"mode": {
"const": "none"
},
"commission_promised": {
"const": false
}
},
"required": [
"mode",
"commission_promised"
],
"additionalProperties": false
}
},
"required": [
"error",
"price_usdc",
"plan",
"flow"
],
"additionalProperties": false
},
"example": {
"error": "payment_required",
"price_usdc": "0.002796",
"plan": {
"version": "inference-v4-purchase",
"models": [
{
"index": 0,
"model": "gpt-6-luna",
"provider_model": "gpt-6-luna",
"reason": "bounded_general_task",
"reasoning_effort": "none",
"input_token_allowance": 326,
"max_output_tokens": 64,
"response_format": "text"
}
],
"price_micros": 2796,
"delivery_policy": "Stored results delivered after independently verified payment inclusion; finality reconciles separately.",
"processing": "OpenAI direct API; store=false; standard processing",
"output_policy": "Complete text or JSON object; refusals, truncation and any failed item are uncharged."
},
"flow": "quote-first-async"
}
}
}
},
"409": {
"description": "Payment or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"error"
]
},
"example": {
"error": "temporarily_unavailable"
}
}
}
},
"410": {
"description": "Uncharged failed work or expired private recovery; inspect response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"error"
]
},
"example": {
"error": "supplier_work_incomplete"
}
}
}
},
"413": {
"description": "Input too large.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"error"
]
},
"example": {
"error": "temporarily_unavailable"
}
}
}
},
"415": {
"description": "Expected application/json.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"error"
]
},
"example": {
"error": "temporarily_unavailable"
}
}
}
},
"422": {
"description": "Selected work exceeds spending limit; no silent model downgrade.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"menu": {
"type": "object",
"properties": {
"options": {
"type": "array",
"maxItems": 9,
"items": {
"type": "object",
"properties": {
"option_id": {
"type": "string",
"minLength": 1,
"maxLength": 24
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"recommended": {
"type": "boolean"
},
"request": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"minItems": 1,
"maxItems": 16,
"items": {
"type": "object",
"properties": {
"role": {
"enum": [
"system",
"user",
"assistant"
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 16000
}
},
"required": [
"role",
"content"
],
"additionalProperties": false
}
},
"model": {
"enum": [
"auto",
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
],
"default": "auto",
"description": "Gemma is only eligible for a checked contract with current qualification and supplier authorization."
},
"task": {
"enum": [
"auto",
"extract",
"classify",
"summarize",
"translate",
"write",
"code",
"analyze",
"plan"
],
"default": "auto"
},
"priority": {
"enum": [
"balanced",
"economy",
"quality",
"speed"
],
"default": "balanced"
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096,
"default": 1000,
"description": "Total billed output ceiling, including reasoning and non-visible tokens. Small ceilings can truncate a response; truncated work is uncharged."
},
"response_format": {
"enum": [
"text",
"json_object"
],
"default": "text"
},
"contract": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "extract_fields"
},
"fields": {
"type": "object",
"minProperties": 1,
"maxProperties": 3,
"propertyNames": {
"pattern": "^[a-z][a-z0-9_]{0,31}$",
"not": {
"const": "abstain"
}
},
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
}
},
"required": [
"kind",
"fields"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "classify"
},
"labels": {
"type": "object",
"minProperties": 2,
"maxProperties": 3,
"propertyNames": {
"pattern": "^[a-z][a-z0-9_]{0,31}$",
"not": {
"const": "abstain"
}
},
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
}
},
"required": [
"kind",
"labels"
],
"additionalProperties": false
}
],
"description": "Optional checked workflow for one English user-message source, at most 8000 UTF-8 bytes. Requires json_object and at least the qualified model output allowance (currently 2048). Returns 422 when no current qualified candidate fits. Field values and evidence are verbatim source spans; missing/ambiguous fields are null. Classification can abstain. Validation does not prove semantic correctness."
}
},
"required": [
"messages"
],
"additionalProperties": false
}
},
"max_price_usdc": {
"type": "string",
"minLength": 1,
"maxLength": 8,
"pattern": "^(?:0(?:\\.[0-9]{1,6})?|1(?:\\.0{1,6})?)$"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9_-]{22,128}$"
}
},
"required": [
"tasks",
"max_price_usdc"
],
"additionalProperties": false
},
"plan": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"models": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"model": {
"enum": [
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
]
},
"provider_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"reasoning_effort": {
"enum": [
"none",
"low",
"high",
null
]
},
"input_token_allowance": {
"type": "integer",
"minimum": 1
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096
},
"response_format": {
"enum": [
"text",
"json_object"
]
},
"provider": {
"enum": [
"openai",
"bedrock_mantle"
]
},
"region": {
"const": "us-east-1"
},
"json_policy": {
"const": "strict-object-or-one-outer-fence-v1"
},
"qualification": {
"type": "object",
"properties": {
"policy": {
"const": "qualified-value-v1"
},
"profile": {
"enum": [
"extract_fields",
"classify"
]
},
"prompt_version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"evidence_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[0-9a-f]{64}$"
},
"observed_passed": {
"type": "integer",
"minimum": 0
},
"observed_total": {
"type": "integer",
"minimum": 60
},
"observed_p95_seconds": {
"type": "number",
"minimum": 0,
"maximum": 30
},
"qualified_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"selection_basis": {
"enum": [
"caller_pin",
"highest_observed_lower_bound",
"lowest_observed_p95",
"lowest_qualified_supplier_allowance"
]
},
"scope": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"policy",
"profile",
"prompt_version",
"evidence_id",
"observed_passed",
"observed_total",
"observed_p95_seconds",
"qualified_at",
"expires_at",
"selection_basis",
"scope"
],
"additionalProperties": false
}
},
"required": [
"index",
"model",
"provider_model",
"reason",
"reasoning_effort",
"input_token_allowance",
"max_output_tokens",
"response_format"
],
"additionalProperties": false
}
},
"price_micros": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"processing": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"output_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"delivery_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"version",
"models",
"price_micros",
"processing",
"output_policy"
],
"additionalProperties": false
},
"payment_required": {
"type": "object",
"description": "Complete x402 PaymentRequired object for this exact option request."
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"option_id",
"label",
"recommended",
"request",
"plan",
"payment_required",
"reason"
],
"additionalProperties": false
}
},
"assessment": {
"type": "object",
"properties": {
"basis": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input_bytes": {
"type": "integer",
"minimum": 0
},
"tasks": {
"type": "array",
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer"
},
"recommended_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"rule": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"index",
"recommended_model",
"rule"
],
"additionalProperties": false
}
},
"quality_prediction": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"latency_estimate_seconds": {
"type": "null"
}
},
"required": [
"basis",
"input_bytes",
"tasks",
"quality_prediction",
"latency_estimate_seconds"
],
"additionalProperties": false
},
"choose": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"options",
"assessment",
"choose"
],
"additionalProperties": false
}
},
"required": [
"error"
]
},
"example": {
"error": "budget_too_low"
}
}
}
},
"429": {
"description": "Admission capacity unavailable; no payment started.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"error"
]
},
"example": {
"error": "temporarily_unavailable"
}
}
}
},
"503": {
"description": "Unavailable; retain original proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"error"
]
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "PAYMENT-SIGNATURE",
"in": "header",
"required": false,
"description": "Optional x402 proof; omit to receive an input-bound quote before authorizing.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 16384
}
}
]Export reconciled payment receipts
POST /v1/finance/receipts/export-payment-ledger
0.05 USDC per completed report of up to 10 receipts
Service scope, examples and recovery →
Reconcile 1–10 supplied native-USDC payment receipts on Base and Solana into JSON and CSV. Match finalized transfers, separate transaction-level fees, linked reverse transfers, duplicates and caller delivery claims. 0.05 USDC per completed report; provider failures are uncharged. A completed report can contain pending, failed, ambiguous or mismatched claims.
Input fields
request_idRequired · string- See the complete request schema for values and bounds.
receiptsRequired · array- See the complete request schema for values and bounds.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"receipts"
],
"properties": {
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{12,80}$"
},
"receipts": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"network",
"transaction",
"payer",
"payee",
"amount_usdc"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"network": {
"type": "string",
"enum": [
"eip155:8453",
"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
]
},
"transaction": {
"type": "string",
"minLength": 64,
"maxLength": 88
},
"payer": {
"type": "string",
"minLength": 32,
"maxLength": 44
},
"payee": {
"type": "string",
"minLength": 32,
"maxLength": 44
},
"amount_usdc": {
"type": "string",
"pattern": "^(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,6})?$",
"description": "Positive decimal USDC, at most 6 fractional digits. No floats."
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"delivery_status": {
"type": "string",
"enum": [
"delivered",
"missing",
"unknown"
]
},
"refund": {
"type": "object",
"additionalProperties": false,
"required": [
"transaction",
"amount_usdc"
],
"properties": {
"transaction": {
"type": "string",
"minLength": 64,
"maxLength": 88
},
"amount_usdc": {
"type": "string",
"pattern": "^(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,6})?$"
}
}
}
}
}
}
}
},
"example": {
"request_id": "receipts_example_001",
"receipts": [
{
"id": "purchase-001",
"network": "eip155:8453",
"transaction": "0xabababababababababababababababababababababababababababababababab",
"payer": "0x1111111111111111111111111111111111111111",
"payee": "0x2222222222222222222222222222222222222222",
"amount_usdc": "0.050000",
"label": "Synthetic API purchase",
"delivery_status": "unknown"
}
]
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"observed_at",
"rows",
"transactions",
"totals",
"csv",
"fees_csv",
"limitations"
],
"properties": {
"status": {
"type": "string",
"const": "ok"
},
"observed_at": {
"type": "string"
},
"rows": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"label",
"network",
"transaction",
"payer",
"payee",
"expected_usdc",
"settlement_status",
"matched_usdc",
"delivery_claim",
"refund_status",
"refund_usdc",
"net_usdc",
"block_time",
"transfer_index",
"duplicate_of",
"refund_transaction",
"delivery_verified"
],
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"network": {
"type": "string"
},
"transaction": {
"type": "string"
},
"payer": {
"type": "string"
},
"payee": {
"type": "string"
},
"expected_usdc": {
"type": "string"
},
"settlement_status": {
"type": "string"
},
"matched_usdc": {
"type": "string"
},
"delivery_claim": {
"type": "string"
},
"refund_status": {
"type": "string"
},
"refund_usdc": {
"type": "string"
},
"net_usdc": {
"type": "string"
},
"block_time": {
"type": [
"string",
"null"
]
},
"transfer_index": {
"type": [
"string",
"null"
]
},
"duplicate_of": {
"type": [
"string",
"null"
]
},
"refund_transaction": {
"type": [
"string",
"null"
]
},
"delivery_verified": {
"type": "boolean",
"const": false
}
}
}
},
"transactions": {
"type": "array",
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"network",
"transaction",
"state",
"block_time",
"fee",
"source_sha256"
],
"properties": {
"network": {
"type": "string"
},
"transaction": {
"type": "string"
},
"state": {
"type": "string"
},
"block_time": {
"type": [
"string",
"null"
]
},
"fee": {
"anyOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"payer",
"unit",
"execution_atomic",
"l1_data_atomic",
"observed_components_atomic",
"completeness"
],
"properties": {
"payer": {
"type": "string"
},
"unit": {
"type": "string",
"enum": [
"wei",
"lamports"
]
},
"execution_atomic": {
"type": "string"
},
"l1_data_atomic": {
"type": [
"string",
"null"
]
},
"observed_components_atomic": {
"type": "string"
},
"completeness": {
"type": "string",
"enum": [
"observed_components_only",
"network_transaction_fee"
]
}
}
},
{
"type": "null"
}
]
},
"source_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
}
}
},
"totals": {
"type": "object",
"additionalProperties": false,
"required": [
"matched_principal_usdc",
"matched_refunds_usdc",
"net_matched_usdc"
],
"properties": {
"matched_principal_usdc": {
"type": "string"
},
"matched_refunds_usdc": {
"type": "string"
},
"net_matched_usdc": {
"type": "string"
}
}
},
"csv": {
"type": "string"
},
"fees_csv": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"observed_at": "2026-10-26T15:01:00+00:00",
"rows": [
{
"id": "purchase-001",
"label": "Synthetic API purchase",
"network": "eip155:8453",
"transaction": "0xabababababababababababababababababababababababababababababababab",
"payer": "0x1111111111111111111111111111111111111111",
"payee": "0x2222222222222222222222222222222222222222",
"expected_usdc": "0.050000",
"settlement_status": "matched",
"block_time": "2026-10-26T15:00:00+00:00",
"matched_usdc": "0.050000",
"transfer_index": "0",
"duplicate_of": null,
"delivery_claim": "unknown",
"delivery_verified": false,
"refund_transaction": null,
"refund_status": "not_supplied",
"refund_usdc": "0.000000",
"net_usdc": "0.050000"
}
],
"transactions": [
{
"network": "eip155:8453",
"transaction": "0xabababababababababababababababababababababababababababababababab",
"state": "finalized",
"block_time": "2026-10-26T15:00:00+00:00",
"fee": {
"payer": "0x3333333333333333333333333333333333333333",
"unit": "wei",
"execution_atomic": "210000000000",
"l1_data_atomic": "1000000000",
"observed_components_atomic": "211000000000",
"completeness": "observed_components_only"
},
"source_sha256": "352ba3d7b9214968eb9d6bd7502ab7475c1ea22f128e6073c6e7dd482af9399a"
}
],
"totals": {
"matched_principal_usdc": "0.050000",
"matched_refunds_usdc": "0.000000",
"net_matched_usdc": "0.050000"
},
"csv": "id,label,network,transaction,payer,payee,expected_usdc,settlement_status,block_time,matched_usdc,duplicate_of,delivery_claim,delivery_verified,refund_transaction,refund_status,refund_usdc,net_usdc\r\npurchase-001,Synthetic API purchase,eip155:8453,0xabababababababababababababababababababababababababababababababab,0x1111111111111111111111111111111111111111,0x2222222222222222222222222222222222222222,0.050000,matched,2026-10-26T15:00:00+00:00,0.050000,,unknown,False,,not_supplied,0.000000,0.050000\r\n",
"fees_csv": "network,transaction,state,block_time,fee_payer,unit,execution_atomic,l1_data_atomic,observed_components_atomic,completeness\r\neip155:8453,0xabababababababababababababababababababababababababababababababab,finalized,2026-10-26T15:00:00+00:00,0x3333333333333333333333333333333333333333,wei,210000000000,1000000000,211000000000,observed_components_only\r\n",
"limitations": [
"Only supplied transaction claims are reconciled; this is not complete wallet history or tax advice.",
"Block time is inclusion time, not the exact moment finality occurred.",
"Delivery labels and the relationship of a reverse transfer to a purchase are caller claims, not chain proof.",
"Fees are transaction-level native units paid by the reported fee payer; sponsored fees are not automatically buyer expenses.",
"Base fee fields report observed components; absent additional fees are not assumed zero.",
"CSV formula-like text is prefixed with an apostrophe for spreadsheet safety."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.050000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Compare API request quotes
POST /v1/services/offers/compare-request-quotes
0.005 USDC per complete dated quote comparison
Service scope, examples and recovery →
Compare current unsigned x402 quotes for 2–4 supplied API requests. Return original challenges, native USDC prices on Base/Solana, advertised outputs and explicit fee, expiry and quality gaps. Identify lowest quoted amounts per network without claiming equivalent delivery or lowest total cost. No seller purchases, credentials or market-wide search. 0.005 USDC per complete comparison; unavailable or invalid candidate quotes are uncharged.
Input fields
request_idRequired · string- See the complete request schema for values and bounds.
taskRequired · string- See the complete request schema for values and bounds.
candidatesRequired · array- See the complete request schema for values and bounds.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"task",
"candidates"
],
"properties": {
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"task": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"candidates": {
"type": "array",
"minItems": 2,
"maxItems": 4,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"url"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,40}$"
},
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"pattern": "^https://"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
],
"default": "GET"
},
"body": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"description": "POST JSON, at most 4096 encoded bytes; GET has no body. Credentials/payment fields are rejected."
}
}
}
}
}
},
"example": {
"request_id": "quote_comparison_example_001",
"task": "Compare quoted prices for extracting readable content from the Mekler homepage",
"candidates": [
{
"id": "markdown",
"url": "https://x402.shizu.me/markdown?url=https%3A%2F%2Fmekler.ai%2F",
"method": "GET"
},
{
"id": "readable-text",
"url": "https://true402.dev/api/v1/web-extract",
"method": "POST",
"body": {
"url": "https://mekler.ai/"
}
}
]
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"task",
"observed_at",
"observations",
"price_groups",
"scope",
"limitations"
],
"properties": {
"status": {
"type": "string",
"const": "ok"
},
"task": {
"type": "string"
},
"observed_at": {
"type": "string"
},
"observations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"url",
"method",
"request_sha256",
"resource_url",
"description",
"description_truncated",
"observed_at",
"challenge_sha256",
"payment_required_header",
"offers",
"input_binding",
"source_limits"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"method": {
"type": "string"
},
"request_sha256": {
"type": "string"
},
"resource_url": {
"type": "string"
},
"description": {
"type": "string"
},
"description_truncated": {
"type": "boolean"
},
"observed_at": {
"type": "string"
},
"challenge_sha256": {
"type": "string"
},
"payment_required_header": {
"type": "string"
},
"offers": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"network",
"asset",
"scheme",
"amount_atomic",
"quoted_usdc",
"recipient",
"payment_timeout_seconds",
"quote_expires_at",
"additional_fees",
"total_cost_usdc"
],
"properties": {
"network": {
"type": "string"
},
"asset": {
"type": "string"
},
"scheme": {
"type": "string"
},
"amount_atomic": {
"type": "string"
},
"quoted_usdc": {
"type": "string"
},
"recipient": {
"type": "string"
},
"payment_timeout_seconds": {
"type": "integer"
},
"quote_expires_at": {
"type": "null"
},
"additional_fees": {
"type": "null"
},
"total_cost_usdc": {
"type": "null"
}
}
}
},
"input_binding": {
"type": "string"
},
"source_limits": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"price_groups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"network",
"asset",
"quoted_amounts",
"lowest_quoted_candidate_ids",
"comparison_available",
"lowest_total_cost_candidate_id",
"equivalent_outputs_verified"
],
"properties": {
"network": {
"type": "string"
},
"asset": {
"type": "string"
},
"quoted_amounts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"amount_atomic"
],
"properties": {
"id": {
"type": "string"
},
"amount_atomic": {
"type": "string"
}
}
}
},
"lowest_quoted_candidate_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"comparison_available": {
"type": "boolean"
},
"lowest_total_cost_candidate_id": {
"type": "null"
},
"equivalent_outputs_verified": {
"type": "boolean"
}
}
}
},
"scope": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"task": "Compare quoted prices for extracting readable content from the Mekler homepage",
"observed_at": "2026-10-26T15:00:01+00:00",
"observations": [
{
"id": "markdown",
"url": "https://x402.shizu.me/markdown?url=https%3A%2F%2Fmekler.ai%2F",
"method": "GET",
"request_sha256": "a724b7ba65d3b802ab6ace9168bcad86c1b882d40147d38ab7a7d9aa61b69932",
"resource_url": "https://x402.shizu.me/markdown?url=https%3A%2F%2Fmekler.ai%2F",
"description": "Synthetic advertised extraction output",
"description_truncated": false,
"observed_at": "2026-10-26T15:00:00+00:00",
"challenge_sha256": "66be961ebc87e2eb224610c41d4e57721c36e3366a670f9f361517de0c73cf85",
"payment_required_header": "eyJ4NDAyVmVyc2lvbiI6IDIsICJyZXNvdXJjZSI6IHsidXJsIjogImh0dHBzOi8veDQwMi5zaGl6dS5tZS9tYXJrZG93bj91cmw9aHR0cHMlM0ElMkYlMkZtZWtsZXIuYWklMkYiLCAiZGVzY3JpcHRpb24iOiAiU3ludGhldGljIGFkdmVydGlzZWQgZXh0cmFjdGlvbiBvdXRwdXQiLCAibWltZVR5cGUiOiAiYXBwbGljYXRpb24vanNvbiJ9LCAiYWNjZXB0cyI6IFt7InNjaGVtZSI6ICJleGFjdCIsICJuZXR3b3JrIjogImVpcDE1NTo4NDUzIiwgImFzc2V0IjogIjB4ODMzNTg5ZkNENmVEYjZFMDhmNGM3QzMyRDRmNzFiNTRiZEEwMjkxMyIsICJhbW91bnQiOiAiNDAwMCIsICJwYXlUbyI6ICIweDExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTEiLCAibWF4VGltZW91dFNlY29uZHMiOiAzMDAsICJleHRyYSI6IHsibmFtZSI6ICJVU0QgQ29pbiIsICJ2ZXJzaW9uIjogIjIifX1dfQ==",
"offers": [
{
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"scheme": "exact",
"amount_atomic": "4000",
"quoted_usdc": "0.004000",
"recipient": "0x1111111111111111111111111111111111111111",
"payment_timeout_seconds": 300,
"quote_expires_at": null,
"additional_fees": null,
"total_cost_usdc": null
}
],
"input_binding": "Observed for this request; seller cryptographic body binding is unverified.",
"source_limits": [
"Seller delivery quality, output capacity, fees and guaranteed expiry are not independently verified."
]
},
{
"id": "readable-text",
"url": "https://true402.dev/api/v1/web-extract",
"method": "POST",
"request_sha256": "77abbded48d17bb560589def54855c17e08ed46b1c443fc767e37c28bbe65de2",
"resource_url": "https://true402.dev/api/v1/web-extract",
"description": "Synthetic advertised extraction output",
"description_truncated": false,
"observed_at": "2026-10-26T15:00:00+00:00",
"challenge_sha256": "ac6d1a4aecdfca184bcd60187aa57ad93ac7b211cfac5145f1b6f3485529b157",
"payment_required_header": "eyJ4NDAyVmVyc2lvbiI6IDIsICJyZXNvdXJjZSI6IHsidXJsIjogImh0dHBzOi8vdHJ1ZTQwMi5kZXYvYXBpL3YxL3dlYi1leHRyYWN0IiwgImRlc2NyaXB0aW9uIjogIlN5bnRoZXRpYyBhZHZlcnRpc2VkIGV4dHJhY3Rpb24gb3V0cHV0IiwgIm1pbWVUeXBlIjogImFwcGxpY2F0aW9uL2pzb24ifSwgImFjY2VwdHMiOiBbeyJzY2hlbWUiOiAiZXhhY3QiLCAibmV0d29yayI6ICJlaXAxNTU6ODQ1MyIsICJhc3NldCI6ICIweDgzMzU4OWZDRDZlRGI2RTA4ZjRjN0MzMkQ0ZjcxYjU0YmRBMDI5MTMiLCAiYW1vdW50IjogIjUwMDAiLCAicGF5VG8iOiAiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwgIm1heFRpbWVvdXRTZWNvbmRzIjogMzAwLCAiZXh0cmEiOiB7Im5hbWUiOiAiVVNEIENvaW4iLCAidmVyc2lvbiI6ICIyIn19XX0=",
"offers": [
{
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"scheme": "exact",
"amount_atomic": "5000",
"quoted_usdc": "0.005000",
"recipient": "0x1111111111111111111111111111111111111111",
"payment_timeout_seconds": 300,
"quote_expires_at": null,
"additional_fees": null,
"total_cost_usdc": null
}
],
"input_binding": "Observed for this request; seller cryptographic body binding is unverified.",
"source_limits": [
"Seller delivery quality, output capacity, fees and guaranteed expiry are not independently verified."
]
}
],
"price_groups": [
{
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"quoted_amounts": [
{
"id": "markdown",
"amount_atomic": "4000"
},
{
"id": "readable-text",
"amount_atomic": "5000"
}
],
"lowest_quoted_candidate_ids": [
"markdown"
],
"comparison_available": true,
"lowest_total_cost_candidate_id": null,
"equivalent_outputs_verified": false
}
],
"scope": "Supplied candidate requests only; no market-wide discovery or seller purchase.",
"limitations": [
"Lowest quoted amount is not lowest total cost or best value.",
"Candidates are caller-selected; equivalent task fulfillment is not verified.",
"Payment timeout is not quote expiry or a delivery guarantee.",
"Stored recovery preserves the original dated comparison; it does not refresh quotes."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Check OFAC sanctions list name and identifier matches
POST /v1/data/sanctions/check-list-matches
0.01 USDC per completed matching diagnostic
Service scope, examples and recovery →
Match a supplied name and optional typed identifiers against freshly retrieved OFAC SDN and Consolidated lists. Return potential candidates, strong/weak aliases, matching evidence and versioned source dates/hashes. Similarity is heuristic; no identity, transaction-legality or clearance guarantee. 0.01 USDC per completed diagnostic; source/limit failures are uncharged.
Input fields
nameRequired · string- One name, at least two normalized alphanumeric characters. Unicode accepted. Case/accent/punctuation folding and token-order matching; fuzzy threshold 85, short names exact only. No transliteration.
identifiersOptional · array- See the complete request schema for values and bounds.
request_idRequired · string- Fresh purchase identity; retain the same JSON and original proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"request_id"
],
"properties": {
"name": {
"type": "string",
"maxLength": 160,
"minLength": 2,
"description": "One name, at least two normalized alphanumeric characters. Unicode accepted. Case/accent/punctuation folding and token-order matching; fuzzy threshold 85, short names exact only. No transliteration."
},
"identifiers": {
"type": "array",
"maxItems": 5,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Exact OFAC identifier label, such as Passport or Registration Number; case-insensitive type comparison."
},
"value": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Exact source identifier value after outer whitespace removal. Case/punctuation variants are not normalized."
}
}
},
"default": []
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh purchase identity; retain the same JSON and original proof for recovery."
}
}
},
"example": {
"name": "Mekler Example Trading",
"request_id": "sanctions-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"verdict",
"name",
"matches",
"observed_at",
"coverage",
"limitations"
],
"properties": {
"status": {
"type": "string",
"const": "ok"
},
"verdict": {
"type": "string",
"enum": [
"potential_matches",
"no_matches"
]
},
"name": {
"type": "string",
"maxLength": 160
},
"matches": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"list",
"uid",
"primary_name",
"entity_type",
"programs",
"name_matches",
"identifier_matches",
"basis",
"weak_alias_only",
"review_required",
"source_url"
],
"properties": {
"list": {
"type": "string",
"enum": [
"ofac_sdn",
"ofac_consolidated"
]
},
"uid": {
"type": "string",
"maxLength": 12
},
"primary_name": {
"type": "string",
"maxLength": 1024
},
"entity_type": {
"type": "string",
"maxLength": 80
},
"programs": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 128
}
},
"name_matches": {
"type": "array",
"maxItems": 500,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"kind",
"quality",
"method",
"similarity"
],
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"kind": {
"type": "string",
"enum": [
"primary",
"alias"
]
},
"quality": {
"type": "string",
"enum": [
"primary",
"strong",
"weak"
]
},
"method": {
"type": "string",
"enum": [
"normalized_exact",
"token_order_exact",
"fuzzy_token_similarity"
]
},
"similarity": {
"type": "number",
"minimum": 85,
"maximum": 100,
"description": "Heuristic string similarity, not a probability or OFAC Search score."
}
}
}
},
"identifier_matches": {
"type": "array",
"maxItems": 5,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Exact OFAC identifier label, such as Passport or Registration Number; case-insensitive type comparison."
},
"value": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Exact source identifier value after outer whitespace removal. Case/punctuation variants are not normalized."
}
}
}
},
"basis": {
"type": "string",
"enum": [
"exact_identifier",
"name_candidate"
]
},
"weak_alias_only": {
"type": "boolean"
},
"review_required": {
"type": "boolean",
"const": true
},
"source_url": {
"type": "string",
"maxLength": 256
}
}
}
},
"observed_at": {
"type": "string",
"maxLength": 40
},
"coverage": {
"type": "object",
"additionalProperties": false,
"required": [
"sources",
"query_complete",
"matching_policy",
"name_similarity_threshold",
"candidate_limit"
],
"properties": {
"sources": {
"type": "array",
"maxItems": 2,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"list",
"source_url",
"sha256",
"published_date",
"retrieved_at",
"records"
],
"properties": {
"list": {
"type": "string",
"enum": [
"ofac_sdn",
"ofac_consolidated"
]
},
"source_url": {
"type": "string",
"maxLength": 256
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"published_date": {
"type": "string",
"maxLength": 10
},
"retrieved_at": {
"type": "string",
"maxLength": 40
},
"records": {
"type": "integer",
"minimum": 0,
"maximum": 100000
}
}
}
},
"query_complete": {
"type": "boolean",
"const": true
},
"matching_policy": {
"type": "string",
"const": "ofac-candidate-v1"
},
"name_similarity_threshold": {
"type": "integer",
"const": 85
},
"candidate_limit": {
"type": "integer",
"const": 50
}
}
},
"limitations": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string",
"maxLength": 1024
}
}
}
},
"example": {
"status": "ok",
"verdict": "potential_matches",
"name": "Mekler Example Trading",
"matches": [
{
"list": "ofac_sdn",
"uid": "900001",
"primary_name": "Mekler Example Trading",
"entity_type": "Entity",
"programs": [
"SYNTHETIC"
],
"name_matches": [
{
"name": "Mekler Example Trading",
"kind": "primary",
"quality": "primary",
"method": "normalized_exact",
"similarity": 100
}
],
"identifier_matches": [],
"basis": "name_candidate",
"weak_alias_only": false,
"review_required": true,
"source_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN.XML"
}
],
"observed_at": "2026-10-23T00:00:00Z",
"coverage": {
"sources": [
{
"list": "ofac_sdn",
"source_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN.XML",
"sha256": "c4ba3d2a9e10e6e904335895b4263beddf3e8037b1e598e8d42b877fcdecba97",
"published_date": "2026-10-21",
"retrieved_at": "2026-10-23T00:00:00Z",
"records": 1
},
{
"list": "ofac_consolidated",
"source_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/CONSOLIDATED.XML",
"sha256": "cbae6b57debbecedfbce3a18af6bab30d4a8df42d96a81ff5e1e5a650b706efc",
"published_date": "2026-10-21",
"retrieved_at": "2026-10-23T00:00:00Z",
"records": 0
}
],
"query_complete": true,
"matching_policy": "ofac-candidate-v1",
"name_similarity_threshold": 85,
"candidate_limit": 50
},
"limitations": [
"Potential matches require review; names and identifiers do not establish identity, a prohibition or legal clearance. No matches is not permission to transact.",
"Coverage is OFAC SDN and Non-SDN Consolidated legacy XML only. Non-SDN programs impose different restrictions. Other jurisdictions, ownership/control and the 50 Percent Rule are not assessed.",
"Names use Unicode case folding, accent removal, punctuation spacing and token ordering; fuzzy similarity is a heuristic, not a probability or OFAC Search score. No transliteration or phonetic matching; short names require an exact normalized token match.",
"Identifier types compare case-insensitively to the exact OFAC label; values compare exactly after outer whitespace removal. Alternative formats, case variants and identifiers recorded only in remarks can be missed.",
"Each full source is freshly retrieved for this purchase; publication dates can differ. Retrieval time does not establish publisher freshness or a synchronized snapshot. Recovered results retain the original dated evidence.",
"No ongoing monitoring, PEP search, transaction approval or legal advice. Weak aliases and common names can produce false positives; unlisted parties and missed variants can produce non-matches."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.010000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Check package version vulnerabilities
POST /v1/data/packages/check-version-vulnerabilities
0.01 USDC per completed diagnostic
Service scope, examples and recovery →
Check an exact PyPI or npm package version against OSV advisories, group aliases and report affected/fixed version evidence and CISA known exploitation. Preserve source disagreements, withdrawn records, unsupported ranges and dated coverage. No dependency traversal, malware scan, registry existence check or safety guarantee. 0.01 USDC per completed diagnostic; source failures and incomplete pagination are uncharged.
Input fields
ecosystemRequired · string- See the complete request schema for values and bounds.
nameRequired · string- PyPI project name or lowercase npm name, optionally @scope/name. PyPI names normalize runs of dash, underscore and dot to dash.
versionRequired · string- Required exact version: PyPI PEP 440 without local build suffix; npm strict SemVer 2.0. No ranges, tags or dependency trees. Versions are ordered against advisory boundaries, including prereleases.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"ecosystem": {
"type": "string",
"enum": [
"pypi",
"npm"
]
},
"name": {
"type": "string",
"maxLength": 128,
"description": "PyPI project name or lowercase npm name, optionally @scope/name. PyPI names normalize runs of dash, underscore and dot to dash."
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "Required exact version: PyPI PEP 440 without local build suffix; npm strict SemVer 2.0. No ranges, tags or dependency trees. Versions are ordered against advisory boundaries, including prereleases."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"ecosystem",
"name",
"version",
"request_id"
]
},
"example": {
"ecosystem": "pypi",
"name": "requests",
"version": "2.19.0",
"request_id": "package-vulnerability-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"ecosystem",
"name",
"version",
"verdict",
"advisories",
"vulnerability_groups",
"withdrawn_advisory_ids",
"observed_at",
"coverage",
"limitations"
],
"properties": {
"status": {
"type": "string",
"const": "ok"
},
"ecosystem": {
"type": "string",
"enum": [
"pypi",
"npm"
]
},
"name": {
"type": "string",
"maxLength": 128
},
"version": {
"type": "string",
"maxLength": 80
},
"verdict": {
"type": "string",
"enum": [
"affected",
"review_required",
"no_known_matches"
]
},
"advisories": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"aliases",
"modified",
"version_status",
"ranges",
"fixed_versions_reported",
"listed_version_match",
"source_url",
"known_exploitation"
],
"properties": {
"id": {
"type": "string",
"maxLength": 160
},
"aliases": {
"type": "array",
"maxItems": 40,
"items": {
"type": "string",
"maxLength": 160
}
},
"modified": {
"type": "string",
"maxLength": 80
},
"version_status": {
"type": "string",
"enum": [
"affected",
"not_affected",
"unknown"
]
},
"ranges": {
"type": "array",
"maxItems": 3000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"events"
],
"properties": {
"type": {
"type": "string",
"maxLength": 32
},
"events": {
"type": "array",
"maxItems": 60,
"items": {
"type": "object",
"minProperties": 1,
"maxProperties": 1,
"additionalProperties": false,
"properties": {
"introduced": {
"type": "string",
"maxLength": 80
},
"fixed": {
"type": "string",
"maxLength": 80
},
"last_affected": {
"type": "string",
"maxLength": 80
},
"limit": {
"type": "string",
"maxLength": 80
}
}
}
}
}
}
},
"fixed_versions_reported": {
"type": "array",
"maxItems": 3000,
"items": {
"type": "string",
"maxLength": 80
}
},
"listed_version_match": {
"type": "boolean",
"description": "Whether the exact requested spelling occurs in a matching source entry version enumeration. Range and enumeration verdicts use ecosystem version equivalence."
},
"source_url": {
"type": "string",
"maxLength": 512
},
"known_exploitation": {
"type": "array",
"maxItems": 41,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"cve",
"date_added",
"due_date",
"ransomware_use"
],
"properties": {
"cve": {
"type": "string",
"maxLength": 160
},
"date_added": {
"type": "string",
"maxLength": 10
},
"due_date": {
"type": "string",
"maxLength": 10
},
"ransomware_use": {
"type": "string",
"maxLength": 32
}
}
}
}
}
}
},
"vulnerability_groups": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"identifiers",
"advisory_ids",
"version_status",
"source_disagreement"
],
"properties": {
"identifiers": {
"type": "array",
"maxItems": 4100,
"items": {
"type": "string",
"maxLength": 160
}
},
"advisory_ids": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 160
}
},
"version_status": {
"type": "string",
"enum": [
"affected",
"not_affected",
"unknown"
]
},
"source_disagreement": {
"type": "boolean"
}
}
}
},
"withdrawn_advisory_ids": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 160
}
},
"observed_at": {
"type": "string",
"maxLength": 80
},
"coverage": {
"type": "object",
"additionalProperties": false,
"required": [
"advisory_records",
"withdrawn_records",
"pages",
"query_complete",
"osv_source",
"kev_source",
"kev_catalog_version",
"kev_released_at",
"kev_count"
],
"properties": {
"advisory_records": {
"type": "integer",
"minimum": 0
},
"withdrawn_records": {
"type": "integer",
"minimum": 0
},
"pages": {
"type": "integer",
"minimum": 1,
"maximum": 4
},
"query_complete": {
"type": "boolean"
},
"osv_source": {
"type": "string",
"maxLength": 512
},
"kev_source": {
"type": "string",
"maxLength": 512
},
"kev_catalog_version": {
"type": "string",
"maxLength": 80
},
"kev_released_at": {
"type": "string",
"maxLength": 80
},
"kev_count": {
"type": "integer",
"minimum": 0
}
}
},
"limitations": {
"type": "array",
"maxItems": 5,
"items": {
"type": "string",
"maxLength": 512
}
}
}
},
"example": {
"status": "ok",
"ecosystem": "pypi",
"name": "requests",
"version": "2.19.0",
"verdict": "affected",
"advisories": [
{
"id": "GHSA-mekl-0000-0001",
"aliases": [
"CVE-2026-99901"
],
"modified": "2026-10-20T00:00:00Z",
"version_status": "affected",
"ranges": [
{
"type": "ECOSYSTEM",
"events": [
{
"introduced": "0"
},
{
"fixed": "2.20.0"
}
]
}
],
"fixed_versions_reported": [
"2.20.0"
],
"listed_version_match": false,
"source_url": "https://osv.dev/vulnerability/GHSA-mekl-0000-0001",
"known_exploitation": [
{
"cve": "CVE-2026-99901",
"date_added": "2026-10-20",
"due_date": "2026-11-10",
"ransomware_use": "Unknown"
}
]
}
],
"vulnerability_groups": [
{
"identifiers": [
"CVE-2026-99901",
"GHSA-mekl-0000-0001"
],
"advisory_ids": [
"GHSA-mekl-0000-0001"
],
"version_status": "affected",
"source_disagreement": false
}
],
"withdrawn_advisory_ids": [],
"observed_at": "2026-10-21T00:00:00Z",
"coverage": {
"advisory_records": 1,
"withdrawn_records": 0,
"pages": 1,
"query_complete": true,
"osv_source": "https://api.osv.dev/v1/query",
"kev_source": "https://raw.githubusercontent.com/cisagov/kev-data/main/known_exploited_vulnerabilities.json",
"kev_catalog_version": "2026.10.20",
"kev_released_at": "2026-10-20T00:00:00Z",
"kev_count": 1
},
"limitations": [
"No known matches means no affected version found in this bounded OSV response; unknown, unpublished, missing or newly changed advisories remain possible.",
"Only the supplied exact package/version is checked. No dependency resolution, code execution, malware scan, registry-existence check or installation-safety guarantee.",
"GitHub and PyPI advisory records are obtained through OSV, not independently corroborated. Aliases group source assertions; disagreements remain visible.",
"Fixed versions are source-reported boundaries, not a recommended upgrade or a guarantee against other vulnerabilities. Prereleases use version ordering, not npm installer range selection.",
"CISA catalog membership is exploitation evidence for the CVE, not proof that this package deployment is exploitable. Absence is not evidence of no exploitation."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.010000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Response Check: Check schema, timestamp freshness and supplied claim evidence
POST /v1/data/responses/check-response-contract
0.05 USDC per completed diagnostic
Service scope, examples and recovery →
Check supplied JSON against a bounded Draft 2020-12 schema, declared timestamp freshness and optional claim evidence. Return separate pass/fail/review findings. Evidence assessment is advisory and uses supplied excerpts only; no external fact verification, source authentication or URL retrieval.
Input fields
request_idRequired · string- Fresh per purchase; preserve for original-proof recovery.
responseRequired · See complete schema- Any supplied JSON value. Whole request at most 20000 serialized UTF-8 bytes, depth 16 and 1200 values. Integer values, including integral exponent notation, are exact up to 1000 digits. Fractional numbers must round-trip unchanged through finite binary64 decimal serialization; unsupported precision, overflow or underflow rejects before payment with unsupported_number_precision. Wire and canonical normalized JSON each have the 20000-byte bound.
schemaOptional · See complete schema- Optional bounded Draft 2020-12 schema. Allowed keywords: $schema, title, description, type, properties, required, additionalProperties, items, enum, const, minimum, maximum, exclusiveMinimum, exclusiveMaximum, minLength, maxLength, minItems, maxItems, minProperties, maxProperties, format. Schema depth at most 8. Formats asserted: date-time, uuid, ipv4, ipv6. No refs, regexes or combinators; other keywords reject before payment. The date-time assertion uses the freshness timestamp profile: uppercase T/Z, seconds, known UTC offset, at most six fractional digits and no leap seconds. At most ten schema errors are returned; error_limit_reached indicates the cap was reached and further errors may exist.
freshnessOptional · object- See the complete request schema for values and bounds.
semanticOptional · array- Optional selected claim checks. One bounded AWS Bedrock model call receives these claim texts and evidence. Other response fields are not sent. Missing evidence is not world knowledge. Serialized selected claim/evidence array is at most 10000 UTF-8 bytes, including repeated claim text; this is checked before payment.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"response"
],
"properties": {
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh per purchase; preserve for original-proof recovery."
},
"response": {
"description": "Any supplied JSON value. Whole request at most 20000 serialized UTF-8 bytes, depth 16 and 1200 values. Integer values, including integral exponent notation, are exact up to 1000 digits. Fractional numbers must round-trip unchanged through finite binary64 decimal serialization; unsupported precision, overflow or underflow rejects before payment with unsupported_number_precision. Wire and canonical normalized JSON each have the 20000-byte bound."
},
"schema": {
"oneOf": [
{
"type": "boolean"
},
{
"type": "object"
}
],
"description": "Optional bounded Draft 2020-12 schema. Allowed keywords: $schema, title, description, type, properties, required, additionalProperties, items, enum, const, minimum, maximum, exclusiveMinimum, exclusiveMaximum, minLength, maxLength, minItems, maxItems, minProperties, maxProperties, format. Schema depth at most 8. Formats asserted: date-time, uuid, ipv4, ipv6. No refs, regexes or combinators; other keywords reject before payment. The date-time assertion uses the freshness timestamp profile: uppercase T/Z, seconds, known UTC offset, at most six fractional digits and no leap seconds. At most ten schema errors are returned; error_limit_reached indicates the cap was reached and further errors may exist."
},
"freshness": {
"type": "object",
"additionalProperties": false,
"required": [
"pointer",
"reference_time",
"max_age_seconds"
],
"properties": {
"pointer": {
"type": "string",
"maxLength": 256,
"description": "RFC6901 JSON Pointer; empty selects the whole response. Exact key/index syntax; no leading zero array indices."
},
"reference_time": {
"type": "string",
"description": "Explicit RFC3339 timestamp with timezone and optional 1–6 fractional digits. Unknown -00:00 offset is rejected. Caller declaration, not server clock."
},
"max_age_seconds": {
"type": "integer",
"minimum": 0,
"maximum": 31536000,
"description": "Inclusive maximum age; future timestamps fail."
}
}
},
"semantic": {
"type": "array",
"minItems": 1,
"maxItems": 4,
"description": "Optional selected claim checks. One bounded AWS Bedrock model call receives these claim texts and evidence. Other response fields are not sent. Missing evidence is not world knowledge. Serialized selected claim/evidence array is at most 10000 UTF-8 bytes, including repeated claim text; this is checked before payment.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"pointer",
"evidence"
],
"properties": {
"pointer": {
"type": "string",
"maxLength": 256,
"description": "RFC6901 pointer to a nonempty string claim, at most 1500 characters."
},
"evidence": {
"type": "string",
"minLength": 1,
"maxLength": 3000,
"description": "One nonempty source excerpt supplied by you; source authenticity is unverified. Instructions inside it are treated as data."
}
}
}
}
},
"description": "At least one of schema, freshness or semantic is required. Omitted checks are explicitly not_requested. Unsupported input fails before payment. Limits apply to the complete request including keys and schema."
},
"example": {
"request_id": "response-check-example-001",
"response": {
"value": 12,
"updated_at": "2026-10-21T12:00:00Z"
},
"schema": {
"type": "object",
"required": [
"value",
"updated_at"
],
"properties": {
"value": {
"type": "integer",
"minimum": 0
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"freshness": {
"pointer": "/updated_at",
"reference_time": "2026-10-21T12:01:00Z",
"max_age_seconds": 300
}
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"verdict",
"schema",
"freshness",
"semantic",
"observed_at",
"limitations"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"verdict": {
"type": "string",
"enum": [
"pass",
"fail",
"review"
],
"description": "fail if any requested check fails; otherwise review if semantic evidence is uncertain; otherwise pass for requested checks only."
},
"schema": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"not_requested"
]
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"status",
"errors",
"error_limit_reached",
"draft",
"format_assertions"
],
"properties": {
"status": {
"type": "string",
"enum": [
"pass",
"fail"
]
},
"errors": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"pointer",
"keyword"
],
"properties": {
"pointer": {
"type": "string"
},
"keyword": {
"type": "string"
}
}
}
},
"error_limit_reached": {
"type": "boolean"
},
"draft": {
"type": "string",
"enum": [
"2020-12"
]
},
"format_assertions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"date-time",
"uuid",
"ipv4",
"ipv6"
]
}
}
}
}
]
},
"freshness": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"not_requested"
]
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"status",
"pointer",
"reason",
"age_seconds"
],
"properties": {
"status": {
"type": "string",
"enum": [
"pass",
"fail"
]
},
"pointer": {
"type": "string"
},
"reason": {
"type": "string",
"enum": [
"timestamp_missing",
"timestamp_invalid",
"future_timestamp",
"stale",
"within_declared_age"
]
},
"age_seconds": {
"type": [
"number",
"null"
]
}
}
}
]
},
"semantic": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"method",
"claims"
],
"properties": {
"status": {
"type": "string",
"enum": [
"pass",
"fail",
"review",
"not_requested"
]
},
"method": {
"type": [
"string",
"null"
]
},
"claims": {
"type": "array",
"maxItems": 4,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"pointer",
"verdict",
"evidence_quote"
],
"properties": {
"pointer": {
"type": "string"
},
"verdict": {
"type": "string",
"enum": [
"supported",
"contradicted",
"uncertain"
]
},
"evidence_quote": {
"type": "string",
"maxLength": 300
}
}
}
}
}
},
"observed_at": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"verdict": "pass",
"schema": {
"status": "pass",
"errors": [],
"error_limit_reached": false,
"draft": "2020-12",
"format_assertions": [
"date-time",
"ipv4",
"ipv6",
"uuid"
]
},
"freshness": {
"status": "pass",
"pointer": "/updated_at",
"reason": "within_declared_age",
"age_seconds": 60.0
},
"semantic": {
"status": "not_requested",
"claims": [],
"method": null
},
"observed_at": "2026-10-21T12:01:00Z",
"limitations": [
"Only the requested contract is checked; pass is not proof of truth, source authenticity or suitability for a consequential decision.",
"Freshness uses caller-supplied timestamps and reference time; a recent timestamp does not authenticate recent source data.",
"Semantic assessment is advisory, uses supplied evidence only and can be wrong. Only caller-selected claims are assessed; other content remains unchecked.",
"No URLs are fetched, instructions executed or external facts independently verified."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.050000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Cron and Timezone Calculation: Calculate up to 20 upcoming five-field cron runs in a named IANA timezone, strictly after an explicit timestamp through a 366-day horizon
POST /v1/data/schedules/calculate-cron-runs
0.005 USDC per accepted request
Service scope, examples and recovery →
Calculate up to 20 upcoming five-field cron runs in a named IANA timezone, strictly after an explicit timestamp through a 366-day horizon. Report UTC, local offset and fold. Skip nonexistent times; choose both, first or second repeated times. Calculation only: no scheduler, job execution or delivery.
Input fields
expressionRequired · string- Five fields minute hour day-of-month month day-of-week. Numeric lists, inclusive ranges, positive steps and English month/weekday abbreviations. Sunday 0 or 7. If both day fields differ from literal *, either may match; otherwise both must match. No seconds/year/macros/L/W/#.
timezoneRequired · string- IANA timezone name available in the deployed runtime, e.g. America/Los_Angeles.
startRequired · string- RFC3339 timestamp with seconds and explicit Z or numeric offset, years 1970 through 2097. No fractional seconds.
countOptional · integer- See the complete request schema for values and bounds.
repeat_policyOptional · string- Policy for repeated local times when clocks go backward. Nonexistent times are always skipped.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"expression": {
"type": "string",
"maxLength": 128,
"description": "Five fields minute hour day-of-month month day-of-week. Numeric lists, inclusive ranges, positive steps and English month/weekday abbreviations. Sunday 0 or 7. If both day fields differ from literal *, either may match; otherwise both must match. No seconds/year/macros/L/W/#."
},
"timezone": {
"type": "string",
"maxLength": 100,
"description": "IANA timezone name available in the deployed runtime, e.g. America/Los_Angeles."
},
"start": {
"type": "string",
"format": "date-time",
"description": "RFC3339 timestamp with seconds and explicit Z or numeric offset, years 1970 through 2097. No fractional seconds."
},
"count": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"default": 5
},
"repeat_policy": {
"type": "string",
"enum": [
"both",
"first",
"second"
],
"default": "both",
"description": "Policy for repeated local times when clocks go backward. Nonexistent times are always skipped."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"expression",
"timezone",
"start",
"request_id"
]
},
"example": {
"expression": "30 9 * * MON-FRI",
"timezone": "America/Los_Angeles",
"start": "2026-10-20T00:00:00Z",
"count": 5,
"repeat_policy": "both",
"request_id": "cron-calculation-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"expression",
"timezone",
"start",
"runs",
"requested_count",
"complete",
"search_end_utc",
"repeat_policy",
"observed_at",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"expression": {
"type": "string"
},
"timezone": {
"type": "string"
},
"start": {
"type": "string"
},
"runs": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"utc",
"local",
"fold"
],
"properties": {
"utc": {
"type": "string"
},
"local": {
"type": "string"
},
"fold": {
"type": "integer"
}
}
}
},
"requested_count": {
"type": "integer"
},
"complete": {
"type": "boolean"
},
"search_end_utc": {
"type": "string"
},
"repeat_policy": {
"type": "string"
},
"observed_at": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"expression": "30 9 * * MON-FRI",
"timezone": "America/Los_Angeles",
"start": "2026-10-20T00:00:00+00:00",
"runs": [
{
"utc": "2026-10-20T16:30:00Z",
"local": "2026-10-20T09:30:00-07:00",
"fold": 0
},
{
"utc": "2026-10-21T16:30:00Z",
"local": "2026-10-21T09:30:00-07:00",
"fold": 0
},
{
"utc": "2026-10-22T16:30:00Z",
"local": "2026-10-22T09:30:00-07:00",
"fold": 0
},
{
"utc": "2026-10-23T16:30:00Z",
"local": "2026-10-23T09:30:00-07:00",
"fold": 0
},
{
"utc": "2026-10-26T16:30:00Z",
"local": "2026-10-26T09:30:00-07:00",
"fold": 0
}
],
"requested_count": 5,
"complete": true,
"search_end_utc": "2027-10-21T00:00:00+00:00",
"repeat_policy": "both",
"observed_at": "2026-10-20T00:00:00Z",
"limitations": [
"Calculation only; no job is scheduled or delivered.",
"Five fields: minute hour day-of-month month day-of-week. Numeric lists, ranges, steps and English month/weekday abbreviations; Sunday is 0 or 7.",
"Day-of-month and day-of-week use OR when both fields differ from the literal *; otherwise both must match. No seconds, year, L, W, # or @ macros.",
"Nonexistent local times are skipped. Repeated times follow repeat_policy. Search is strictly after start through 366 elapsed days.",
"Uses the deployed IANA timezone database; future government rule changes may alter results."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]TLS Certificate Inspection: Inspect a public host on TCP port 443 for certificate expiry, DNS names, fingerprint, runtime CA/hostname validation and negotiated TLS details
POST /v1/web/tls/inspect-certificate
0.005 USDC per accepted request
Service scope, examples and recovery →
Inspect a public host on TCP port 443 for certificate expiry, DNS names, fingerprint, runtime CA/hostname validation and negotiated TLS details. A failed certificate check triggers one unverified diagnostic handshake and remains untrusted. No HTTP scanning, revocation or exhaustive security assessment.
Input fields
hostnameRequired · string- Public DNS hostname only, without scheme, port, path or credentials. Public addresses are resolved and pinned; private/local targets are rejected.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"hostname": {
"type": "string",
"maxLength": 253,
"description": "Public DNS hostname only, without scheme, port, path or credentials. Public addresses are resolved and pinned; private/local targets are rejected."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"hostname",
"request_id"
]
},
"example": {
"hostname": "mekler.ai",
"request_id": "tls-inspection-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"hostname",
"port",
"observed_at",
"verified",
"verification_error_code",
"not_before",
"not_after",
"dns_names",
"sha256",
"tls_version",
"cipher",
"seconds_until_expiry",
"time_valid",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"hostname": {
"type": "string"
},
"port": {
"type": "integer"
},
"observed_at": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"verification_error_code": {
"type": [
"integer",
"null"
]
},
"not_before": {
"type": "string"
},
"not_after": {
"type": "string"
},
"dns_names": {
"type": "array",
"items": {
"type": "string"
}
},
"sha256": {
"type": "string"
},
"tls_version": {
"type": [
"string",
"null"
]
},
"cipher": {
"type": [
"string",
"null"
]
},
"seconds_until_expiry": {
"type": "integer"
},
"time_valid": {
"type": "boolean"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"hostname": "mekler.ai",
"port": 443,
"observed_at": "2026-10-20T00:00:00Z",
"verified": true,
"verification_error_code": null,
"not_before": "2026-10-01T00:00:00+00:00",
"not_after": "2027-01-01T00:00:00+00:00",
"dns_names": [
"mekler.ai"
],
"sha256": "0000000000000000000000000000000000000000000000000000000000000000",
"tls_version": "TLSv1.3",
"cipher": "TLS_AES_256_GCM_SHA384",
"seconds_until_expiry": 6307200,
"time_valid": true,
"limitations": [
"One remote handshake from the deployed service; DNS, certificate and routing can change.",
"verified uses the runtime CA store and hostname validation. Certificate failure triggers one unverified handshake to collect diagnostics; it does not make the certificate trusted.",
"No revocation/OCSP, certificate-transparency, exhaustive protocol/cipher scan or overall security guarantee. Only public DNS hosts on port 443; no HTTP request is sent."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]JSON Repair and Format Conversion: Conservatively repair JSON syntax or convert JSON and safe YAML while recording every repair
POST /v1/data/json/repair-or-convert-document
0.005 USDC per accepted request
Service scope, examples and recovery →
Conservatively repair JSON syntax or convert JSON and safe YAML while recording every repair. Remove only BOM, complete JSON markdown fences and trailing commas outside strings; abstain on ambiguous or unsupported data. Up to 16000 UTF-8 input bytes, depth 24 and 4000 values. No invented values, semantic validation or code execution. Numeric values that cannot be preserved without rounding return explicit abstention.
Input fields
textRequired · string- Document text; additionally limited to 16000 UTF-8 bytes. YAML uses safe YAML 1.1 scalar interpretation, timestamps as strings; no anchors, aliases or explicit tags. Numeric precision must round-trip without decimal-value loss; otherwise the completed diagnostic abstains instead of rounding.
input_formatOptional · string- See the complete request schema for values and bounds.
output_formatOptional · string- See the complete request schema for values and bounds.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 16000,
"description": "Document text; additionally limited to 16000 UTF-8 bytes. YAML uses safe YAML 1.1 scalar interpretation, timestamps as strings; no anchors, aliases or explicit tags. Numeric precision must round-trip without decimal-value loss; otherwise the completed diagnostic abstains instead of rounding."
},
"input_format": {
"type": "string",
"enum": [
"json",
"yaml"
],
"default": "json"
},
"output_format": {
"type": "string",
"enum": [
"json",
"yaml"
],
"default": "json"
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"text",
"request_id"
]
},
"example": {
"text": "{\"service\":\"Mekler\",}",
"input_format": "json",
"output_format": "yaml",
"request_id": "json-conversion-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"outcome",
"input_format",
"output_format",
"output",
"transformations",
"reason",
"observed_at",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"outcome": {
"type": "string"
},
"input_format": {
"type": "string"
},
"output_format": {
"type": "string"
},
"output": {
"type": [
"string",
"null"
]
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"operation",
"offset"
],
"properties": {
"operation": {
"type": "string"
},
"offset": {
"type": "integer"
}
}
}
},
"reason": {
"type": [
"string",
"null"
],
"description": "Null on success; numeric_precision_unsupported means the source numeric value cannot be round-tripped without loss, so output is null and no repair is proposed."
},
"observed_at": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"outcome": "converted",
"input_format": "json",
"output_format": "yaml",
"output": "service: Mekler\n",
"transformations": [
{
"operation": "remove_trailing_comma",
"offset": 19
}
],
"reason": null,
"observed_at": "2026-10-20T00:00:00Z",
"limitations": [
"Only BOM removal, complete JSON markdown fences and trailing commas outside quoted strings are repaired; offsets refer to each transformation stage.",
"No missing values, keys, closing delimiters or quotes are guessed. Duplicate keys, nonfinite numbers and unsupported syntax produce abstention.",
"Numeric values must round-trip through their serialized representation without decimal-value loss; unsupported precision produces abstention instead of rounding.",
"YAML uses safe YAML 1.1 scalar interpretation; timestamps remain strings, aliases/anchors/explicit tags are rejected, and only JSON-compatible string-keyed values are supported.",
"Formatting and comments are not preserved. A completed conversion or abstention diagnostic is charged; no semantic truth or schema validity claim."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Package Identity Checks: Check public PyPI or npm package identity and a requested version
POST /v1/data/packages/check-registry-identity
0.005 USDC per accepted request
Service scope, examples and recovery →
Check public PyPI or npm package identity and a requested version. Compare up to five supplied candidate names for normalized-name equality and bounded edit-distance confusion. Return sourced existence and version evidence without downloading code. No malware, vulnerability, publisher-authenticity or installation-safety guarantee.
Input fields
ecosystemRequired · string- See the complete request schema for values and bounds.
nameRequired · string- PyPI project name or lowercase npm name, optionally @scope/name. PyPI names normalize runs of dash, underscore and dot to dash.
versionOptional · string or null- Optional exact version; omit or null for current registry latest. A missing exact version does not imply absence of the project.
compare_namesOptional · array- Candidate package names to look up and compare. No exhaustive registry search is performed.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"ecosystem": {
"type": "string",
"enum": [
"pypi",
"npm"
]
},
"name": {
"type": "string",
"maxLength": 128,
"description": "PyPI project name or lowercase npm name, optionally @scope/name. PyPI names normalize runs of dash, underscore and dot to dash."
},
"version": {
"type": [
"string",
"null"
],
"maxLength": 80,
"description": "Optional exact version; omit or null for current registry latest. A missing exact version does not imply absence of the project."
},
"compare_names": {
"type": "array",
"maxItems": 5,
"items": {
"type": "string",
"maxLength": 128
},
"default": [],
"description": "Candidate package names to look up and compare. No exhaustive registry search is performed."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"ecosystem",
"name",
"request_id"
]
},
"example": {
"ecosystem": "pypi",
"name": "pip",
"compare_names": [
"pip-tools"
],
"request_id": "package-identity-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"ecosystem",
"identity",
"comparisons",
"observed_at",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"ecosystem": {
"type": "string"
},
"identity": {
"type": "object",
"additionalProperties": false,
"required": [
"exists",
"name",
"version",
"source_url",
"requested_version",
"package_exists",
"version_exists"
],
"properties": {
"exists": {
"type": "boolean"
},
"name": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
]
},
"source_url": {
"type": "string"
},
"requested_version": {
"type": [
"string",
"null"
]
},
"package_exists": {
"type": "boolean"
},
"version_exists": {
"type": [
"boolean",
"null"
]
}
}
},
"comparisons": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"exists",
"name",
"version",
"source_url",
"requested_version",
"package_exists",
"version_exists",
"edit_distance",
"same_normalized_name",
"possible_name_confusion"
],
"properties": {
"exists": {
"type": "boolean"
},
"name": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
]
},
"source_url": {
"type": "string"
},
"requested_version": {
"type": [
"string",
"null"
]
},
"package_exists": {
"type": "boolean"
},
"version_exists": {
"type": [
"boolean",
"null"
]
},
"edit_distance": {
"type": "integer"
},
"same_normalized_name": {
"type": "boolean"
},
"possible_name_confusion": {
"type": "boolean"
}
}
}
},
"observed_at": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"ecosystem": "pypi",
"identity": {
"exists": true,
"name": "pip",
"version": "1.0.0",
"source_url": "https://pypi.org/pypi/pip/json",
"requested_version": null,
"package_exists": true,
"version_exists": null
},
"comparisons": [
{
"exists": true,
"name": "pip-tools",
"version": "1.0.0",
"source_url": "https://pypi.org/pypi/pip-tools/json",
"requested_version": null,
"package_exists": true,
"version_exists": null,
"edit_distance": 6,
"same_normalized_name": false,
"possible_name_confusion": false
}
],
"observed_at": "2026-10-20T00:00:00Z",
"limitations": [
"Public PyPI and npm registry lookup at observation time; no package is downloaded or executed.",
"Existence is not authenticity, security, vulnerability clearance or a recommendation to install. A missing requested version does not establish that the package name is absent.",
"Name-confusion evidence compares only the supplied maximum five candidates using normalized names and Levenshtein distance <= 2; it is not an exhaustive typosquat search.",
"Registry maintainer identities, emails and package descriptions are excluded. Deleted, transferred or newly published packages may change after this observation."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Feed Inspection and Normalization: Inspect a public RSS, Atom or JSON feed and return a verified record mapping, normalized preview, ID provenance, duplicate evidence and field coverage
POST /v1/data/feeds/inspect-record-mapping
0.005 USDC per accepted request
Service scope, examples and recovery →
Inspect a public RSS, Atom or JSON feed and return a verified record mapping, normalized preview, ID provenance, duplicate evidence and field coverage. One uncompressed UTF-8 document up to 256 KiB; maximum 100 returned records. No pagination, complete history, JavaScript rendering or safe-link guarantee.
Input fields
urlRequired · string- Public HTTP(S) URL on standard port 80/443; no credentials/private addresses. Robots restrictions and DNS-pinned public-address checks apply.
records_pathOptional · string or null- Optional JSON Pointer to a record array; omit to infer one of items, entries, results or data, or a root array. XML does not accept this field.
max_recordsOptional · integer- See the complete request schema for values and bounds.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"description": "Public HTTP(S) URL on standard port 80/443; no credentials/private addresses. Robots restrictions and DNS-pinned public-address checks apply."
},
"records_path": {
"type": [
"string",
"null"
],
"maxLength": 128,
"description": "Optional JSON Pointer to a record array; omit to infer one of items, entries, results or data, or a root array. XML does not accept this field."
},
"max_records": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"url",
"request_id"
]
},
"example": {
"url": "https://mekler.ai/check/changes.xml",
"max_records": 20,
"request_id": "feed-inspection-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"source_url",
"format",
"records_path",
"mapping",
"records",
"observed_at",
"coverage",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"source_url": {
"type": "string"
},
"format": {
"type": "string"
},
"records_path": {
"type": "string"
},
"mapping": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"url",
"published"
],
"properties": {
"id": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
]
},
"published": {
"type": [
"string",
"null"
]
}
}
},
"records": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"id_basis",
"title",
"url",
"published"
],
"properties": {
"id": {
"type": "string"
},
"id_basis": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
]
},
"published": {
"type": [
"string",
"null"
]
}
}
}
},
"observed_at": {
"type": "string"
},
"coverage": {
"type": "object",
"additionalProperties": false,
"required": [
"source_records",
"returned_records",
"truncated",
"duplicate_ids_in_returned",
"source_id_records",
"field_counts"
],
"properties": {
"source_records": {
"type": "integer"
},
"returned_records": {
"type": "integer"
},
"truncated": {
"type": "boolean"
},
"duplicate_ids_in_returned": {
"type": "integer"
},
"source_id_records": {
"type": "integer"
},
"field_counts": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"url",
"published"
],
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "integer"
},
"url": {
"type": "integer"
},
"published": {
"type": "integer"
}
}
}
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"source_url": "https://mekler.ai/check/changes.xml",
"format": "rss",
"records_path": "/rss/channel/item",
"mapping": {
"id": "guid",
"title": "title",
"url": "link",
"published": "pubDate"
},
"records": [
{
"id": "mekler-example-1",
"id_basis": "source_id",
"title": "Mekler feed example",
"url": "https://mekler.ai/",
"published": "Tue, 20 Oct 2026 00:00:00 GMT"
}
],
"observed_at": "2026-10-20T00:00:00Z",
"coverage": {
"source_records": 1,
"returned_records": 1,
"truncated": false,
"duplicate_ids_in_returned": 0,
"source_id_records": 1,
"field_counts": {
"id": 1,
"title": 1,
"url": 1,
"published": 1
}
},
"limitations": [
"One uncompressed UTF-8 RSS 2.0, Atom 1.0 or JSON document up to 256 KiB; previews also stop at 40000 serialized UTF-8 bytes. No JavaScript, authentication, pagination or complete-history claim.",
"JSON mapping chooses the first recognized field in documented precedence; inspect mapping and field_counts. Optional records_path is a JSON Pointer to the record array.",
"Source IDs are retained; URL hashes are stable while URLs persist; content hashes change when content changes. Duplicates remain visible.",
"Dates are source strings, not verified event times. Links are normalized but not fetched or proven safe. Descriptions, markup and enclosures are not included."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Search academic papers with deduplicated identifiers and provenance
POST /v1/research/papers/find-research-papers
0.01 USDC per accepted request
Service scope, examples and recovery →
Academic paper search by topic or seed DOI/OpenAlex ID. Return ranked publication metadata with identifiers, source provenance, conservative duplicate/version grouping and reported retraction flags from OpenAlex and Crossref. Filter by publication year; retrieve up to 20 results. No abstracts, full text, author identities, exhaustive literature review or quality/retraction clearance.
Input fields
queryOptional · string- Topic keywords; plaintext, no control characters.
seedOptional · string- DOI, https://doi.org DOI URL, OpenAlex W ID or https://openalex.org/W ID. Resolved only at fixed API hosts.
limitOptional · integer- See the complete request schema for values and bounds.
from_yearOptional · integer- See the complete request schema for values and bounds.
to_yearOptional · integer- See the complete request schema for values and bounds.
include_retractedOptional · boolean- See the complete request schema for values and bounds.
request_idRequired · string- Fresh per new search. Preserve for identical-body/original-proof recovery.
Response status
200- Completed metadata search, including zero results. PAYMENT-RESPONSE confirms settlement; results recover for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id"
],
"oneOf": [
{
"required": [
"query"
],
"not": {
"required": [
"seed"
]
}
},
{
"required": [
"seed"
],
"not": {
"required": [
"query"
]
}
}
],
"properties": {
"query": {
"type": "string",
"minLength": 3,
"maxLength": 240,
"description": "Topic keywords; plaintext, no control characters."
},
"seed": {
"type": "string",
"maxLength": 280,
"description": "DOI, https://doi.org DOI URL, OpenAlex W ID or https://openalex.org/W ID. Resolved only at fixed API hosts."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"default": 10
},
"from_year": {
"type": "integer",
"minimum": 1600,
"maximum": 2100
},
"to_year": {
"type": "integer",
"minimum": 1600,
"maximum": 2100
},
"include_retracted": {
"type": "boolean",
"default": false
},
"request_id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{16,64}$",
"description": "Fresh per new search. Preserve for identical-body/original-proof recovery."
}
}
},
"example": {
"query": "graph neural networks",
"limit": 5,
"request_id": "paper-search-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed metadata search, including zero results. PAYMENT-RESPONSE confirms settlement; results recover for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"retrieved_at",
"mode",
"results",
"returned",
"coverage",
"ranking",
"cost",
"warnings"
],
"properties": {
"status": {
"type": "string"
},
"retrieved_at": {
"type": "string"
},
"mode": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"doi",
"openalex_id",
"title",
"year",
"type",
"venue",
"url",
"retraction_status",
"is_retraction_notice",
"sources",
"versions",
"source_records"
],
"properties": {
"id": {
"type": "string"
},
"doi": {
"type": [
"string",
"null"
]
},
"openalex_id": {
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"year": {
"type": [
"integer",
"null"
]
},
"type": {
"type": "string"
},
"venue": {
"type": [
"string",
"null"
]
},
"url": {
"type": "string"
},
"retraction_status": {
"type": "string",
"enum": [
"reported_retracted",
"not_reported",
"unknown"
]
},
"is_retraction_notice": {
"type": "boolean"
},
"sources": {
"type": "array",
"items": {
"type": "string"
}
},
"versions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"relation",
"doi",
"source"
],
"properties": {
"relation": {
"type": "string",
"enum": [
"is-preprint-of",
"has-preprint",
"is-version-of",
"has-version"
]
},
"doi": {
"type": "string"
},
"source": {
"const": "crossref"
}
}
}
},
"source_records": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"id",
"rank"
],
"properties": {
"source": {
"type": "string"
},
"id": {
"type": "string"
},
"rank": {
"type": "integer"
}
}
}
}
}
}
},
"returned": {
"type": "integer"
},
"coverage": {
"type": "object",
"additionalProperties": false,
"required": [
"openalex_records",
"crossref_records",
"normalized_records",
"duplicate_or_version_records_merged",
"retracted_groups_excluded",
"complete_source_requests"
],
"properties": {
"openalex_records": {
"type": "integer"
},
"crossref_records": {
"type": "integer"
},
"normalized_records": {
"type": "integer"
},
"duplicate_or_version_records_merged": {
"type": "integer"
},
"retracted_groups_excluded": {
"type": "integer"
},
"complete_source_requests": {
"type": "boolean"
}
}
},
"ranking": {
"type": "string"
},
"cost": {
"type": "object",
"additionalProperties": false,
"required": [
"source_attempts",
"openalex_list_price_usd",
"charged_supplier_usd",
"supplier_access",
"hosting_cost_usd"
],
"properties": {
"source_attempts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"operation",
"list_price_usd",
"state",
"elapsed_ms"
],
"properties": {
"source": {
"type": "string"
},
"operation": {
"type": "string"
},
"list_price_usd": {
"type": "number"
},
"state": {
"type": "string"
},
"elapsed_ms": {
"type": "number"
}
}
}
},
"openalex_list_price_usd": {
"type": "number"
},
"charged_supplier_usd": {
"type": "integer"
},
"supplier_access": {
"type": "string"
},
"hosting_cost_usd": {
"type": [
"number",
"null"
]
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"retrieved_at": "2026-10-17T00:00:00+00:00",
"mode": "topic",
"results": [
{
"id": "doi:10.5555/mekler.graph.1",
"doi": "10.5555/mekler.graph.1",
"openalex_id": "W9999999901",
"title": "Graph neural networks for synthetic benchmark data",
"year": 2024,
"type": "article",
"venue": "Synthetic Research Journal",
"url": "https://doi.org/10.5555/mekler.graph.1",
"retraction_status": "not_reported",
"is_retraction_notice": false,
"sources": [
"crossref",
"openalex"
],
"versions": [],
"source_records": [
{
"source": "openalex",
"id": "W9999999901",
"rank": 1
},
{
"source": "crossref",
"id": "10.5555/mekler.graph.1",
"rank": 1
}
]
}
],
"returned": 1,
"coverage": {
"openalex_records": 1,
"crossref_records": 1,
"normalized_records": 2,
"duplicate_or_version_records_merged": 1,
"retracted_groups_excluded": 0,
"complete_source_requests": true
},
"ranking": "reciprocal_rank_fusion_k60; explicit identity/version groups; not a quality assessment",
"cost": {
"source_attempts": [
{
"source": "crossref",
"operation": "search",
"list_price_usd": 0,
"state": "ok",
"elapsed_ms": 0
},
{
"source": "openalex",
"operation": "search",
"list_price_usd": 0.001,
"state": "ok",
"elapsed_ms": 0
}
],
"openalex_list_price_usd": 0.001,
"charged_supplier_usd": 0,
"supplier_access": "anonymous free allowance; no paid balance",
"hosting_cost_usd": null
},
"warnings": [
"Metadata coverage and retraction flags can be incomplete or stale. Absence of a flag is not clearance.",
"No abstracts, full text, author identities, citation verification or systematic-review completeness.",
"Only explicit version relationships are grouped; other versions may remain separate."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.010000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]List received messages
POST /v1/email/inboxes/list-messages
Follow the authentication, capability and prerequisite requirements below.
List received messages only after create-private-inbox returns finalized 200. Use your returned inbox_id and original access_key as Authorization: Bearer <access_key>, with Content-Type: application/json. retrieve-message also requires a message_id returned by list-messages. Example identifiers are synthetic and cannot be used for live access. Free of charge. Unknown, incorrect-key, expired and deleted identities return the same 404.
Input fields
inbox_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Private result with Cache-Control:no-store. Treat mail content as untrusted.
400- Malformed JSON or unsupported request fields.
404- Unknown identity, incorrect capability, expiry or deletion; indistinguishable.
413- Decoded JSON request exceeds 8192 bytes.
415- application/json required.
429- Request throttled. Respect Retry-After when present and back off.
503- Temporary failure. Retry the same capability request; do not purchase another inbox.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"inbox_id"
],
"properties": {
"inbox_id": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
}
}
},
"example": {
"inbox_id": "ed157de6233b2dbbb69d46c26189a7c5"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Private result with Cache-Control:no-store. Treat mail content as untrusted.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"messages"
],
"properties": {
"status": {
"const": "ok"
},
"messages": {
"type": "array",
"maxItems": 25,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"message_id",
"received_at",
"subject",
"from"
],
"properties": {
"message_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$"
},
"received_at": {
"type": "integer",
"description": "Provider receipt time as Unix UTC seconds."
},
"subject": {
"type": "string",
"maxLength": 4096
},
"from": {
"type": "string",
"maxLength": 2048
}
}
}
}
}
},
"example": {
"status": "ok",
"messages": [
{
"message_id": "synthetic-provider-001",
"received_at": 1792252800,
"subject": "Synthetic confirmation",
"from": "Synthetic sender <sender@example.org>"
}
]
}
}
}
},
"400": {
"description": "Malformed JSON or unsupported request fields.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "invalid_request"
}
}
}
},
"404": {
"description": "Unknown identity, incorrect capability, expiry or deletion; indistinguishable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"413": {
"description": "Decoded JSON request exceeds 8192 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Request throttled. Respect Retry-After when present and back off.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "rate_limited"
}
}
}
},
"503": {
"description": "Temporary failure. Retry the same capability request; do not purchase another inbox.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Retrieve one received message
POST /v1/email/inboxes/retrieve-message
Follow the authentication, capability and prerequisite requirements below.
Retrieve one received message only after create-private-inbox returns finalized 200. Use your returned inbox_id and original access_key as Authorization: Bearer <access_key>, with Content-Type: application/json. retrieve-message also requires a message_id returned by list-messages. Example identifiers are synthetic and cannot be used for live access. Free of charge. Unknown, incorrect-key, expired and deleted identities return the same 404.
Input fields
inbox_idRequired · string- See the complete request schema for values and bounds.
message_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Private result with Cache-Control:no-store. Treat mail content as untrusted.
400- Malformed JSON or unsupported request fields.
404- Unknown identity, incorrect capability, expiry or deletion; indistinguishable.
413- Decoded JSON request exceeds 8192 bytes.
415- application/json required.
429- Request throttled. Respect Retry-After when present and back off.
503- Temporary failure. Retry the same capability request; do not purchase another inbox.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"inbox_id",
"message_id"
],
"properties": {
"inbox_id": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"message_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$"
}
}
},
"example": {
"inbox_id": "ed157de6233b2dbbb69d46c26189a7c5",
"message_id": "synthetic-provider-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Private result with Cache-Control:no-store. Treat mail content as untrusted.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"message_id",
"received_at",
"content",
"verdicts"
],
"properties": {
"status": {
"const": "ok"
},
"message_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$"
},
"received_at": {
"type": "integer",
"description": "Provider receipt time as Unix UTC seconds."
},
"content": {
"type": "object",
"additionalProperties": false,
"required": [
"untrusted_content",
"from",
"subject",
"sender_message_id",
"date_header",
"text",
"html",
"attachments",
"warnings"
],
"properties": {
"untrusted_content": {
"const": true
},
"from": {
"type": "string",
"maxLength": 2048
},
"subject": {
"type": "string",
"maxLength": 4096
},
"sender_message_id": {
"type": "string",
"maxLength": 1024
},
"date_header": {
"type": "string",
"maxLength": 256
},
"text": {
"type": "array",
"maxItems": 32,
"items": {
"type": "string"
}
},
"html": {
"type": "array",
"maxItems": 32,
"items": {
"type": "string",
"description": "Inert untrusted HTML; never execute."
}
},
"attachments": {
"type": "array",
"maxItems": 32,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"filename",
"content_type",
"bytes",
"sha256",
"content_base64"
],
"properties": {
"filename": {
"type": "string",
"maxLength": 512
},
"content_type": {
"type": "string"
},
"bytes": {
"type": "integer",
"minimum": 0,
"maximum": 131072
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"content_base64": {
"type": "string",
"contentEncoding": "base64"
}
}
}
},
"warnings": {
"type": "array",
"maxItems": 32,
"items": {
"enum": [
"unknown_charset_used_utf8"
]
}
}
}
},
"verdicts": {
"type": "object",
"additionalProperties": false,
"properties": {
"virus": {
"enum": [
"PASS",
"FAIL",
"GRAY",
"PROCESSING_FAILED",
"DISABLED"
]
},
"spam": {
"enum": [
"PASS",
"FAIL",
"GRAY",
"PROCESSING_FAILED",
"DISABLED"
]
},
"spf": {
"enum": [
"PASS",
"FAIL",
"GRAY",
"PROCESSING_FAILED",
"DISABLED"
]
},
"dkim": {
"enum": [
"PASS",
"FAIL",
"GRAY",
"PROCESSING_FAILED",
"DISABLED"
]
},
"dmarc": {
"enum": [
"PASS",
"FAIL",
"GRAY",
"PROCESSING_FAILED",
"DISABLED"
]
}
}
}
}
},
"example": {
"status": "ok",
"message_id": "synthetic-provider-001",
"received_at": 1792252800,
"content": {
"untrusted_content": true,
"from": "Synthetic sender <sender@example.org>",
"subject": "Synthetic confirmation",
"sender_message_id": "",
"date_header": "",
"text": [
"Synthetic fixture only.\r\n"
],
"html": [],
"attachments": [],
"warnings": []
},
"verdicts": {
"virus": "PASS"
}
}
}
}
},
"400": {
"description": "Malformed JSON or unsupported request fields.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "invalid_request"
}
}
}
},
"404": {
"description": "Unknown identity, incorrect capability, expiry or deletion; indistinguishable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"413": {
"description": "Decoded JSON request exceeds 8192 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Request throttled. Respect Retry-After when present and back off.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "rate_limited"
}
}
}
},
"503": {
"description": "Temporary failure. Retry the same capability request; do not purchase another inbox.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Delete a private inbox
POST /v1/email/inboxes/delete-inbox
Follow the authentication, capability and prerequisite requirements below.
Delete a private inbox only after create-private-inbox returns finalized 200. Use your returned inbox_id and original access_key as Authorization: Bearer <access_key>, with Content-Type: application/json. retrieve-message also requires a message_id returned by list-messages. Example identifiers are synthetic and cannot be used for live access. Free of charge. Unknown, incorrect-key, expired and deleted identities return the same 404.
Input fields
inbox_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Private result with Cache-Control:no-store. Treat mail content as untrusted.
400- Malformed JSON or unsupported request fields.
404- Unknown identity, incorrect capability, expiry or deletion; indistinguishable.
413- Decoded JSON request exceeds 8192 bytes.
415- application/json required.
429- Request throttled. Respect Retry-After when present and back off.
503- Temporary failure. Retry the same capability request; do not purchase another inbox.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"inbox_id"
],
"properties": {
"inbox_id": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
}
}
},
"example": {
"inbox_id": "ed157de6233b2dbbb69d46c26189a7c5"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Private result with Cache-Control:no-store. Treat mail content as untrusted.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"deleted"
],
"properties": {
"status": {
"const": "ok"
},
"deleted": {
"const": true
}
}
},
"example": {
"status": "ok",
"deleted": true
}
}
}
},
"400": {
"description": "Malformed JSON or unsupported request fields.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "invalid_request"
}
}
}
},
"404": {
"description": "Unknown identity, incorrect capability, expiry or deletion; indistinguishable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"413": {
"description": "Decoded JSON request exceeds 8192 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Request throttled. Respect Retry-After when present and back off.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "rate_limited"
}
}
}
},
"503": {
"description": "Temporary failure. Retry the same capability request; do not purchase another inbox.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"retry": {
"type": "string"
},
"guidance": {
"type": "object"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Find topic news and incremental headline briefings
POST /v1/research/news/find-topic-news
0.01 USDC per completed news search
Service scope, examples and recovery →
Find recent topic news or poll for new-to-agent links using a bounded follow-up checkpoint and seen history. Return normalized links, exact-link/headline deduplication and optional source-linked headline highlights from a 7-day GDELT headline index. Monitoring dates are not verified publication dates. 0.01 USDC per completed search, including no new links; source failures are uncharged.
Input fields
queryRequired · string- Plain topic words, at most 12 words. Upstream operators and URLs are unsupported.
matchOptional · string- See the complete request schema for values and bounds.
daysOptional · integer- Rolling UTC search window. Mutually exclusive with explicit dates.
start_dateOptional · string- UTC monitoring date, inclusive; must be paired with end_date and within the last 7 dates.
end_dateOptional · string- UTC monitoring date, inclusive, not future. Range at most 7 dates.
limitOptional · integer- See the complete request schema for values and bounds.
sortOptional · string- See the complete request schema for values and bounds.
languageOptional · string- See the complete request schema for values and bounds.
include_summaryOptional · boolean- Include at most 5 source-linked headline highlights; no full-text reading or generated claims.
sinceOptional · string- UTC follow-up checkpoint within the last 7 days, never future. Incompatible with explicit dates. Includes a45-minute overlap for delayed indexing; does not assert publication time.
seenOptional · array- Bounded previously returned URL/headline markers. Suppress matching URLs and exact normalized headlines; use monitoring.next_request to continue.
Response status
200- Completed bounded news search, including valid zero matches. PAYMENT-RESPONSE reports settlement. Observe limitations and monitoring timestamps.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid topic, unsupported upstream operator or invalid bounds; uncharged.
402- Input-bound x402 quote. Sign one offer and resend the identical JSON.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 4096 bytes.
415- application/json required.
503- Source throttled, unavailable, malformed or deadline/storage failure. Work failures before settlement are uncharged; preserve the original proof after uncertain payment.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"query": {
"type": "string",
"maxLength": 160,
"minLength": 3,
"pattern": "^[\\w\\s.,'’\\-]+$",
"description": "Plain topic words, at most 12 words. Upstream operators and URLs are unsupported."
},
"match": {
"type": "string",
"maxLength": 6,
"enum": [
"all",
"any",
"phrase"
],
"default": "all"
},
"days": {
"type": "integer",
"minimum": 1,
"maximum": 7,
"default": 7,
"description": "Rolling UTC search window. Mutually exclusive with explicit dates."
},
"start_date": {
"type": "string",
"maxLength": 10,
"format": "date",
"description": "UTC monitoring date, inclusive; must be paired with end_date and within the last 7 dates."
},
"end_date": {
"type": "string",
"maxLength": 10,
"format": "date",
"description": "UTC monitoring date, inclusive, not future. Range at most 7 dates."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 30,
"default": 10
},
"sort": {
"type": "string",
"maxLength": 9,
"enum": [
"newest",
"relevance"
],
"default": "newest"
},
"language": {
"type": "string",
"maxLength": 7,
"enum": [
"english",
"any"
],
"default": "english"
},
"include_summary": {
"type": "boolean",
"default": false,
"description": "Include at most 5 source-linked headline highlights; no full-text reading or generated claims."
},
"since": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
"description": "UTC follow-up checkpoint within the last 7 days, never future. Incompatible with explicit dates. Includes a45-minute overlap for delayed indexing; does not assert publication time."
},
"seen": {
"type": "array",
"maxItems": 32,
"uniqueItems": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"headline_id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^article-[0-9a-f]{16}$"
},
"headline_id": {
"type": "string",
"pattern": "^headline-[0-9a-f]{16}$"
}
}
},
"description": "Bounded previously returned URL/headline markers. Suppress matching URLs and exact normalized headlines; use monitoring.next_request to continue."
}
},
"required": [
"query"
],
"oneOf": [
{
"required": [
"start_date",
"end_date"
],
"not": {
"required": [
"days"
]
}
},
{
"not": {
"anyOf": [
{
"required": [
"start_date"
]
},
{
"required": [
"end_date"
]
}
]
}
}
]
},
"example": {
"query": "renewable energy",
"include_summary": true,
"limit": 1
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded news search, including valid zero matches. PAYMENT-RESPONSE reports settlement. Observe limitations and monitoring timestamps.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"maxLength": 2,
"enum": [
"ok"
]
},
"query": {
"type": "string",
"maxLength": 160
},
"retrieved_at": {
"type": "string",
"maxLength": 20,
"format": "date-time"
},
"window": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "string",
"maxLength": 20,
"format": "date-time"
},
"end": {
"type": "string",
"maxLength": 20,
"format": "date-time"
},
"date_basis": {
"type": "string",
"maxLength": 17,
"enum": [
"gdelt_observed_at"
]
}
},
"required": [
"start",
"end",
"date_basis"
]
},
"articles": {
"type": "array",
"maxItems": 30,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"maxLength": 24
},
"title": {
"type": "string",
"maxLength": 1000
},
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"source_domain": {
"type": "string",
"maxLength": 253
},
"language": {
"type": "string",
"maxLength": 80
},
"source_country": {
"type": "string",
"maxLength": 80
},
"observed_at": {
"type": "string",
"maxLength": 20,
"format": "date-time"
},
"published_at": {
"type": "string",
"nullable": true,
"description": "Always null: publisher publication date is not verified."
},
"duplicate_count": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"headline_id": {
"type": "string",
"pattern": "^headline-[0-9a-f]{16}$"
}
},
"required": [
"id",
"title",
"url",
"source_domain",
"language",
"source_country",
"observed_at",
"published_at",
"duplicate_count",
"headline_id"
]
}
},
"summary": {
"type": "object",
"additionalProperties": false,
"properties": {
"basis": {
"type": "string",
"maxLength": 14,
"enum": [
"headlines_only"
]
},
"highlights": {
"type": "array",
"maxItems": 5,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 1000
},
"article_ids": {
"type": "array",
"maxItems": 1,
"items": {
"type": "string",
"maxLength": 24
}
}
},
"required": [
"text",
"article_ids"
]
}
}
},
"required": [
"basis",
"highlights"
],
"nullable": true
},
"coverage": {
"type": "object",
"additionalProperties": false,
"properties": {
"source": {
"type": "string",
"maxLength": 20,
"enum": [
"GDELT headline index"
]
},
"source_rows": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"returned": {
"type": "integer",
"minimum": 0,
"maximum": 30
},
"duplicates_removed": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"discarded_rows": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"source_limit": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"possibly_truncated": {
"type": "boolean"
},
"result_byte_limited": {
"type": "boolean"
},
"previously_seen_removed": {
"type": "integer",
"minimum": 0
}
},
"required": [
"source",
"source_rows",
"returned",
"duplicates_removed",
"discarded_rows",
"source_limit",
"possibly_truncated",
"result_byte_limited",
"previously_seen_removed"
]
},
"attribution": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 30
},
"url": {
"type": "string",
"maxLength": 60,
"format": "uri"
}
},
"required": [
"name",
"url"
]
},
"limitations": {
"type": "array",
"maxItems": 5,
"items": {
"type": "string",
"maxLength": 200
}
},
"monitoring": {
"type": "object",
"additionalProperties": false,
"required": [
"state",
"overlap_seconds",
"history_limited",
"next_request"
],
"properties": {
"state": {
"type": "string",
"enum": [
"initial",
"no_matches",
"updates",
"no_new_links"
]
},
"overlap_seconds": {
"type": "integer",
"enum": [
2700
]
},
"history_limited": {
"type": "boolean",
"description": "The returned follow-up dropped older history to fit its bounded request. Older items may repeat."
},
"next_request": {
"type": "object",
"additionalProperties": false,
"properties": {
"query": {
"type": "string",
"maxLength": 160,
"minLength": 3,
"pattern": "^[\\w\\s.,'’\\-]+$",
"description": "Plain topic words, at most 12 words. Upstream operators and URLs are unsupported."
},
"match": {
"type": "string",
"maxLength": 6,
"enum": [
"all",
"any",
"phrase"
],
"default": "all"
},
"days": {
"type": "integer",
"minimum": 1,
"maximum": 7,
"default": 7,
"description": "Rolling UTC search window. Mutually exclusive with explicit dates."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 30,
"default": 10
},
"sort": {
"type": "string",
"maxLength": 9,
"enum": [
"newest",
"relevance"
],
"default": "newest"
},
"language": {
"type": "string",
"maxLength": 7,
"enum": [
"english",
"any"
],
"default": "english"
},
"include_summary": {
"type": "boolean",
"default": false,
"description": "Include at most 5 source-linked headline highlights; no full-text reading or generated claims."
},
"since": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
"description": "UTC follow-up checkpoint within the last 7 days, never future. Incompatible with explicit dates. Includes a45-minute overlap for delayed indexing; does not assert publication time."
},
"seen": {
"type": "array",
"maxItems": 32,
"uniqueItems": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"headline_id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^article-[0-9a-f]{16}$"
},
"headline_id": {
"type": "string",
"pattern": "^headline-[0-9a-f]{16}$"
}
}
},
"description": "Bounded previously returned URL/headline markers. Suppress matching URLs and exact normalized headlines; use monitoring.next_request to continue."
}
},
"required": [
"query",
"match",
"days",
"limit",
"sort",
"language",
"include_summary",
"since",
"seen"
],
"nullable": true
}
}
}
},
"required": [
"status",
"query",
"retrieved_at",
"window",
"articles",
"summary",
"coverage",
"attribution",
"limitations",
"monitoring"
]
},
"example": {
"status": "ok",
"query": "renewable energy",
"retrieved_at": "2026-10-12T12:00:00Z",
"window": {
"start": "2026-10-05T12:00:00Z",
"end": "2026-10-12T12:00:00Z",
"date_basis": "gdelt_observed_at"
},
"articles": [
{
"id": "article-10e46334083ac0e3",
"headline_id": "headline-9d12a0a05f5e0338",
"title": "Renewable energy storage pilot opens",
"url": "https://news.example.org/energy",
"source_domain": "news.example.org",
"language": "English",
"source_country": "",
"observed_at": "2026-10-11T12:00:00Z",
"published_at": null,
"duplicate_count": 1
}
],
"summary": {
"basis": "headlines_only",
"highlights": [
{
"text": "Renewable energy storage pilot opens",
"article_ids": [
"article-10e46334083ac0e3"
]
}
]
},
"coverage": {
"source": "GDELT headline index",
"source_rows": 3,
"returned": 1,
"duplicates_removed": 1,
"discarded_rows": 0,
"source_limit": 150,
"previously_seen_removed": 0,
"possibly_truncated": false,
"result_byte_limited": false
},
"attribution": {
"name": "The GDELT Project",
"url": "https://www.gdeltproject.org/"
},
"limitations": [
"Dates are GDELT monitoring times, not verified publication or first-ever observation times.",
"Results are a bounded source sample, not exhaustive news coverage or verified facts.",
"Links remove known tracking fields; publisher canonical URLs and reachability are unverified.",
"Search matches native-language headlines only. Highlights quote them; articles are not read.",
"Updates use a45-minute overlap and bounded32-entry history; busy topics can omit coverage or repeat older items."
],
"monitoring": {
"state": "initial",
"overlap_seconds": 2700,
"history_limited": false,
"next_request": {
"query": "renewable energy",
"match": "all",
"days": 7,
"limit": 1,
"sort": "newest",
"language": "english",
"include_summary": true,
"since": "2026-10-12T12:00:00Z",
"seen": [
{
"id": "article-10e46334083ac0e3",
"headline_id": "headline-9d12a0a05f5e0338"
}
]
}
}
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid topic, unsupported upstream operator or invalid bounds; uncharged.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"maxLength": 128
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "Input-bound x402 quote. Sign one offer and resend the identical JSON.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"maxLength": 128
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.010000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"maxLength": 128
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 4096 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"maxLength": 128
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"maxLength": 128
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Source throttled, unavailable, malformed or deadline/storage failure. Work failures before settlement are uncharged; preserve the original proof after uncertain payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"maxLength": 128
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Validate CSV before import: get pass/fail and row/column errors for missing values, duplicates, types and bounds.
POST /v1/data/csv/validate-data
0.05 USDC per accepted request
Service scope, examples and recovery →
Validate CSV before import using a fixed JSON column specification. Checks missing/extra columns, required cells, string/integer/decimal/boolean/date types, uniqueness, allowed values and numeric/row-count bounds. Returns pass/fail with row/column error codes. POST JSON with csv and spec.columns; schemas/examples attached. Full contract: /openapi.json. Max 2,000 rows, 50 columns, 256 KiB; first 50 failures. No formulas, cross-column rules, fact checking or data repair.
Input fields
csvRequired · string- UTF-8 comma-delimited CSV with header. No trimming. Data record numbers start at 1; quoted newlines are one record.
specRequired · object- See the complete request schema for values and bounds.
Response status
200- Service result. Inspect X-Mekler-Payment-State: finalized includes PAYMENT-RESPONSE; provisional includes a purchase ID without a settlement receipt.
400- Malformed input or unsupported criterion; no acceptance verdict
413- Request exceeds 256 KiB
415- Requires application/json
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
402- Payment required; PAYMENT-REQUIRED header contains the server-authored USDC quote.
202- Settlement outcome pending; retry identical request and signed proof, never create a second payment.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
503- Payment service temporarily unavailable; do not create a second payment after an ambiguous response.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"csv",
"spec"
],
"properties": {
"csv": {
"type": "string",
"description": "UTF-8 comma-delimited CSV with header. No trimming. Data record numbers start at 1; quoted newlines are one record."
},
"spec": {
"type": "object",
"additionalProperties": false,
"required": [
"columns"
],
"properties": {
"columns": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"type": {
"type": "string",
"enum": [
"string",
"integer",
"decimal",
"boolean",
"date"
],
"description": "string: literal text; integer: base-10, no plus sign or leading zeros; decimal: plain decimal, no exponent; boolean: lowercase true/false; date: valid YYYY-MM-DD."
},
"required": {
"type": "boolean",
"default": false,
"description": "Reject empty cells. Whitespace is not trimmed."
},
"unique": {
"type": "boolean",
"default": false,
"description": "Reject repeated nonempty values within this column; numeric values compare numerically."
},
"min": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Inclusive numeric bound; allowed only for integer or decimal columns."
},
"max": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Inclusive numeric bound; allowed only for integer or decimal columns."
},
"enum": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
},
"description": "Exact allowed cell strings, compared without trimming or normalization."
}
}
},
"description": "Fixed built-in checks. Every named column must exist, even when required is false."
},
"min_rows": {
"type": "integer",
"minimum": 0,
"maximum": 2000,
"default": 0
},
"max_rows": {
"type": "integer",
"minimum": 0,
"maximum": 2000,
"default": 2000
},
"allow_extra_columns": {
"type": "boolean",
"default": false,
"description": "If false, reject CSV headers not named in columns."
}
}
}
}
},
"example": {
"csv": "id,amount\na,12.50\na,-2.00\n",
"spec": {
"columns": [
{
"name": "id",
"type": "string",
"required": true,
"unique": true
},
{
"name": "amount",
"type": "decimal",
"required": true,
"min": "0",
"max": "100"
}
],
"min_rows": 1
}
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Service result. Inspect X-Mekler-Payment-State: finalized includes PAYMENT-RESPONSE; provisional includes a purchase ID without a settlement receipt.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"schema_version": {
"type": "integer",
"enum": [
1
]
},
"verdict": {
"type": "string",
"enum": [
"pass",
"fail"
]
},
"rows_checked": {
"type": "integer",
"minimum": 0
},
"failure_count": {
"type": "integer",
"minimum": 0
},
"failures": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"missing_column",
"extra_columns",
"row_width",
"required",
"type",
"min",
"max",
"enum",
"unique",
"min_rows",
"max_rows"
]
},
"row": {
"type": "integer",
"nullable": true,
"description": "One-based data record, excluding header; null for file/header errors."
},
"column": {
"type": "string",
"nullable": true,
"description": "Column name, or null when the error applies to the row or file."
}
},
"required": [
"code",
"row",
"column"
]
}
},
"failures_truncated": {
"type": "boolean"
},
"receipt_sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"boundary": {
"type": "string"
}
},
"required": [
"schema_version",
"verdict",
"rows_checked",
"failure_count",
"failures",
"failures_truncated",
"receipt_sha256",
"boundary"
]
},
"example": {
"schema_version": 1,
"verdict": "fail",
"rows_checked": 2,
"failure_count": 2,
"failures": [
{
"code": "unique",
"row": 2,
"column": "id"
},
{
"code": "min",
"row": 2,
"column": "amount"
}
],
"failures_truncated": false,
"receipt_sha256": "32265ae46050fa0067b9adb0df085a5cf3d9fa3d47d91e9ea2f61135a382d8ac",
"boundary": "Only supplied explicit criteria checked; no certification of truth or subjective quality."
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Malformed input or unsupported criterion; no acceptance verdict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"413": {
"description": "Request exceeds 256 KiB",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "Requires application/json",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application/json required"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
},
"402": {
"description": "Payment required; PAYMENT-REQUIRED header contains the server-authored USDC quote.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.050000"
}
}
}
},
"202": {
"description": "Settlement outcome pending; retry identical request and signed proof, never create a second payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"503": {
"description": "Payment service temporarily unavailable; do not create a second payment after an ambiguous response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "PAYMENT-SIGNATURE",
"in": "header",
"required": false,
"description": "Buyer-signed x402 v2 exact payment proof matching the server quote. Omit to obtain a 402 quote; send the identical proof on retry.",
"schema": {
"type": "string"
}
}
]Check a JSON CSV column specification before use; return the validated rules or reject unsupported settings.
POST /v1/data/csv/validate-column-spec
0.05 USDC per accepted request
Service scope, examples and recovery →
Validate a fixed JSON CSV column specification before assigning extraction or checking deliveries. Send typed column settings in requirements; returns the validated spec for /v1/data/csv/validate-data. Rejects unknown fields and unsupported settings. This checks the specification itself, not CSV data. No custom expressions, cross-column rules or prose-to-rule conversion. Schemas/examples attached; full contract: /openapi.json.
Input fields
requirementsRequired · object- See the complete request schema for values and bounds.
Response status
200- Service result. Inspect X-Mekler-Payment-State: finalized includes PAYMENT-RESPONSE; provisional includes a purchase ID without a settlement receipt.
400- Malformed input or unsupported criterion; no acceptance verdict
413- Request exceeds 256 KiB
415- Requires application/json
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
402- Payment required; PAYMENT-REQUIRED header contains the server-authored USDC quote.
202- Settlement outcome pending; retry identical request and signed proof, never create a second payment.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
503- Payment service temporarily unavailable; do not create a second payment after an ambiguous response.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"requirements"
],
"properties": {
"requirements": {
"type": "object",
"additionalProperties": false,
"required": [
"columns"
],
"properties": {
"columns": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"type": {
"type": "string",
"enum": [
"string",
"integer",
"decimal",
"boolean",
"date"
],
"description": "string: literal text; integer: base-10, no plus sign or leading zeros; decimal: plain decimal, no exponent; boolean: lowercase true/false; date: valid YYYY-MM-DD."
},
"required": {
"type": "boolean",
"default": false,
"description": "Reject empty cells. Whitespace is not trimmed."
},
"unique": {
"type": "boolean",
"default": false,
"description": "Reject repeated nonempty values within this column; numeric values compare numerically."
},
"min": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Inclusive numeric bound; allowed only for integer or decimal columns."
},
"max": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Inclusive numeric bound; allowed only for integer or decimal columns."
},
"enum": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
},
"description": "Exact allowed cell strings, compared without trimming or normalization."
}
}
},
"description": "Fixed built-in checks. Every named column must exist, even when required is false."
},
"min_rows": {
"type": "integer",
"minimum": 0,
"maximum": 2000,
"default": 0
},
"max_rows": {
"type": "integer",
"minimum": 0,
"maximum": 2000,
"default": 2000
},
"allow_extra_columns": {
"type": "boolean",
"default": false,
"description": "If false, reject CSV headers not named in columns."
}
}
}
}
},
"example": {
"requirements": {
"columns": [
{
"name": "id",
"type": "string",
"required": true,
"unique": true
},
{
"name": "amount",
"type": "decimal",
"required": true,
"min": "0",
"max": "100"
}
],
"min_rows": 1
}
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Service result. Inspect X-Mekler-Payment-State: finalized includes PAYMENT-RESPONSE; provisional includes a purchase ID without a settlement receipt.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"schema_version": {
"type": "integer",
"enum": [
1
]
},
"spec": {
"type": "object",
"additionalProperties": false,
"required": [
"columns"
],
"properties": {
"columns": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"type": {
"type": "string",
"enum": [
"string",
"integer",
"decimal",
"boolean",
"date"
]
},
"required": {
"type": "boolean",
"default": false
},
"unique": {
"type": "boolean",
"default": false
},
"min": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
]
},
"max": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
]
},
"enum": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
}
}
}
}
},
"min_rows": {
"type": "integer",
"minimum": 0,
"maximum": 2000,
"default": 0
},
"max_rows": {
"type": "integer",
"minimum": 0,
"maximum": 2000,
"default": 2000
},
"allow_extra_columns": {
"type": "boolean",
"default": false
}
}
},
"unsupported": {
"type": "array",
"maxItems": 0,
"items": {
"type": "string"
}
},
"boundary": {
"type": "string"
}
},
"required": [
"schema_version",
"spec",
"unsupported",
"boundary"
]
},
"example": {
"schema_version": 1,
"spec": {
"columns": [
{
"name": "id",
"type": "string",
"required": true,
"unique": true
},
{
"name": "amount",
"type": "decimal",
"required": true,
"min": "0",
"max": "100"
}
],
"min_rows": 1
},
"unsupported": [],
"boundary": "Typed requirements only; no natural-language interpretation."
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Malformed input or unsupported criterion; no acceptance verdict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"413": {
"description": "Request exceeds 256 KiB",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "Requires application/json",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application/json required"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
},
"402": {
"description": "Payment required; PAYMENT-REQUIRED header contains the server-authored USDC quote.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.050000"
}
}
}
},
"202": {
"description": "Settlement outcome pending; retry identical request and signed proof, never create a second payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"503": {
"description": "Payment service temporarily unavailable; do not create a second payment after an ambiguous response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "PAYMENT-SIGNATURE",
"in": "header",
"required": false,
"description": "Buyer-signed x402 v2 exact payment proof matching the server quote. Omit to obtain a 402 quote; send the identical proof on retry.",
"schema": {
"type": "string"
}
}
]Find duplicate citation URLs and shared source links in supplied HTML, with locations to inspect before relying on corroboration.
POST /v1/research/citations/check-source-overlap
0.05 USDC per accepted request
Service scope, examples and recovery →
Check source overlap before counting corroboration. Supply 2-10 URLs, optional article HTML and citation chains. Returns duplicate URLs, shared links and supplied-source groups with locations. No fetching, truth or independence verdict. Schemas: /openapi.json.
Input fields
claimRequired · string- Context label only; truth and semantic relevance are not assessed.
citationsRequired · array- See the complete request schema for values and bounds.
Response status
200- Service result. Inspect X-Mekler-Payment-State: finalized includes PAYMENT-RESPONSE; provisional includes a purchase ID without a settlement receipt.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"claim",
"citations"
],
"properties": {
"claim": {
"type": "string",
"minLength": 1,
"maxLength": 4000,
"description": "Context label only; truth and semantic relevance are not assessed."
},
"citations": {
"type": "array",
"minItems": 2,
"maxItems": 10,
"example": [
{
"id": "a",
"url": "https://a.test"
},
{
"id": "b",
"url": "https://b.test"
}
],
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"url"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_.-]{1,64}$"
},
"url": {
"type": "string",
"format": "uri",
"pattern": "^https://",
"maxLength": 2048
},
"html": {
"type": "string",
"maxLength": 131072,
"description": "Supplied article HTML; limit 131072 UTF-8 bytes. Never executed."
},
"derives_from": {
"type": "string",
"maxLength": 64,
"description": "Caller-declared parent citation ID. Requires evidence_locator; cycles rejected."
},
"evidence_locator": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"description": "Location supporting declared lineage; not independently verified."
}
},
"dependentRequired": {
"derives_from": [
"evidence_locator"
],
"evidence_locator": [
"derives_from"
]
}
}
}
}
},
"example": {
"claim": "Reported benefit",
"citations": [
{
"id": "a",
"url": "https://a.test",
"html": "<a href=\"https://b.test\">Source</a>"
},
{
"id": "b",
"url": "https://b.test"
}
]
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Service result. Inspect X-Mekler-Payment-State: finalized includes PAYMENT-RESPONSE; provisional includes a purchase ID without a settlement receipt.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"service": {
"const": "citation-overlap-checker"
},
"schema_version": {
"const": "1"
},
"shared_origin_groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"origin_url": {
"type": "string"
},
"citation_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"basis": {
"const": "supplied_lineage_or_identical_url"
}
},
"required": [
"origin_url",
"citation_ids",
"basis"
]
}
},
"supplied_lineage_links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"from_id": {
"type": "string"
},
"to_id": {
"type": "string"
},
"evidence_locator": {
"type": "string"
}
},
"required": [
"from_id",
"to_id",
"evidence_locator"
]
}
},
"shared_link_candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"linked_url": {
"type": "string"
},
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"target_url": {
"type": "string"
},
"line": {
"type": "integer"
},
"column": {
"type": "integer"
},
"anchor_text": {
"type": "string"
}
},
"required": [
"target_url",
"line",
"column",
"anchor_text"
]
}
}
},
"required": [
"id",
"locations"
]
}
},
"status": {
"const": "shared_link_candidate"
}
},
"required": [
"linked_url",
"documents",
"status"
]
}
},
"citation_link_candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"from_id": {
"type": "string"
},
"to_id": {
"type": "string"
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"target_url": {
"type": "string"
},
"line": {
"type": "integer"
},
"column": {
"type": "integer"
},
"anchor_text": {
"type": "string"
}
},
"required": [
"target_url",
"line",
"column",
"anchor_text"
]
}
},
"status": {
"const": "citation_link_candidate"
}
},
"required": [
"from_id",
"to_id",
"locations",
"status"
]
}
},
"unresolved_citation_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"independence": {
"const": "unknown"
},
"coverage": {
"type": "object",
"properties": {
"citation_count": {
"type": "integer"
},
"html_document_count": {
"type": "integer"
}
},
"required": [
"citation_count",
"html_document_count"
]
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"service",
"schema_version",
"shared_origin_groups",
"supplied_lineage_links",
"shared_link_candidates",
"citation_link_candidates",
"unresolved_citation_ids",
"independence",
"coverage",
"limitations"
]
},
"example": {
"service": "citation-overlap-checker",
"schema_version": "1",
"shared_origin_groups": [],
"supplied_lineage_links": [],
"shared_link_candidates": [],
"citation_link_candidates": [
{
"from_id": "a",
"to_id": "b",
"locations": [
{
"target_url": "https://b.test/",
"line": 1,
"column": 0,
"anchor_text": "Source"
}
],
"status": "citation_link_candidate"
}
],
"unresolved_citation_ids": [
"a",
"b"
],
"independence": "unknown",
"coverage": {
"citation_count": 2,
"html_document_count": 1
},
"limitations": [
"Supplied lineage is not independently verified.",
"Links may be navigation or unrelated to the claim; candidates are not verified dependencies.",
"No URLs are fetched. Missing links do not establish independence.",
"Claim truth and semantic relevance are not assessed."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.050000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Extract readable text, title and source links from one public static HTML page, with the final URL and fetch time.
POST /v1/web/pages/extract-static-content
0.005 USDC per completed page
Service scope, examples and recovery →
Fetch one public static HTML page after robots and public-address checks, then return bounded readable text, title, final URL and source links. Standard x402: POST the URL, sign the 402 and resend the same body. The 402 also returns an encrypted payment_request that pays for exactly the quoted fetch. No browser, login, summary or full-site crawl.
Input fields
urlRequired · string- See the complete request schema for values and bounds.
snapshotOptional · string- Opaque encrypted result from payment_request; omit it in the first call and for a standard resend.
Response status
200- Paid result; X-Mekler-Payment-State identifies finalized or provisional recovery.
202- Payment finality pending; retry the same signed body and proof.
400- Invalid JSON, URL or encrypted snapshot.
402- With a valid URL, the fetched page is ready: sign the offer and resend the same body, or send payment_request unchanged. An empty unsigned POST returns a preflight-only 402 price advertisement for directory validation; it has no payment_request and must not be signed. Submit a URL first.
409- Payment proof conflicts with a claimed purchase or changed content.
413- Request or fetched result exceeds the documented bound.
415- Use application/json.
422- URL, robots, fetch or page-content refusal; no payment required.
429- Short per-source rate limit or global gateway throttle. Wait Retry-After when present; preserve an existing signed body and proof.
503- Payment provider temporarily unavailable; retry a signed request unchanged.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url"
],
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"format": "uri"
},
"snapshot": {
"type": "string",
"minLength": 1,
"maxLength": 65536,
"description": "Opaque encrypted result from payment_request; omit it in the first call and for a standard resend."
}
}
},
"example": {
"url": "https://example.org/"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Paid result; X-Mekler-Payment-State identifies finalized or provisional recovery.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"final_url",
"title",
"text",
"source_links",
"fetched_at",
"truncated",
"coverage",
"bytes_fetched",
"redirects",
"elapsed_ms"
],
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"final_url": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"maxLength": 300
},
"text": {
"type": "string",
"maxLength": 20000
},
"source_links": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"format": "uri"
}
},
"fetched_at": {
"type": "string",
"format": "date-time"
},
"truncated": {
"type": "boolean"
},
"coverage": {
"type": "string",
"enum": [
"static_html_only"
]
},
"bytes_fetched": {
"type": "integer",
"minimum": 0
},
"redirects": {
"type": "integer",
"minimum": 0,
"maximum": 3
},
"elapsed_ms": {
"type": "number",
"minimum": 0
}
}
},
"example": {
"status": "ok",
"final_url": "https://example.org/",
"title": "Example Domain",
"text": "This domain is for use in documentation examples without needing permission. This is not a service, avoid relying on it for testing and monitoring purposes.\nLearn more",
"source_links": [
"https://iana.org/help/example-domains"
],
"fetched_at": "2026-09-29T00:00:00Z",
"truncated": false,
"coverage": "static_html_only",
"bytes_fetched": 274,
"redirects": 0,
"elapsed_ms": 12
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64-encoded receipt on finalized payment",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment finality pending; retry the same signed body and proof.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"status": "pending",
"retry_after_seconds": 5
}
}
}
},
"400": {
"description": "Invalid JSON, URL or encrypted snapshot.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "With a valid URL, the fetched page is ready: sign the offer and resend the same body, or send payment_request unchanged. An empty unsigned POST returns a preflight-only 402 price advertisement for directory validation; it has no payment_request and must not be signed. Submit a URL first.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_required",
"payment_request": {
"url": "https://example.org/",
"snapshot": "opaque-token"
}
}
}
},
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64-encoded x402 v2 payment requirements",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Payment proof conflicts with a claimed purchase or changed content.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_conflict"
}
}
}
},
"413": {
"description": "Request or fetched result exceeds the documented bound.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "Use application/json.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "application_json_required"
}
}
}
},
"422": {
"description": "URL, robots, fetch or page-content refusal; no payment required.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"status": "error",
"error": "robots_disallowed",
"text": ""
}
}
}
},
"429": {
"description": "Short per-source rate limit or global gateway throttle. Wait Retry-After when present; preserve an existing signed body and proof.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "pilot_attempt_capacity_exhausted"
}
}
},
"headers": {
"Retry-After": {
"description": "Seconds until this source can retry after an application rate limit.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}
},
"503": {
"description": "Payment provider temporarily unavailable; retry a signed request unchanged.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "PAYMENT-SIGNATURE",
"in": "header",
"required": false,
"description": "Buyer-signed x402 v2 payment proof. First send the URL without this header to obtain a quote; resend the same body (or the returned payment_request) with the proof. Retries reuse that body and proof. No separate API key is required.",
"schema": {
"type": "string"
}
}
]Prepare annual financial facts, checked changes and observed revisions
POST /v1/finance/companies/retrieve-annual-facts
0.05 USDC per annual facts bundle
Service scope, examples and recovery →
Annual US-GAAP facts by CIK, SEC sources, same-filing growth checks and observed revisions. Fast quote or coverage preview. Free SEC data; paid selection.
Input fields
cikRequired · string- SEC CIK, 1–10 ASCII digits, greater than zero. Leading zeros optional. Tickers are not accepted.
yearsOptional · integer- Number of most recent original annual 10-K report periods, not calendar years.
snapshotOptional · string- Opaque encrypted result from the unsigned quote. Optional: omit it for a standard x402 resend of the same input; if sent, use the returned payment_request unchanged and never construct it.
include_revisionsOptional · boolean- Include observed historical value changes across up to four recent annual filings represented in the SEC feed per period. No prior request needed; not exhaustive revision history or a restatement determination.
quote_modeOptional · string- Optional: fast returns a payable quote before source work and privately retains encrypted successful results for 30-day recovery. Omit for the existing preview/snapshot flow. Cannot be combined with snapshot.
Response status
200- Selected reported facts; inspect coverage and every field status. A provisional payment header is not settlement.
202- Payment pending. Retry the identical body and original proof; do not pay again.
400- Malformed input, unknown fields, invalid CIK/years, snapshot or proof.
402- Payable input-bound fast quote without source work, or the existing default preview/snapshot quote. Empty unsigned input is nonpayable preflight_only and must not be signed.
409- Fast work is already running, its lease was lost, or the proof is bound to another request; retain the original body and proof.
413- Request exceeds 128 KiB.
415- Use application/json.
422- Unsupported company/taxonomy or no supported annual facts; no successful purchase.
429- Per-source or gateway rate limit. Respect Retry-After and keep the original proof.
503- Temporary source, storage or payment dependency failure; retain the original body and proof and retry.
410- The encrypted fast-mode result has reached its 30-day recovery expiry. No new payment or source work is initiated.
504- Work deadline exceeded before successful result storage; unfinished work is uncharged.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"cik"
],
"additionalProperties": false,
"properties": {
"cik": {
"type": "string",
"pattern": "^[0-9]{1,10}$",
"description": "SEC CIK, 1–10 ASCII digits, greater than zero. Leading zeros optional. Tickers are not accepted."
},
"years": {
"type": "integer",
"minimum": 1,
"maximum": 3,
"default": 3,
"description": "Number of most recent original annual 10-K report periods, not calendar years."
},
"snapshot": {
"type": "string",
"minLength": 1,
"maxLength": 65536,
"description": "Opaque encrypted result from the unsigned quote. Optional: omit it for a standard x402 resend of the same input; if sent, use the returned payment_request unchanged and never construct it."
},
"include_revisions": {
"type": "boolean",
"default": false,
"description": "Include observed historical value changes across up to four recent annual filings represented in the SEC feed per period. No prior request needed; not exhaustive revision history or a restatement determination."
},
"quote_mode": {
"type": "string",
"enum": [
"fast"
],
"description": "Optional: fast returns a payable quote before source work and privately retains encrypted successful results for 30-day recovery. Omit for the existing preview/snapshot flow. Cannot be combined with snapshot."
}
},
"not": {
"required": [
"quote_mode",
"snapshot"
]
}
},
"example": {
"cik": "320193",
"years": 1,
"quote_mode": "fast"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Selected reported facts; inspect coverage and every field status. A provisional payment header is not settlement.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"cik",
"selection_policy",
"retrieved_at",
"years",
"coverage",
"sources",
"limitations",
"comparisons"
],
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"cik": {
"type": "string"
},
"selection_policy": {
"type": "string"
},
"retrieved_at": {
"type": "string"
},
"years": {
"type": "array",
"minItems": 1,
"maxItems": 3,
"items": {
"type": "object",
"required": [
"fiscal_year",
"period_end",
"fields"
],
"additionalProperties": false,
"properties": {
"fiscal_year": {
"type": "integer",
"nullable": true
},
"period_end": {
"type": "string"
},
"fields": {
"type": "object",
"required": [
"revenue",
"net_income",
"assets",
"liabilities",
"cash",
"operating_cash_flow"
],
"minProperties": 6,
"maxProperties": 6,
"additionalProperties": {
"type": "object",
"required": [
"status",
"value"
],
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"reported",
"missing",
"ambiguous",
"unsupported"
]
},
"value": {
"type": "number",
"nullable": true
},
"reason": {
"type": "string"
},
"unit": {
"type": "string",
"enum": [
"USD"
]
},
"period_start": {
"type": "string",
"nullable": true
},
"period_end": {
"type": "string"
},
"taxonomy": {
"type": "string",
"enum": [
"us-gaap"
]
},
"tag": {
"type": "string"
},
"accession": {
"type": "string"
},
"filed": {
"type": "string"
},
"form": {
"type": "string",
"enum": [
"10-K",
"10-K/A"
]
},
"filing_url": {
"type": "string"
}
}
}
}
}
}
},
"coverage": {
"type": "object",
"required": [
"requested_years",
"returned_years",
"reported_fields",
"requested_fields",
"complete"
],
"additionalProperties": false,
"properties": {
"requested_years": {
"type": "integer",
"minimum": 0
},
"returned_years": {
"type": "integer",
"minimum": 0
},
"reported_fields": {
"type": "integer",
"minimum": 0
},
"requested_fields": {
"type": "integer",
"minimum": 0
},
"complete": {
"type": "boolean"
}
}
},
"sources": {
"type": "object",
"properties": {
"companyfacts": {
"type": "string"
},
"submissions": {
"type": "string"
}
},
"required": [
"companyfacts",
"submissions"
],
"additionalProperties": false
},
"source_retrieved_at": {
"type": "object",
"properties": {
"companyfacts": {
"type": "string"
},
"submissions": {
"type": "string"
}
},
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
},
"comparisons": {
"type": "array",
"maxItems": 12,
"items": {
"type": "object",
"required": [
"field",
"prior_period_end",
"period_end",
"status",
"growth_percent",
"prior",
"current",
"period_days",
"warnings"
],
"additionalProperties": false,
"properties": {
"field": {
"type": "string"
},
"prior_period_end": {
"type": "string"
},
"period_end": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"missing",
"ambiguous",
"unsupported",
"no_common_filing",
"tag_mismatch",
"nonadjacent_periods",
"period_length_mismatch",
"nonpositive_base",
"checks_passed"
]
},
"growth_percent": {
"type": "number",
"nullable": true
},
"prior": {
"type": "object",
"required": [
"status",
"value"
],
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"reported",
"missing",
"ambiguous",
"unsupported"
]
},
"value": {
"type": "number",
"nullable": true
},
"reason": {
"type": "string"
},
"unit": {
"type": "string",
"enum": [
"USD"
]
},
"period_start": {
"type": "string",
"nullable": true
},
"period_end": {
"type": "string"
},
"taxonomy": {
"type": "string",
"enum": [
"us-gaap"
]
},
"tag": {
"type": "string"
},
"accession": {
"type": "string"
},
"filed": {
"type": "string"
},
"form": {
"type": "string",
"enum": [
"10-K",
"10-K/A"
]
},
"filing_url": {
"type": "string"
}
},
"nullable": true
},
"current": {
"type": "object",
"required": [
"status",
"value"
],
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"reported",
"missing",
"ambiguous",
"unsupported"
]
},
"value": {
"type": "number",
"nullable": true
},
"reason": {
"type": "string"
},
"unit": {
"type": "string",
"enum": [
"USD"
]
},
"period_start": {
"type": "string",
"nullable": true
},
"period_end": {
"type": "string"
},
"taxonomy": {
"type": "string",
"enum": [
"us-gaap"
]
},
"tag": {
"type": "string"
},
"accession": {
"type": "string"
},
"filed": {
"type": "string"
},
"form": {
"type": "string",
"enum": [
"10-K",
"10-K/A"
]
},
"filing_url": {
"type": "string"
}
},
"nullable": true
},
"period_days": {
"type": "array",
"maxItems": 2,
"items": {
"type": "integer"
}
},
"warnings": {
"type": "array",
"maxItems": 4,
"items": {
"type": "string"
}
}
}
}
},
"revisions": {
"type": "object",
"required": [
"scope",
"classification",
"periods"
],
"additionalProperties": false,
"properties": {
"scope": {
"type": "string"
},
"classification": {
"type": "string"
},
"periods": {
"type": "array",
"maxItems": 3,
"items": {
"type": "object",
"required": [
"period_end",
"available_filing_count",
"inspected_filings",
"truncated",
"fields"
],
"additionalProperties": false,
"properties": {
"period_end": {
"type": "string"
},
"available_filing_count": {
"type": "integer",
"minimum": 0
},
"inspected_filings": {
"type": "array",
"maxItems": 4,
"items": {
"type": "string"
}
},
"truncated": {
"type": "boolean"
},
"fields": {
"type": "array",
"maxItems": 24,
"items": {
"type": "object",
"required": [
"field",
"tag",
"unit",
"period_start",
"period_end",
"status",
"observations",
"missing_from_filings"
],
"additionalProperties": false,
"properties": {
"field": {
"type": "string"
},
"tag": {
"type": "string",
"nullable": true
},
"unit": {
"type": "string",
"nullable": true
},
"period_start": {
"type": "string",
"nullable": true
},
"period_end": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"missing",
"unsupported",
"ambiguous",
"incomplete_history",
"reported_value_changed",
"unchanged_in_inspected_filings"
]
},
"observations": {
"type": "array",
"maxItems": 8,
"items": {
"type": "object",
"required": [
"status",
"value"
],
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"reported",
"missing",
"ambiguous",
"unsupported"
]
},
"value": {
"type": "number",
"nullable": true
},
"reason": {
"type": "string"
},
"unit": {
"type": "string",
"enum": [
"USD"
]
},
"period_start": {
"type": "string",
"nullable": true
},
"period_end": {
"type": "string"
},
"taxonomy": {
"type": "string",
"enum": [
"us-gaap"
]
},
"tag": {
"type": "string"
},
"accession": {
"type": "string"
},
"filed": {
"type": "string"
},
"form": {
"type": "string",
"enum": [
"10-K",
"10-K/A"
]
},
"filing_url": {
"type": "string"
}
}
}
},
"missing_from_filings": {
"type": "array",
"maxItems": 4,
"items": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
},
"example": {
"status": "ok",
"cik": "0000320193",
"selection_policy": "latest-annual-filed-per-field-v1",
"retrieved_at": "2026-10-05T00:00:00Z",
"years": [
{
"fiscal_year": 2025,
"period_end": "2025-09-27",
"fields": {
"revenue": {
"status": "reported",
"value": 416161000000,
"unit": "USD",
"period_start": "2024-09-29",
"period_end": "2025-09-27",
"taxonomy": "us-gaap",
"tag": "RevenueFromContractWithCustomerExcludingAssessedTax",
"accession": "0000320193-25-000079",
"filed": "2025-10-31",
"form": "10-K",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.html"
},
"net_income": {
"status": "reported",
"value": 112010000000,
"unit": "USD",
"period_start": "2024-09-29",
"period_end": "2025-09-27",
"taxonomy": "us-gaap",
"tag": "NetIncomeLoss",
"accession": "0000320193-25-000079",
"filed": "2025-10-31",
"form": "10-K",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.html"
},
"assets": {
"status": "reported",
"value": 359241000000,
"unit": "USD",
"period_start": null,
"period_end": "2025-09-27",
"taxonomy": "us-gaap",
"tag": "Assets",
"accession": "0000320193-25-000079",
"filed": "2025-10-31",
"form": "10-K",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.html"
},
"liabilities": {
"status": "reported",
"value": 285508000000,
"unit": "USD",
"period_start": null,
"period_end": "2025-09-27",
"taxonomy": "us-gaap",
"tag": "Liabilities",
"accession": "0000320193-25-000079",
"filed": "2025-10-31",
"form": "10-K",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.html"
},
"cash": {
"status": "reported",
"value": 35934000000,
"unit": "USD",
"period_start": null,
"period_end": "2025-09-27",
"taxonomy": "us-gaap",
"tag": "CashAndCashEquivalentsAtCarryingValue",
"accession": "0000320193-25-000079",
"filed": "2025-10-31",
"form": "10-K",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.html"
},
"operating_cash_flow": {
"status": "reported",
"value": 111482000000,
"unit": "USD",
"period_start": "2024-09-29",
"period_end": "2025-09-27",
"taxonomy": "us-gaap",
"tag": "NetCashProvidedByUsedInOperatingActivities",
"accession": "0000320193-25-000079",
"filed": "2025-10-31",
"form": "10-K",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.html"
}
}
}
],
"coverage": {
"requested_years": 1,
"returned_years": 1,
"reported_fields": 6,
"requested_fields": 6,
"complete": true
},
"sources": {
"companyfacts": "https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json",
"submissions": "https://data.sec.gov/submissions/CIK0000320193.json"
},
"limitations": [
"US-GAAP standard whole-entity USD facts in annual 10-K/10-K/A only.",
"Latest annual-filed value is selected per field; different fields may cite different filings.",
"Missing is not zero and does not establish absence from the original filing.",
"No custom tags, segments, quarterly derivations, currency conversion or investment advice."
],
"comparisons": []
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "x402 v2 encoded payment envelope",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry the identical body and original proof; do not pay again.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"error": "retry_or_correct_request"
}
}
},
"headers": {
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Malformed input, unknown fields, invalid CIK/years, snapshot or proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"error": "retry_or_correct_request"
}
}
}
},
"402": {
"description": "Payable input-bound fast quote without source work, or the existing default preview/snapshot quote. Empty unsigned input is nonpayable preflight_only and must not be signed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"payment_request": {
"type": "object",
"required": [
"cik"
],
"additionalProperties": false,
"properties": {
"cik": {
"type": "string",
"pattern": "^[0-9]{1,10}$",
"description": "SEC CIK, 1–10 ASCII digits, greater than zero. Leading zeros optional. Tickers are not accepted."
},
"years": {
"type": "integer",
"minimum": 1,
"maximum": 3,
"default": 3,
"description": "Number of most recent original annual 10-K report periods, not calendar years."
},
"snapshot": {
"type": "string",
"minLength": 1,
"maxLength": 65536,
"description": "Opaque encrypted result from the unsigned quote. Optional: omit it for a standard x402 resend of the same input; if sent, use the returned payment_request unchanged and never construct it."
},
"include_revisions": {
"type": "boolean",
"default": false,
"description": "Include observed historical value changes across up to four recent annual filings represented in the SEC feed per period. No prior request needed; not exhaustive revision history or a restatement determination."
}
}
},
"coverage": {
"type": "object",
"required": [
"requested_years",
"returned_years",
"reported_fields",
"requested_fields",
"complete"
],
"additionalProperties": false,
"properties": {
"requested_years": {
"type": "integer",
"minimum": 0
},
"returned_years": {
"type": "integer",
"minimum": 0
},
"reported_fields": {
"type": "integer",
"minimum": 0
},
"requested_fields": {
"type": "integer",
"minimum": 0
},
"complete": {
"type": "boolean"
}
}
},
"preflight_only": {
"type": "boolean"
},
"preparation": {
"type": "object",
"required": [
"comparison_count",
"comparisons_with_growth",
"revisions_requested",
"changed_series",
"incomplete_series",
"history_truncated"
],
"additionalProperties": false,
"properties": {
"comparison_count": {
"type": "integer"
},
"comparisons_with_growth": {
"type": "integer"
},
"revisions_requested": {
"type": "boolean"
},
"changed_series": {
"type": "integer"
},
"incomplete_series": {
"type": "integer"
},
"history_truncated": {
"type": "boolean"
}
}
},
"quote_mode": {
"type": "string",
"enum": [
"fast"
]
},
"recovery": {
"type": "string"
}
}
},
"example": {
"preflight_only": true
}
}
},
"headers": {
"PAYMENT-REQUIRED": {
"description": "x402 v2 encoded payment envelope",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Fast work is already running, its lease was lost, or the proof is bound to another request; retain the original body and proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"error": "retry_or_correct_request"
}
}
}
},
"413": {
"description": "Request exceeds 128 KiB.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"error": "retry_or_correct_request"
}
}
}
},
"415": {
"description": "Use application/json.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"error": "retry_or_correct_request"
}
}
}
},
"422": {
"description": "Unsupported company/taxonomy or no supported annual facts; no successful purchase.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"error": "retry_or_correct_request"
}
}
}
},
"429": {
"description": "Per-source or gateway rate limit. Respect Retry-After and keep the original proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"error": "retry_or_correct_request"
}
}
}
},
"503": {
"description": "Temporary source, storage or payment dependency failure; retain the original body and proof and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"error": "retry_or_correct_request"
}
}
}
},
"410": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"description": "The encrypted fast-mode result has reached its 30-day recovery expiry. No new payment or source work is initiated."
},
"504": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"description": "Work deadline exceeded before successful result storage; unfinished work is uncharged."
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "Optional x402 v2 signed proof after reviewing the quote; omit for uncharged retrieval and quote."
}
]Render one public JavaScript page in a headless browser and extract readable text, title and source links, with the final URL and render time.
POST /v1/web/pages/extract-rendered-content
0.01 USDC per completed rendered page
Service scope, examples and recovery →
Render one public web page in a headless browser and extract bounded text and source links, for pages whose content appears only after JavaScript runs. Standard x402 resend with an immediate opt-in fast quote and private encrypted recovery, or default render-first preview and optional caller-carried snapshot. 0.01 USDC on Solana or Base mainnet per completed page; failed renders are never charged.
Input fields
urlRequired · string- See the complete request schema for values and bounds.
snapshotOptional · string- Opaque encrypted result from payment_request; omit it in the first call and for a standard resend.
quote_modeOptional · string- Optional: fast returns a payable quote before source work and privately retains encrypted successful results for 30-day recovery. Omit for the existing preview/snapshot flow. Cannot be combined with snapshot.
Response status
200- Paid result; X-Mekler-Payment-State identifies finalized or provisional recovery.
202- Payment finality pending; retry the same signed body and proof.
400- Invalid JSON, URL or encrypted snapshot.
402- Payable input-bound fast quote without source work, or the existing default preview/snapshot quote. Empty unsigned input is nonpayable preflight_only and must not be signed.
409- Fast work is already running, its lease was lost, or the proof is bound to another request; retain the original body and proof.
413- Request or rendered result exceeds the documented bound.
415- Use application/json.
422- URL, robots, address, bot-protection, HTTP status or empty-page refusal; nothing charged.
429- Short per-source rate limit or global gateway throttle. Wait Retry-After when present; preserve an existing signed body and proof.
502- The page could not be rendered (navigation failure or robots.txt unavailable); nothing charged.
503- Temporary source, storage or payment dependency failure; retain the original body and proof and retry.
504- Work deadline exceeded before successful result storage; unfinished work is uncharged.
410- The encrypted fast-mode result has reached its 30-day recovery expiry. No new payment or source work is initiated.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url"
],
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"format": "uri"
},
"snapshot": {
"type": "string",
"minLength": 1,
"maxLength": 65536,
"description": "Opaque encrypted result from payment_request; omit it in the first call and for a standard resend."
},
"quote_mode": {
"type": "string",
"enum": [
"fast"
],
"description": "Optional: fast returns a payable quote before source work and privately retains encrypted successful results for 30-day recovery. Omit for the existing preview/snapshot flow. Cannot be combined with snapshot."
}
},
"not": {
"required": [
"quote_mode",
"snapshot"
]
}
},
"example": {
"url": "https://crates.io/crates/serde",
"quote_mode": "fast"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Paid result; X-Mekler-Payment-State identifies finalized or provisional recovery.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"final_url",
"title",
"text",
"source_links",
"fetched_at",
"truncated",
"coverage"
],
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"final_url": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"maxLength": 300
},
"text": {
"type": "string",
"maxLength": 20000
},
"source_links": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"format": "uri"
}
},
"fetched_at": {
"type": "string",
"format": "date-time"
},
"truncated": {
"type": "boolean"
},
"coverage": {
"type": "string",
"enum": [
"rendered_html"
]
}
}
},
"example": {
"status": "ok",
"final_url": "https://crates.io/crates/serde",
"title": "serde - crates.io: Rust Package Registry",
"text": "Serde is a framework for serializing and deserializing Rust data structures efficiently and generically.\nserde.rs",
"source_links": [
"https://serde.rs/"
],
"fetched_at": "2026-10-05T00:00:00Z",
"truncated": false,
"coverage": "rendered_html"
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64-encoded receipt on finalized payment",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment finality pending; retry the same signed body and proof.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"status": "pending",
"retry_after_seconds": 5
}
}
},
"headers": {
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid JSON, URL or encrypted snapshot.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "Payable input-bound fast quote without source work, or the existing default preview/snapshot quote. Empty unsigned input is nonpayable preflight_only and must not be signed.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_required",
"payment_request": {
"url": "https://example.org/",
"snapshot": "opaque-token"
}
}
}
},
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64-encoded x402 v2 payment requirements",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Fast work is already running, its lease was lost, or the proof is bound to another request; retain the original body and proof.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_conflict"
}
}
}
},
"413": {
"description": "Request or rendered result exceeds the documented bound.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "Use application/json.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "application_json_required"
}
}
}
},
"422": {
"description": "URL, robots, address, bot-protection, HTTP status or empty-page refusal; nothing charged.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"status": "error",
"error": "robots_disallowed",
"text": "",
"charged": false
}
}
}
},
"429": {
"description": "Short per-source rate limit or global gateway throttle. Wait Retry-After when present; preserve an existing signed body and proof.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "pilot_attempt_capacity_exhausted"
}
}
},
"headers": {
"Retry-After": {
"description": "Seconds until this source can retry after an application rate limit.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}
},
"502": {
"description": "The page could not be rendered (navigation failure or robots.txt unavailable); nothing charged.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"status": "error",
"error": "navigation_failure",
"text": "",
"charged": false
}
}
}
},
"503": {
"description": "Temporary source, storage or payment dependency failure; retain the original body and proof and retry.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"504": {
"description": "Work deadline exceeded before successful result storage; unfinished work is uncharged.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"status": "error",
"error": "timeout",
"text": "",
"charged": false
}
}
}
},
"410": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"description": "The encrypted fast-mode result has reached its 30-day recovery expiry. No new payment or source work is initiated."
}
}Complete schema: parameters and headers
[
{
"name": "PAYMENT-SIGNATURE",
"in": "header",
"required": false,
"description": "Buyer-signed x402 v2 payment proof. First send the URL without this header to obtain a quote; resend the same body (or the returned payment_request) with the proof. Retries reuse that body and proof. No separate API key is required.",
"schema": {
"type": "string"
}
}
]Check an email address or domain for syntax and published mail configuration.
POST /v1/email/domains/check-mail-configuration
0.003 USDC per completed check
Service scope, examples and recovery →
Check one email address or domain. Report common address syntax, MX or null MX and A/AAAA fallback, SPF, exact-domain DMARC and optional caller-supplied DKIM selector records, and a small known disposable-domain list. DNS failures remain unknown. Does not verify a mailbox or predict delivery.
Input fields
kindRequired · string- See the complete request schema for values and bounds.
valueRequired · string- One email address when kind=email; one public DNS domain when kind=domain.
selectorOptional · string- Optional caller-supplied DKIM selector. No selector discovery; periods separate DNS labels.
Response status
200- Completed check; inspect unknown and not_found_at_queried_name before acting. X-Mekler-Payment-State reports settlement.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"domain"
]
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 320,
"description": "One email address when kind=email; one public DNS domain when kind=domain."
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional caller-supplied DKIM selector. No selector discovery; periods separate DNS labels."
}
}
},
"example": {
"kind": "domain",
"value": "example.org"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed check; inspect unknown and not_found_at_queried_name before acting. X-Mekler-Payment-State reports settlement.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"service",
"schema_version",
"domain",
"syntax",
"mail_route",
"spf",
"dmarc",
"dkim",
"disposable",
"mailbox_exists"
],
"properties": {
"service": {
"type": "string"
},
"schema_version": {
"type": "string"
},
"domain": {
"type": "string"
},
"syntax": {
"type": "string"
},
"mail_route": {
"type": "object"
},
"spf": {
"type": "object"
},
"dmarc": {
"type": "object"
},
"disposable": {
"type": "string"
},
"mailbox_exists": {
"type": "string"
},
"dkim": {
"type": "object"
}
}
},
"example": {
"service": "email-domain-checks",
"schema_version": "1",
"domain": "example.org",
"syntax": "not_applicable",
"mail_route": {
"status": "mx_configured",
"mx": {
"status": "ok",
"values": [
[
10,
"mail.example.org"
]
],
"ttl_seconds": 60
}
},
"spf": {
"status": "record_found",
"record": "v=spf1 -all",
"dns": {
"status": "ok",
"ttl_seconds": 60
}
},
"dmarc": {
"status": "record_found",
"record": "v=DMARC1; p=reject",
"dns": {
"status": "ok",
"ttl_seconds": 60
}
},
"dkim": {
"status": "selector_required"
},
"disposable": "not_on_small_known_list",
"mailbox_exists": "unknown"
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.003000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Read job state with capability, or public report freshness by report_id
GET /v1/services/conformance/retrieve-scan-status
Follow the authentication, capability and prerequisite requirements below.
Read job state with capability, or public report freshness by report_id. Does not create work or payment. Requires identifiers from your own scan; published example IDs are synthetic. Supply either job_id plus X-Mekler-Scan-Capability from an admitted scan, or report_id from a completed paid scan. A quote alone creates no job. These are alternative parameter sets, not an all-optional call.
Response status
200- Read job state with capability, or public report freshness by report_id. Does not create work or payment.
404- Unknown or inaccessible record.
410- Artifact expired; receipt recovery remains available. No automatic repurchase.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Read job state with capability, or public report freshness by report_id. Does not create work or payment.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"required": [
"job_id",
"state",
"flow"
],
"properties": {
"job_id": {
"type": "string",
"description": "Opaque job identifier. Retain with the recovery capability."
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"result-ready",
"settlement-pending",
"complete",
"failed-uncharged",
"expired-uncharged",
"reconciliation-required",
"report-expired"
]
},
"flow": {
"enum": [
"compute-then-pay",
"quote-first-async"
]
},
"retry_after": {
"type": "integer"
},
"recovery_capability": {
"type": "string",
"description": "Secret capability, returned at admission only. Send in X-Mekler-Scan-Capability; never in a URL."
},
"report_id": {
"type": "string",
"description": "Opaque report identifier; public access begins only after confirmed settlement."
},
"error": {
"type": "string",
"description": "Stable safe error code."
},
"purchase_id": {
"type": "string",
"description": "Payment recovery reference, visible only with capability."
},
"receipt": {
"type": "object",
"properties": {
"network": {
"type": "string"
},
"transaction": {
"type": "string"
},
"finalized": {
"const": true
}
}
}
}
},
{
"type": "object",
"required": [
"report_id",
"scanned_at",
"expires_at",
"linter",
"compliance"
]
}
]
}
}
}
},
"404": {
"description": "Unknown or inaccessible record.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"410": {
"description": "Artifact expired; receipt recovery remains available. No automatic repurchase.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_id",
"state",
"flow"
],
"properties": {
"job_id": {
"type": "string",
"description": "Opaque job identifier. Retain with the recovery capability."
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"result-ready",
"settlement-pending",
"complete",
"failed-uncharged",
"expired-uncharged",
"reconciliation-required"
]
},
"flow": {
"enum": [
"compute-then-pay",
"quote-first-async"
]
},
"retry_after": {
"type": "integer"
},
"recovery_capability": {
"type": "string",
"description": "Secret capability, returned at admission only. Send in X-Mekler-Scan-Capability; never in a URL."
},
"report_id": {
"type": "string",
"description": "Opaque public report identifier, present after payment confirmation."
},
"error": {
"type": "string",
"description": "Stable safe error code."
},
"purchase_id": {
"type": "string",
"description": "Payment recovery reference, visible only with capability."
}
}
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "job_id",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Required with X-Mekler-Scan-Capability when looking up a private admitted job; otherwise supply report_id."
},
{
"name": "X-Mekler-Scan-Capability",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Required when using job_id. Private capability returned by the admitted scan; never place it in a URL."
},
{
"name": "report_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"description": "64 lowercase hexadecimal characters returned by a completed paid scan. Required for report retrieval; alternative to job_id/capability for status."
}
]Read a complete public cached report for 24 hours after scanning; expired reports return 410 without creating work
GET /v1/services/conformance/retrieve-scan-report
Follow the authentication, capability and prerequisite requirements below.
Read a complete public cached report for 24 hours after scanning; expired reports return 410 without creating work. Requires identifiers from your own scan; published example IDs are synthetic. Supply report_id from a completed paid scan. This is not a discovery/health endpoint.
Response status
200- Read a complete public cached report for 24 hours after scanning; expired reports return 410 without creating work.
404- Unknown or inaccessible record.
410- Artifact expired; receipt recovery remains available. No automatic repurchase.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Read a complete public cached report for 24 hours after scanning; expired reports return 410 without creating work.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"report_id",
"checks_version",
"scanned_at",
"expires_at",
"linter",
"compliance",
"findings"
],
"properties": {
"report_id": {
"type": "string",
"description": "Opaque ID"
},
"checks_version": {
"type": "string",
"description": "Mekler grading/check version"
},
"scanned_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"linter": {
"type": "object"
},
"compliance": {
"type": "object"
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"status",
"severity",
"evidence",
"fix"
],
"properties": {
"id": {
"type": "string",
"description": "Versioned check ID"
},
"status": {
"type": "string",
"description": "pass, warn, fail, skip or unknown"
},
"severity": {
"type": "string",
"description": "critical, major or minor"
},
"evidence": {
"type": "string",
"description": "Generated safe reason code, never target content"
},
"fix": {
"type": "string",
"description": "Fixed corrective advice"
}
}
}
},
"coverage": {
"type": "object"
}
}
}
}
}
},
"404": {
"description": "Unknown or inaccessible record.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"410": {
"description": "Artifact expired; receipt recovery remains available. No automatic repurchase.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_id",
"state",
"flow"
],
"properties": {
"job_id": {
"type": "string",
"description": "Opaque job identifier. Retain with the recovery capability."
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"result-ready",
"settlement-pending",
"complete",
"failed-uncharged",
"expired-uncharged",
"reconciliation-required"
]
},
"flow": {
"enum": [
"compute-then-pay",
"quote-first-async"
]
},
"retry_after": {
"type": "integer"
},
"recovery_capability": {
"type": "string",
"description": "Secret capability, returned at admission only. Send in X-Mekler-Scan-Capability; never in a URL."
},
"report_id": {
"type": "string",
"description": "Opaque public report identifier, present after payment confirmation."
},
"error": {
"type": "string",
"description": "Stable safe error code."
},
"purchase_id": {
"type": "string",
"description": "Payment recovery reference, visible only with capability."
}
}
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "report_id",
"in": "query",
"required": true,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"description": "64 lowercase hexadecimal characters returned by a completed paid scan. Required for report retrieval; alternative to job_id/capability for status."
},
{
"name": "X-Mekler-Scan-Capability",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Required when using job_id. Private capability returned by the admitted scan; never place it in a URL."
}
]Read both independent check catalogs, grading rules, versions and evaluation coverage
GET /v1/services/conformance/list-conformance-checks
Follow the authentication, capability and prerequisite requirements below.
Read both independent check catalogs, grading rules, versions and evaluation coverage.
Response status
200- Read both independent check catalogs, grading rules, versions and evaluation coverage.
404- Unknown or inaccessible record.
410- Artifact expired; receipt recovery remains available. No automatic repurchase.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Read both independent check catalogs, grading rules, versions and evaluation coverage.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"404": {
"description": "Unknown or inaccessible record.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"410": {
"description": "Artifact expired; receipt recovery remains available. No automatic repurchase.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_id",
"state",
"flow"
],
"properties": {
"job_id": {
"type": "string",
"description": "Opaque job identifier. Retain with the recovery capability."
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"result-ready",
"settlement-pending",
"complete",
"failed-uncharged",
"expired-uncharged",
"reconciliation-required"
]
},
"flow": {
"enum": [
"compute-then-pay",
"quote-first-async"
]
},
"retry_after": {
"type": "integer"
},
"recovery_capability": {
"type": "string",
"description": "Secret capability, returned at admission only. Send in X-Mekler-Scan-Capability; never in a URL."
},
"report_id": {
"type": "string",
"description": "Opaque public report identifier, present after payment confirmation."
},
"error": {
"type": "string",
"description": "Stable safe error code."
},
"purchase_id": {
"type": "string",
"description": "Payment recovery reference, visible only with capability."
}
}
}
}
}
}
}Complete schema: parameters and headers
[]
Scan an x402 service origin for protocol and discovery conformance
POST /v1/services/conformance/scan-origin
0.05 USDC per completed scan
Service scope, examples and recovery →
Diagnose a public x402 origin with 25 linter and 14 compliance checks, plus six separate request-example/schema and challenge consistency diagnostics. Use quote_mode fast for an immediate 402, resend unchanged input with one payment proof, then poll using the returned capability. Successful reports are stored before settlement. Examples are checked offline, never replayed; unsupported schemas stay unknown. No target payment, paid-delivery verification or safety guarantee.
Input fields
originRequired · string- Public HTTP(S) origin only; no path, credentials, query or fragment. Standard port only.
idempotency_keyOptional · string- Required in default compute-first mode; optional in fast mode, where the original payment proof itself is the retry identity. If supplied, generate at least 128 random bits and reuse for every retry. One proof per job for at least 90 days; changed input or a second proof returns 409.
pathsOptional · array- Optional same-origin paths to probe with unsigned GET/HEAD. No query strings, fragments or credential-bearing input. Otherwise discover paid routes from OpenAPI and the x402 manifest.
quote_modeOptional · string- Optional payable first quote. The unchanged input plus proof admits an asynchronous scan; settlement follows stored successful output.
Response status
200- Confirmed payment; complete report.
202- Durable asynchronous job or payment pending, not completed output. Save job_id and recovery_capability; poll GET status. Keep original body and proof for POST recovery; do not sign another payment.
400- Invalid input or payment.
402- Genuine payable offer for valid fast input, or for a result-ready default job with capability. Empty input remains nonpayable discovery preflight. Quotes expire in 120 seconds; rail authorization may expire sooner.
409- Changed input or another payment already bound to this job; recover the original attempt.
410- Expired job/artifact, no charge or new work.
429- Unpaid admission limit; retry after indicated delay.
503- Unavailable; retry identical request and original proof.
413- Request exceeds 64 KiB.
415- Use application/json.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"origin"
],
"properties": {
"origin": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Public HTTP(S) origin only; no path, credentials, query or fragment. Standard port only."
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{22,128}$",
"description": "Required in default compute-first mode; optional in fast mode, where the original payment proof itself is the retry identity. If supplied, generate at least 128 random bits and reuse for every retry. One proof per job for at least 90 days; changed input or a second proof returns 409."
},
"paths": {
"type": "array",
"maxItems": 50,
"uniqueItems": true,
"items": {
"type": "string",
"pattern": "^/",
"maxLength": 1024
},
"description": "Optional same-origin paths to probe with unsigned GET/HEAD. No query strings, fragments or credential-bearing input. Otherwise discover paid routes from OpenAPI and the x402 manifest."
},
"quote_mode": {
"type": "string",
"enum": [
"fast"
],
"description": "Optional payable first quote. The unchanged input plus proof admits an asynchronous scan; settlement follows stored successful output."
}
},
"anyOf": [
{
"required": [
"quote_mode"
]
},
{
"required": [
"idempotency_key"
]
}
]
},
"example": {
"origin": "https://api.mekler.ai",
"quote_mode": "fast"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Confirmed payment; complete report.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"report_id",
"checks_version",
"scanned_at",
"expires_at",
"linter",
"compliance",
"findings"
],
"properties": {
"report_id": {
"type": "string",
"description": "Opaque ID"
},
"checks_version": {
"type": "string",
"description": "Mekler grading/check version"
},
"scanned_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"linter": {
"type": "object"
},
"compliance": {
"type": "object"
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"status",
"severity",
"evidence",
"fix"
],
"properties": {
"id": {
"type": "string",
"description": "Versioned check ID"
},
"status": {
"type": "string",
"description": "pass, warn, fail, skip or unknown"
},
"severity": {
"type": "string",
"description": "critical, major or minor"
},
"evidence": {
"type": "string",
"description": "Generated safe reason code, never target content"
},
"fix": {
"type": "string",
"description": "Fixed corrective advice"
}
}
}
},
"coverage": {
"type": "object"
},
"diagnostics": {
"type": "object",
"description": "Optional on older reports. Versioned E1-E6 offline schema and unsigned challenge diagnostics; separate from grades. Contains version, bounds, summary and findings with generated subjects and fixed text."
}
}
},
"example": {
"checks_version": "mekler-2026-10-07.1",
"linter": {
"score": 89,
"grade": "B",
"categories": {
"protocol": 100,
"docs": 68,
"directory": 100
},
"evaluated": 20,
"total": 25,
"provisional": true,
"rules_version": "mekler-2026-10-07.1"
},
"compliance": {
"score": 100,
"grade": "A",
"evaluated": 14,
"total": 14,
"provisional": false,
"rules_version": "mekler-2026-10-07.1"
},
"findings": [
{
"id": "P1",
"title": "http-reachable",
"severity": "critical",
"category": "protocol",
"status": "pass",
"evidence": "criterion_satisfied",
"fix": "Serve a reachable public HTTP endpoint."
}
],
"coverage": {
"paid_routes_probed": 1,
"head_observations": 1,
"chain_checks": "not_evaluated",
"delivery_verified": false,
"raw_content_published": false
},
"report_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"scanned_at": 1791331200,
"expires_at": 1791417600,
"diagnostics": {
"version": "mekler-inputs-2026-10-19.1",
"summary": {
"pass": 1,
"fail": 0,
"warn": 0,
"unknown": 0,
"skip": 0
},
"findings": [
{
"id": "E1",
"subject": "operation_01",
"title": "Request example satisfies its schema",
"status": "pass",
"evidence": "example_matches_supported_schema",
"fix": "Publish an application/json example that satisfies the declared request schema, including every required field."
}
],
"examples_replayed": false,
"paid_delivery_verified": false
}
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON payment receipt.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Durable asynchronous job or payment pending, not completed output. Save job_id and recovery_capability; poll GET status. Keep original body and proof for POST recovery; do not sign another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_id",
"state",
"flow"
],
"properties": {
"job_id": {
"type": "string",
"description": "Opaque job identifier. Retain with the recovery capability."
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"result-ready",
"settlement-pending",
"complete",
"failed-uncharged",
"expired-uncharged",
"reconciliation-required",
"report-expired"
]
},
"flow": {
"enum": [
"compute-then-pay",
"quote-first-async"
]
},
"retry_after": {
"type": "integer"
},
"recovery_capability": {
"type": "string",
"description": "Secret capability, returned at admission only. Send in X-Mekler-Scan-Capability; never in a URL."
},
"report_id": {
"type": "string",
"description": "Opaque report identifier; public access begins only after confirmed settlement."
},
"error": {
"type": "string",
"description": "Stable safe error code."
},
"purchase_id": {
"type": "string",
"description": "Payment recovery reference, visible only with capability."
},
"receipt": {
"type": "object",
"properties": {
"network": {
"type": "string"
},
"transaction": {
"type": "string"
},
"finalized": {
"const": true
}
}
}
}
},
"example": {
"job_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "queued",
"flow": "compute-then-pay"
}
}
},
"headers": {
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid input or payment.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "Genuine payable offer for valid fast input, or for a result-ready default job with capability. Empty input remains nonpayable discovery preflight. Quotes expire in 120 seconds; rail authorization may expire sooner.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_required"
}
}
},
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 challenge. Sign only when the stored result is ready.",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "Changed input or another payment already bound to this job; recover the original attempt.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_id",
"state",
"flow"
],
"properties": {
"job_id": {
"type": "string",
"description": "Opaque job identifier. Retain with the recovery capability."
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"result-ready",
"settlement-pending",
"complete",
"failed-uncharged",
"expired-uncharged",
"reconciliation-required"
]
},
"flow": {
"enum": [
"compute-then-pay",
"quote-first-async"
]
},
"retry_after": {
"type": "integer"
},
"recovery_capability": {
"type": "string",
"description": "Secret capability, returned at admission only. Send in X-Mekler-Scan-Capability; never in a URL."
},
"report_id": {
"type": "string",
"description": "Opaque public report identifier, present after payment confirmation."
},
"error": {
"type": "string",
"description": "Stable safe error code."
},
"purchase_id": {
"type": "string",
"description": "Payment recovery reference, visible only with capability."
}
}
},
"example": {
"error": "invalid_request"
}
}
}
},
"410": {
"description": "Expired job/artifact, no charge or new work.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"job_id",
"state",
"flow"
],
"properties": {
"job_id": {
"type": "string",
"description": "Opaque job identifier. Retain with the recovery capability."
},
"state": {
"type": "string",
"enum": [
"queued",
"running",
"result-ready",
"settlement-pending",
"complete",
"failed-uncharged",
"expired-uncharged",
"reconciliation-required"
]
},
"flow": {
"enum": [
"compute-then-pay",
"quote-first-async"
]
},
"retry_after": {
"type": "integer"
},
"recovery_capability": {
"type": "string",
"description": "Secret capability, returned at admission only. Send in X-Mekler-Scan-Capability; never in a URL."
},
"report_id": {
"type": "string",
"description": "Opaque public report identifier, present after payment confirmation."
},
"error": {
"type": "string",
"description": "Stable safe error code."
},
"purchase_id": {
"type": "string",
"description": "Payment recovery reference, visible only with capability."
}
}
},
"example": {
"error": "invalid_request"
}
}
}
},
"429": {
"description": "Unpaid admission limit; retry after indicated delay.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "invalid_request"
}
}
}
},
"503": {
"description": "Unavailable; retry identical request and original proof.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "invalid_request"
}
}
}
},
"413": {
"description": "Request exceeds 64 KiB.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "Use application/json.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "application_json_required"
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "PAYMENT-SIGNATURE",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Buyer-authorized x402 proof; never forwarded to the scanned service."
},
{
"name": "X-Mekler-Scan-Capability",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Recovery secret issued at admission."
}
]Search x402 service listings
GET /v1/services/listings/search-listings
Follow the authentication, capability and prerequisite requirements below.
Find x402 services imported from attributed catalogs or scanned by Mekler. Filter by task text, host, category, network, source, tier, grade or owner control. Unknown grades, prices and health remain unknown. Payment-ready means a recent valid unsigned challenge; it does not certify useful paid delivery. Immutable cursors retain ordering while current privacy controls still apply.
Response status
200- Successful response. Examples use synthetic identifiers; retain actual returned values.
400- Invalid input. No charge.
403- Invalid, revoked, stale or expired ownership credential.
404- Listing or proof not found.
409- Conflicting idempotency, revision or proof. Keep the original payment.
410- Expired proof, cursor or stored result. Never replace a pending payment.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Per-IP request quota; retry after 60 seconds.
503- Temporary failure. Retry the identical input and original proof.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Successful response. Examples use synthetic identifiers; retain actual returned values.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"listings": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"listing_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"first_seen": {
"type": "integer"
},
"scan_count": {
"type": "integer",
"minimum": 0
},
"at": {
"type": "integer"
},
"report_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"grade": {
"type": [
"string",
"null"
],
"enum": [
"A",
"B",
"C",
"D",
"F",
null
]
},
"score": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 100
},
"owner_verified": {
"type": "boolean"
},
"branding": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500
},
"category": {
"type": "string",
"enum": [
"data",
"research",
"web",
"compute",
"finance",
"email",
"images",
"other"
]
},
"icon_url": {
"type": "string",
"format": "uri"
},
"image_url": {
"type": "string",
"format": "uri"
}
},
"required": [],
"additionalProperties": false
},
"branding_verified": {
"const": false
},
"branding_provenance": {
"type": "object",
"properties": {
"identity_reviewed": {
"type": "boolean"
},
"claims_verified": {
"const": false
},
"source": {
"type": [
"string",
"null"
]
},
"reviewed_at": {
"type": [
"integer",
"null"
]
}
},
"required": [
"identity_reviewed",
"claims_verified",
"source",
"reviewed_at"
],
"additionalProperties": false
},
"origin": {
"type": [
"string",
"null"
]
},
"category": {
"type": [
"string",
"null"
]
},
"source": {
"enum": [
"mekler-conformance",
"x402-list"
]
},
"provenance": {
"type": "object",
"properties": {
"scoring": {
"type": [
"string",
"null"
]
},
"paid_delivery_verified": {
"const": false
}
},
"required": [
"scoring",
"paid_delivery_verified"
],
"additionalProperties": false
},
"featured": {
"type": "boolean"
},
"sources": {
"type": "array",
"items": {
"type": "object"
}
},
"networks": {
"type": "array",
"items": {
"type": "string"
}
},
"tier": {
"enum": [
"unverified",
"payment-ready",
"delivery-verified"
]
},
"health": {
"type": "object"
},
"external_traffic": {
"type": "object"
},
"tasks": {
"type": "array",
"maxItems": 32,
"items": {
"type": "string",
"maxLength": 40
}
},
"routes": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object"
}
},
"route_count": {
"type": "integer",
"minimum": 0,
"maximum": 50
},
"monitoring_route_limit": {
"const": 50
},
"monitoring_routes_truncated": {
"type": "boolean"
},
"min_listed_price_usd": {
"type": [
"string",
"null"
]
}
},
"required": [
"listing_id",
"first_seen",
"scan_count",
"at",
"report_id",
"grade",
"score",
"owner_verified",
"branding",
"branding_verified",
"branding_provenance",
"origin",
"category",
"source",
"provenance",
"featured"
],
"additionalProperties": false
}
},
"total": {
"type": "integer"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"snapshot_at": {
"type": "integer"
},
"featured_policy": {
"type": [
"string",
"null"
]
}
},
"required": [
"listings",
"total",
"next_cursor",
"snapshot_at",
"featured_policy"
],
"additionalProperties": false
},
"example": {
"listings": [],
"total": 0,
"next_cursor": null,
"snapshot_at": 0,
"featured_policy": "A within 30 days; at least two scans spanning one day; recency ordering; no paid influence"
}
}
}
},
"400": {
"description": "Invalid input. No charge."
},
"403": {
"description": "Invalid, revoked, stale or expired ownership credential."
},
"404": {
"description": "Listing or proof not found."
},
"409": {
"description": "Conflicting idempotency, revision or proof. Keep the original payment."
},
"410": {
"description": "Expired proof, cursor or stored result. Never replace a pending payment."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Per-IP request quota; retry after 60 seconds."
},
"503": {
"description": "Temporary failure. Retry the identical input and original proof."
}
}Complete schema: parameters and headers
[
{
"name": "text",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 100
}
},
{
"name": "host",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 100
}
},
{
"name": "category",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"data",
"research",
"web",
"compute",
"finance",
"email",
"images",
"other"
]
}
},
{
"name": "grade",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"A",
"B",
"C",
"D",
"F"
]
}
},
{
"name": "owner_verified",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "featured",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"recency",
"grade",
"uptime",
"price"
],
"default": "recency"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048
}
},
{
"in": "query",
"name": "network",
"required": false,
"schema": {
"type": "string",
"maxLength": 100
}
},
{
"in": "query",
"name": "source",
"required": false,
"schema": {
"type": "string",
"maxLength": 100
}
},
{
"in": "query",
"name": "tier",
"required": false,
"schema": {
"type": "string",
"enum": [
"unverified",
"payment-ready",
"delivery-verified"
]
}
},
{
"in": "query",
"name": "include_delisted",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
]Retrieve a service listing
GET /v1/services/listings/retrieve-listing
Follow the authentication, capability and prerequisite requirements below.
Read one visible directory listing, attributed source assertions, measured reachability, endpoint offers and available linter grades. Imports start ungraded; identity-reviewed business wording does not verify seller claims or paid delivery.
Response status
200- Successful response. Examples use synthetic identifiers; retain actual returned values.
400- Invalid input. No charge.
403- Invalid, revoked, stale or expired ownership credential.
404- Listing or proof not found.
409- Conflicting idempotency, revision or proof. Keep the original payment.
410- Expired proof, cursor or stored result. Never replace a pending payment.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Per-IP request quota; retry after 60 seconds.
503- Temporary failure. Retry the identical input and original proof.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Successful response. Examples use synthetic identifiers; retain actual returned values.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"listing_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"first_seen": {
"type": "integer"
},
"scan_count": {
"type": "integer",
"minimum": 0
},
"at": {
"type": "integer"
},
"report_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"grade": {
"type": [
"string",
"null"
],
"enum": [
"A",
"B",
"C",
"D",
"F",
null
]
},
"score": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 100
},
"owner_verified": {
"type": "boolean"
},
"branding": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500
},
"category": {
"type": "string",
"enum": [
"data",
"research",
"web",
"compute",
"finance",
"email",
"images",
"other"
]
},
"icon_url": {
"type": "string",
"format": "uri"
},
"image_url": {
"type": "string",
"format": "uri"
}
},
"required": [],
"additionalProperties": false
},
"branding_verified": {
"const": false
},
"branding_provenance": {
"type": "object",
"properties": {
"identity_reviewed": {
"type": "boolean"
},
"claims_verified": {
"const": false
},
"source": {
"type": [
"string",
"null"
]
},
"reviewed_at": {
"type": [
"integer",
"null"
]
}
},
"required": [
"identity_reviewed",
"claims_verified",
"source",
"reviewed_at"
],
"additionalProperties": false
},
"origin": {
"type": [
"string",
"null"
]
},
"category": {
"type": [
"string",
"null"
]
},
"source": {
"enum": [
"mekler-conformance",
"x402-list"
]
},
"provenance": {
"type": "object",
"properties": {
"scoring": {
"type": [
"string",
"null"
]
},
"paid_delivery_verified": {
"const": false
}
},
"required": [
"scoring",
"paid_delivery_verified"
],
"additionalProperties": false
},
"featured": {
"type": "boolean"
},
"compliance": {
"type": "object"
},
"grade_history": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"at": {
"type": "integer"
},
"grade": {
"type": [
"string",
"null"
],
"enum": [
"A",
"B",
"C",
"D",
"F",
null
]
},
"score": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 100
}
},
"required": [
"at",
"grade",
"score"
],
"additionalProperties": false
}
},
"history_limit": {
"const": 100
},
"history_truncated": {
"type": "boolean"
},
"sources": {
"type": "array",
"items": {
"type": "object"
}
},
"networks": {
"type": "array",
"items": {
"type": "string"
}
},
"tier": {
"enum": [
"unverified",
"payment-ready",
"delivery-verified"
]
},
"health": {
"type": "object"
},
"external_traffic": {
"type": "object"
},
"tasks": {
"type": "array",
"maxItems": 32,
"items": {
"type": "string",
"maxLength": 40
}
},
"routes": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object"
}
},
"route_count": {
"type": "integer",
"minimum": 0,
"maximum": 50
},
"monitoring_route_limit": {
"const": 50
},
"monitoring_routes_truncated": {
"type": "boolean"
},
"min_listed_price_usd": {
"type": [
"string",
"null"
]
}
},
"required": [
"listing_id",
"first_seen",
"scan_count",
"at",
"report_id",
"grade",
"score",
"owner_verified",
"branding",
"branding_verified",
"branding_provenance",
"origin",
"category",
"source",
"provenance",
"featured",
"compliance",
"grade_history",
"history_limit",
"history_truncated"
],
"additionalProperties": false
},
"example": {
"listing_id": "0000000000000000000000000000000000000000000000000000000000000000",
"first_seen": 1800000000,
"scan_count": 1,
"at": 1800000000,
"report_id": "0000000000000000000000000000000000000000000000000000000000000000",
"grade": "B",
"score": 80,
"owner_verified": false,
"branding": {},
"branding_verified": false,
"branding_provenance": {
"identity_reviewed": false,
"claims_verified": false,
"source": null,
"reviewed_at": null
},
"origin": null,
"category": "other",
"source": "mekler-conformance",
"provenance": {
"scoring": "mekler-linter-v1",
"paid_delivery_verified": false
},
"featured": false,
"compliance": {
"score": 100,
"grade": "A",
"evaluated": 14,
"total": 14,
"provisional": false,
"rules_version": "mekler-2026-10-07.1"
},
"grade_history": [
{
"at": 1800000000,
"grade": "B",
"score": 80
}
],
"history_limit": 100,
"history_truncated": false
}
}
}
},
"400": {
"description": "Invalid input. No charge."
},
"403": {
"description": "Invalid, revoked, stale or expired ownership credential."
},
"404": {
"description": "Listing or proof not found."
},
"409": {
"description": "Conflicting idempotency, revision or proof. Keep the original payment."
},
"410": {
"description": "Expired proof, cursor or stored result. Never replace a pending payment."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Per-IP request quota; retry after 60 seconds."
},
"503": {
"description": "Temporary failure. Retry the identical input and original proof."
}
}Complete schema: parameters and headers
[
{
"name": "listing_id",
"in": "query",
"required": true,
"schema": {
"type": "string",
"maxLength": 258,
"description": "Visible listing identity, its unique 16-character public reference, or exact service host including an optional port. Hidden, unknown and ambiguous references return 404."
}
}
]Start a domain ownership proof
POST /v1/services/listings/start-ownership-proof
Follow the authentication, capability and prerequisite requirements below.
Start a one-hour domain challenge bound to your private random 32-byte requester key in lowercase hex. Publish the returned JSON exactly at its HTTPS well-known URL. Keep the requester key private. An imported directory listing or completed scan is required before confirmation. No payment or target credentials are sent. Optionally supply contact_email and email_consent true for transactional verification/recovery/outcome messages. Contact stays private and must be verified by a mailed code after domain confirmation. No message is sent before successful domain proof.
Input fields
originRequired · string- See the complete request schema for values and bounds.
requester_keyRequired · string or null- See the complete request schema for values and bounds.
contact_emailOptional · string- See the complete request schema for values and bounds.
email_consentOptional · boolean- See the complete request schema for values and bounds.
Response status
200- Successful response. Examples use synthetic identifiers; retain actual returned values.
400- Invalid input. No charge.
403- Invalid, revoked, stale or expired ownership credential.
404- Listing or proof not found.
409- Conflicting idempotency, revision or proof. Keep the original payment.
410- Expired proof, cursor or stored result. Never replace a pending payment.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Per-IP request quota; retry after 60 seconds.
503- Temporary failure. Retry the identical input and original proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"requester_key": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"contact_email": {
"type": "string",
"format": "email",
"maxLength": 254
},
"email_consent": {
"const": true,
"type": "boolean"
}
},
"required": [
"origin",
"requester_key"
],
"additionalProperties": false,
"dependentRequired": {
"contact_email": [
"email_consent"
],
"email_consent": [
"contact_email"
]
}
},
"example": {
"origin": "https://api.mekler.ai",
"requester_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Successful response. Examples use synthetic identifiers; retain actual returned values.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"challenge_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"listing_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"expires_at": {
"type": "integer"
},
"url": {
"type": "string",
"format": "uri"
},
"document": {
"type": "object",
"properties": {
"version": {
"const": 1
},
"challenge_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"requester_hash": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"version",
"challenge_id",
"requester_hash"
],
"additionalProperties": false
},
"contact_status": {
"type": "string",
"enum": [
"pending_domain_proof",
"verification_required",
"verified"
]
},
"contact_code_expires_at": {
"type": [
"integer",
"null"
]
}
},
"required": [
"challenge_id",
"listing_id",
"expires_at",
"url",
"document"
],
"additionalProperties": false
},
"example": {
"challenge_id": "0000000000000000000000000000000000000000000000000000000000000000",
"listing_id": "0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": 1800003600,
"url": "https://api.mekler.ai/.well-known/mekler-conformance-challenge",
"document": {
"version": 1,
"challenge_id": "0000000000000000000000000000000000000000000000000000000000000000",
"requester_hash": "0000000000000000000000000000000000000000000000000000000000000000"
}
}
}
}
},
"400": {
"description": "Invalid input. No charge."
},
"403": {
"description": "Invalid, revoked, stale or expired ownership credential."
},
"404": {
"description": "Listing or proof not found."
},
"409": {
"description": "Conflicting idempotency, revision or proof. Keep the original payment."
},
"410": {
"description": "Expired proof, cursor or stored result. Never replace a pending payment."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Per-IP request quota; retry after 60 seconds."
},
"503": {
"description": "Temporary failure. Retry the identical input and original proof."
}
}Complete schema: parameters and headers
[]
Confirm a domain ownership proof
POST /v1/services/listings/confirm-ownership-proof
Follow the authentication, capability and prerequisite requirements below.
Confirm a one-hour domain challenge with the same private requester key. Exact HTTPS origin and path must match. Returns a 90 day listing-control credential; identical retries recover that grant. A new proof revokes prior credentials. Confirmation does not approve branding or change grades. For a pending private contact, retry the original challenge_id/requester_key with contact_code. For a correction, use update_id and its private requester_key; an exact update-bound domain file queues review without publishing the proposed fields.
Input fields
challenge_idOptional · string or null- See the complete request schema for values and bounds.
requester_keyOptional · string or null- See the complete request schema for values and bounds.
contact_codeOptional · string- See the complete request schema for values and bounds.
update_idOptional · string- See the complete request schema for values and bounds.
Response status
200- Successful response. Examples use synthetic identifiers; retain actual returned values.
400- Invalid input. No charge.
403- Invalid, revoked, stale or expired ownership credential.
404- Listing or proof not found.
409- Conflicting idempotency, revision or proof. Keep the original payment.
410- Expired proof, cursor or stored result. Never replace a pending payment.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Per-IP request quota; retry after 60 seconds.
503- Temporary failure. Retry the identical input and original proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"challenge_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"requester_key": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"contact_code": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"update_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [],
"additionalProperties": false,
"oneOf": [
{
"required": [
"challenge_id",
"requester_key"
],
"not": {
"required": [
"update_id"
]
}
},
{
"required": [
"update_id",
"requester_key"
],
"not": {
"anyOf": [
{
"required": [
"challenge_id"
]
},
{
"required": [
"contact_code"
]
}
]
}
}
]
},
"example": {
"challenge_id": "0000000000000000000000000000000000000000000000000000000000000000",
"requester_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Successful response. Examples use synthetic identifiers; retain actual returned values.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"listing_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"control_credential": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"expires_at": {
"type": "integer"
},
"revision": {
"type": "integer"
},
"contact_status": {
"type": "string",
"enum": [
"pending_domain_proof",
"verification_required",
"verified"
]
},
"contact_code_expires_at": {
"type": [
"integer",
"null"
]
}
},
"required": [
"listing_id",
"control_credential",
"expires_at",
"revision"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"state": {
"type": "string"
},
"review_deadline": {
"type": "integer"
}
},
"required": [
"request_id",
"state",
"review_deadline"
],
"additionalProperties": false
}
]
},
"example": {
"listing_id": "0000000000000000000000000000000000000000000000000000000000000000",
"control_credential": "0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": 1807776000,
"revision": 1
}
}
}
},
"400": {
"description": "Invalid input. No charge."
},
"403": {
"description": "Invalid, revoked, stale or expired ownership credential."
},
"404": {
"description": "Listing or proof not found."
},
"409": {
"description": "Conflicting idempotency, revision or proof. Keep the original payment."
},
"410": {
"description": "Expired proof, cursor or stored result. Never replace a pending payment."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Per-IP request quota; retry after 60 seconds."
},
"503": {
"description": "Temporary failure. Retry the identical input and original proof."
}
}Complete schema: parameters and headers
[]
Update listing visibility and branding preferences
POST /v1/services/listings/update-listing-preferences
Follow the authentication, capability and prerequisite requirements below.
Use X-Mekler-Listing-Control and the expected revision to hide a listing, suppress branding or revoke access. Domain proof is rechecked after seven days; failed, stale, revoked or expired credentials deny control. Concurrent writes return 409. Suppression affects current reads, new exports/feed pages and old search cursors; previously purchased snapshots remain recoverable.
Input fields
listing_idRequired · string or null- See the complete request schema for values and bounds.
revisionRequired · integer- See the complete request schema for values and bounds.
hiddenOptional · boolean- See the complete request schema for values and bounds.
suppress_brandingOptional · boolean- See the complete request schema for values and bounds.
revokeOptional · boolean- See the complete request schema for values and bounds.
Response status
200- Successful response. Examples use synthetic identifiers; retain actual returned values.
400- Invalid input. No charge.
403- Invalid, revoked, stale or expired ownership credential.
404- Listing or proof not found.
409- Conflicting idempotency, revision or proof. Keep the original payment.
410- Expired proof, cursor or stored result. Never replace a pending payment.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Per-IP request quota; retry after 60 seconds.
503- Temporary failure. Retry the identical input and original proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"listing_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"revision": {
"type": "integer",
"minimum": 0
},
"hidden": {
"type": "boolean"
},
"suppress_branding": {
"type": "boolean"
},
"revoke": {
"type": "boolean"
}
},
"required": [
"listing_id",
"revision"
],
"additionalProperties": false
},
"example": {
"listing_id": "0000000000000000000000000000000000000000000000000000000000000000",
"revision": 1,
"suppress_branding": true
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Successful response. Examples use synthetic identifiers; retain actual returned values.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"listing_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"revision": {
"type": "integer"
},
"hidden": {
"type": "boolean"
},
"suppress_branding": {
"type": "boolean"
},
"credential_revoked": {
"type": "boolean"
}
},
"required": [
"listing_id",
"revision",
"hidden",
"suppress_branding",
"credential_revoked"
],
"additionalProperties": false
},
"example": {
"listing_id": "0000000000000000000000000000000000000000000000000000000000000000",
"revision": 2,
"hidden": false,
"suppress_branding": true,
"credential_revoked": false
}
}
}
},
"400": {
"description": "Invalid input. No charge."
},
"403": {
"description": "Invalid, revoked, stale or expired ownership credential."
},
"404": {
"description": "Listing or proof not found."
},
"409": {
"description": "Conflicting idempotency, revision or proof. Keep the original payment."
},
"410": {
"description": "Expired proof, cursor or stored result. Never replace a pending payment."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Per-IP request quota; retry after 60 seconds."
},
"503": {
"description": "Temporary failure. Retry the identical input and original proof."
}
}Complete schema: parameters and headers
[
{
"name": "X-Mekler-Listing-Control",
"in": "header",
"required": true,
"schema": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
}
}
]Export the service catalog
POST /v1/services/listings/export-listings
0.25 USDC per catalog export
Service scope, examples and recovery →
Export up to 10000 visible x402 directory services with attributed source facts, measured health and grade history, first seen, scan counts, provenance and explicit truncation. Returns gzip+base64 JSON and a digest; large results use a 60 second signed download URL. Costs 0.25 USDC on Base or Solana. Reuse the original body and payment proof for exact 30 day result recovery.
Input fields
idempotency_keyRequired · string- See the complete request schema for values and bounds.
Response status
200- Successful response. Examples use synthetic identifiers; retain actual returned values.
400- Invalid input. No charge.
403- Invalid, revoked, stale or expired ownership credential.
404- Listing or proof not found.
409- Conflicting idempotency, revision or proof. Keep the original payment.
410- Expired proof, cursor or stored result. Never replace a pending payment.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Per-IP request quota; retry after 60 seconds.
503- Temporary failure. Retry the identical input and original proof.
202- Settlement pending. Retry the identical body and original proof; no replacement payment.
402- Genuine payable offer for valid fast input, or for a result-ready default job with capability. Empty input remains nonpayable discovery preflight. Quotes expire in 120 seconds; rail authorization may expire sooner.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"idempotency_key": {
"type": "string",
"minLength": 22,
"maxLength": 128,
"pattern": "^[A-Za-z0-9_-]{22,128}$"
}
},
"required": [
"idempotency_key"
],
"additionalProperties": false
},
"example": {
"idempotency_key": "example-export-request-0001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Successful response. Examples use synthetic identifiers; retain actual returned values.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"const": "ok"
},
"content_encoding": {
"const": "gzip+base64"
},
"content_type": {
"const": "application/json"
},
"content": {
"type": "string",
"maxLength": 4000000
},
"delivery": {
"const": "download"
},
"download_url": {
"type": "string",
"format": "uri"
},
"download_expires_in": {
"const": 60
},
"artifact_sha256": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"sha256": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"records": {
"type": "integer",
"maximum": 10000
},
"total": {
"type": "integer"
},
"cap": {
"const": 10000
},
"truncated": {
"type": "boolean"
},
"snapshot_at": {
"type": "integer"
}
},
"required": [
"status",
"content_encoding",
"content_type",
"sha256",
"records",
"total",
"cap",
"truncated",
"snapshot_at"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"content"
]
},
{
"required": [
"delivery",
"download_url",
"download_expires_in",
"artifact_sha256"
]
}
]
},
"example": {
"status": "ok",
"content_encoding": "gzip+base64",
"content_type": "application/json",
"content": "H4sIAAAAAAAA/01QXU7DMAy+ipXnboLXcgQEF0CochNvDcvsKHaGKsTdcTskyEsU+/vL9xUi1jA+PvgZwrlhomnJatLWKUrpV9YwvgWZldqN0oQWfmF+a5RG4X0IxRmZzxvUX7XJjRg5UhjDC10KtUOUa+1GCe5KaFlYnwDrDk4wd81MqpATsWVbwRcfFHccCJfV/Rp13TSfiSrYQpA5lp6cfnf5Lw5/KeBzIYaN7BnhhNE6Ftg/oUd4FZfKLR0qNrdNaKhkA0Rh8yggDeaGnDZuyZFY3VdBe60lUzpuPTBWXcS2dkavUQ2texlBLr41MSz73FrniN5CGE9YlL5/ANbTOd9+AQAA",
"sha256": "1b14bb641af5ff6e993a76f10685f0364b208aac7a9515e4449468f420de3bd3",
"records": 0,
"total": 0,
"cap": 10000,
"truncated": false,
"snapshot_at": 0
}
}
}
},
"400": {
"description": "Invalid input. No charge."
},
"403": {
"description": "Invalid, revoked, stale or expired ownership credential."
},
"404": {
"description": "Listing or proof not found."
},
"409": {
"description": "Conflicting idempotency, revision or proof. Keep the original payment."
},
"410": {
"description": "Expired proof, cursor or stored result. Never replace a pending payment."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Per-IP request quota; retry after 60 seconds."
},
"503": {
"description": "Temporary failure. Retry the identical input and original proof."
},
"202": {
"description": "Settlement pending. Retry the identical body and original proof; no replacement payment."
},
"402": {
"description": "Genuine payable offer for valid fast input, or for a result-ready default job with capability. Empty input remains nonpayable discovery preflight. Quotes expire in 120 seconds; rail authorization may expire sooner.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_required",
"price_usdc": "0.250000"
}
}
},
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 challenge. Sign only when the stored result is ready.",
"schema": {
"type": "string"
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "PAYMENT-SIGNATURE",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Buyer-authorized x402 proof; never forwarded to the scanned service."
},
{
"name": "X-Mekler-Scan-Capability",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Recovery secret issued at admission."
}
]Read x402 service grade changes
POST /v1/services/listings/list-grade-changes
0.01 USDC per grade-change page
Service scope, examples and recovery →
Read ordered new, grade_changed and rescanned events with previous grades and scores. Default 200, maximum 1000; signed watermark cursors. History retains 30 days or 50000 events; expired cursors return 410. Costs 0.01 USDC per page on Base or Solana. Use a fresh idempotency key per page; retain the original body and proof for exact recovery.
Input fields
idempotency_keyRequired · string- See the complete request schema for values and bounds.
cursorOptional · string- See the complete request schema for values and bounds.
limitOptional · integer- See the complete request schema for values and bounds.
Response status
200- Successful response. Examples use synthetic identifiers; retain actual returned values.
400- Invalid input. No charge.
403- Invalid, revoked, stale or expired ownership credential.
404- Listing or proof not found.
409- Conflicting idempotency, revision or proof. Keep the original payment.
410- Expired proof, cursor or stored result. Never replace a pending payment.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Per-IP request quota; retry after 60 seconds.
503- Temporary failure. Retry the identical input and original proof.
202- Settlement pending. Retry the identical body and original proof; no replacement payment.
402- Genuine payable offer for valid fast input, or for a result-ready default job with capability. Empty input remains nonpayable discovery preflight. Quotes expire in 120 seconds; rail authorization may expire sooner.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"idempotency_key": {
"type": "string",
"minLength": 22,
"maxLength": 128,
"pattern": "^[A-Za-z0-9_-]{22,128}$"
},
"cursor": {
"type": "string",
"maxLength": 2048
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 200
}
},
"required": [
"idempotency_key"
],
"additionalProperties": false
},
"example": {
"idempotency_key": "example-grade-request-0001",
"limit": 200
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Successful response. Examples use synthetic identifiers; retain actual returned values.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"const": "ok"
},
"events": {
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"properties": {
"sequence": {
"type": "integer",
"minimum": 1
},
"type": {
"enum": [
"new",
"grade_changed",
"rescanned"
]
},
"listing_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"at": {
"type": "integer"
},
"published_at": {
"type": "integer"
},
"scan_observed_at": {
"type": "integer"
},
"report_id": {
"type": [
"string",
"null"
],
"pattern": "^[a-f0-9]{64}$"
},
"grade": {
"type": [
"string",
"null"
],
"enum": [
"A",
"B",
"C",
"D",
"F",
null
]
},
"score": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 100
},
"previous_grade": {
"type": [
"string",
"null"
],
"enum": [
"A",
"B",
"C",
"D",
"F",
null
]
},
"previous_score": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 100
}
},
"required": [
"sequence",
"type",
"listing_id",
"at",
"published_at",
"scan_observed_at",
"report_id",
"grade",
"score",
"previous_grade",
"previous_score"
],
"additionalProperties": false
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"watermark": {
"type": "integer"
},
"retention_days": {
"const": 30
},
"event_cap": {
"const": 50000
},
"history_floor": {
"type": "integer"
}
},
"required": [
"status",
"events",
"has_more",
"next_cursor",
"watermark",
"retention_days",
"event_cap",
"history_floor"
],
"additionalProperties": false
},
"example": {
"status": "ok",
"events": [],
"has_more": false,
"next_cursor": "synthetic-cursor-replace-with-actual-response",
"watermark": 0,
"retention_days": 30,
"event_cap": 50000,
"history_floor": 0
}
}
}
},
"400": {
"description": "Invalid input. No charge."
},
"403": {
"description": "Invalid, revoked, stale or expired ownership credential."
},
"404": {
"description": "Listing or proof not found."
},
"409": {
"description": "Conflicting idempotency, revision or proof. Keep the original payment."
},
"410": {
"description": "Expired proof, cursor or stored result. Never replace a pending payment."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Per-IP request quota; retry after 60 seconds."
},
"503": {
"description": "Temporary failure. Retry the identical input and original proof."
},
"202": {
"description": "Settlement pending. Retry the identical body and original proof; no replacement payment."
},
"402": {
"description": "Genuine payable offer for valid fast input, or for a result-ready default job with capability. Empty input remains nonpayable discovery preflight. Quotes expire in 120 seconds; rail authorization may expire sooner.",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"error": "payment_required",
"price_usdc": "0.010000"
}
}
},
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 challenge. Sign only when the stored result is ready.",
"schema": {
"type": "string"
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "PAYMENT-SIGNATURE",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Buyer-authorized x402 proof; never forwarded to the scanned service."
},
{
"name": "X-Mekler-Scan-Capability",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Recovery secret issued at admission."
}
]List directory categories
GET /v1/services/listings/list-categories
Follow the authentication, capability and prerequisite requirements below.
Read categories present in visible identity-reviewed directory listings.
Response status
200- List directory categories
400- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
404- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
405- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
409- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
410- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
429- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
503- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "List directory categories",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"categories"
],
"additionalProperties": false
},
"example": {
"categories": [
"data"
]
}
}
}
},
"400": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"404": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"405": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"409": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"410": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"429": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"503": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
}
}Complete schema: parameters and headers
[]
List directory networks
GET /v1/services/listings/list-networks
Follow the authentication, capability and prerequisite requirements below.
Read canonical network identifiers in visible directory routes. Imported network claims are attributed and unverified until observed.
Response status
200- List directory networks
400- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
404- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
405- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
409- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
410- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
429- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
503- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "List directory networks",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"networks": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"networks"
],
"additionalProperties": false
},
"example": {
"networks": [
"eip155:8453"
]
}
}
}
},
"400": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"404": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"405": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"409": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"410": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"429": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"503": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
}
}Complete schema: parameters and headers
[]
Follow payment-offer changes
GET /v1/services/listings/list-offer-changes
Follow the authentication, capability and prerequisite requirements below.
Read changes observed in unsigned payment challenges. Before/after fingerprints preserve payout privacy. A drained cursor advances to new observations on later polls; retain it. No paid delivery is inferred.
Response status
200- Follow payment-offer changes
400- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
404- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
405- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
409- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
410- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
429- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
503- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Follow payment-offer changes",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"has_more": {
"type": "boolean"
},
"watermark": {
"type": "integer"
},
"snapshot_at": {
"type": "integer"
},
"retention_days": {
"type": "integer"
}
},
"required": [
"events",
"next_cursor",
"has_more",
"watermark",
"snapshot_at",
"retention_days"
],
"additionalProperties": false
},
"example": {
"events": [],
"next_cursor": "prepared-cursor-use-real-response",
"has_more": false,
"watermark": 0,
"snapshot_at": 0,
"retention_days": 30
}
}
}
},
"400": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"404": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"405": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"409": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"410": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"429": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"503": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
}
}Complete schema: parameters and headers
[
{
"in": "query",
"name": "listing_id",
"required": false,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
{
"in": "query",
"name": "since",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 100
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048
}
}
]Read measured service history
GET /v1/services/health/retrieve-listing-history
Follow the authentication, capability and prerequisite requirements below.
Page through Mekler uptime, latency or observed price history for one listing. Raw history retains 30 days; UTC daily aggregates are retained indefinitely. Unknown input/auth/rate-limit observations are excluded from uptime denominators. This is configuration/reachability evidence, not paid-delivery proof.
Response status
200- Read measured service history
400- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
404- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
405- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
409- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
410- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
429- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
503- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Read measured service history",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"observations": {
"type": "array",
"items": {
"type": "object"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"snapshot_at": {
"type": "integer"
},
"raw_retention_days": {
"type": "integer"
},
"coverage": {
"type": "string"
}
},
"required": [
"observations",
"next_cursor",
"snapshot_at",
"raw_retention_days",
"coverage"
],
"additionalProperties": false
},
"example": {
"observations": [],
"next_cursor": null,
"snapshot_at": 0,
"raw_retention_days": 30,
"coverage": "Mekler observations only; missing evidence is unknown."
}
}
}
},
"400": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"404": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"405": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"409": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"410": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"429": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"503": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
}
}Complete schema: parameters and headers
[
{
"in": "query",
"name": "listing_id",
"required": true,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
{
"in": "query",
"name": "route_id",
"required": false,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
{
"in": "query",
"name": "series",
"required": false,
"schema": {
"enum": [
"uptime",
"latency",
"price"
],
"default": "uptime"
}
},
{
"in": "query",
"name": "interval",
"required": false,
"schema": {
"enum": [
"raw",
"daily"
],
"default": "raw"
}
},
{
"in": "query",
"name": "since",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 100
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048
}
}
]Read directory health checks
GET /v1/services/health/retrieve-health-checks
Follow the authentication, capability and prerequisite requirements below.
Page through fixed safe monitoring observations for one listing or the whole visible catalog. Current hiding and attribution controls apply to retained history. No captured target body, contact or payout address is returned.
Response status
200- Read directory health checks
400- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
404- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
405- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
409- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
410- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
429- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
503- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Read directory health checks",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"observations": {
"type": "array",
"items": {
"type": "object"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"snapshot_at": {
"type": "integer"
},
"raw_retention_days": {
"type": "integer"
},
"coverage": {
"type": "string"
}
},
"required": [
"observations",
"next_cursor",
"snapshot_at",
"raw_retention_days",
"coverage"
],
"additionalProperties": false
},
"example": {
"observations": [],
"next_cursor": null,
"snapshot_at": 0,
"raw_retention_days": 30,
"coverage": "Mekler observations only; missing evidence is unknown."
}
}
}
},
"400": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"404": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"405": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"409": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"410": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"429": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"503": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
}
}Complete schema: parameters and headers
[
{
"in": "query",
"name": "listing_id",
"required": false,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
{
"in": "query",
"name": "route_id",
"required": false,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
{
"in": "query",
"name": "since",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 100
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048
}
}
]Read directory status
GET /v1/services/health/summarize-directory-status
Follow the authentication, capability and prerequisite requirements below.
Read measured online, degraded, offline and unknown states, delisted count and latest completed monitoring cycle. Missing checks remain unknown; this does not certify paid delivery.
Response status
200- Read directory status
400- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
404- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
405- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
409- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
410- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
429- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
503- Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "Read directory status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"listings": {
"type": "integer"
},
"states": {
"type": "object"
},
"delisted": {
"type": "integer"
},
"snapshot_at": {
"type": "integer"
},
"cadence_seconds": {
"type": "integer"
},
"latest_cycle_at": {
"type": [
"integer",
"null"
]
},
"paid_delivery_verified": {
"type": "boolean"
},
"matrix": {
"type": "array",
"items": {
"type": "object"
}
},
"checks_today": {
"type": "integer"
},
"unknown_checks_today": {
"type": "integer"
},
"imported_origins": {
"type": "integer"
},
"attribution_review_pending": {
"type": "integer"
}
},
"required": [
"listings",
"states",
"delisted",
"snapshot_at",
"cadence_seconds",
"latest_cycle_at",
"paid_delivery_verified",
"matrix",
"checks_today",
"unknown_checks_today",
"imported_origins",
"attribution_review_pending"
],
"additionalProperties": false
},
"example": {
"listings": 0,
"states": {
"online": 0,
"degraded": 0,
"offline": 0,
"unknown": 0
},
"delisted": 0,
"snapshot_at": 0,
"cadence_seconds": 900,
"latest_cycle_at": null,
"paid_delivery_verified": false,
"matrix": [],
"checks_today": 0,
"unknown_checks_today": 0,
"imported_origins": 0,
"attribution_review_pending": 0
}
}
}
},
"400": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"404": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"405": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"409": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"410": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"429": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
},
"503": {
"description": "Validation, missing/private data, method, cursor, quota or temporary availability error; no payment required."
}
}Complete schema: parameters and headers
[]
Request or inspect a listing correction
POST /v1/services/listings/request-listing-update
Follow the authentication, capability and prerequisite requirements below.
Request a free reviewed listing correction with X-Mekler-Listing-Control, current revision, a fresh private requester_key and exact changes. Reuse that same requester_key and identical body after an uncertain response; it pins one request, and changed input conflicts. A verified private email is required. Name/description/category, a same-origin website URL and the full replacement active endpoint list (up to 50 GET/POST paths) are supported. Publish the returned change-bound HTTPS verification file and confirm update_id within 72 hours through confirm-ownership-proof. Confirmation queues review; it never publishes raw submitted text. Pending reviews expire after seven days with a private outcome. Removed-route history is retained. action status with listing_id or origin reads private controls; optional request_id reads that correction outcome. Private data never enters public directory projections.
Input fields
actionOptional · See complete schema- See the complete request schema for values and bounds.
listing_idOptional · string- See the complete request schema for values and bounds.
originOptional · string- See the complete request schema for values and bounds.
request_idOptional · string- See the complete request schema for values and bounds.
revisionOptional · integer- See the complete request schema for values and bounds.
requester_keyOptional · string- See the complete request schema for values and bounds.
changesOptional · object- See the complete request schema for values and bounds.
Response status
200- Private status, confirmation or recoverable result.
202- Uniform recovery-request acknowledgment; does not prove a contact exists or email delivery.
400- Invalid input.
403- Invalid, revoked or expired private capability.
404- Unavailable private request.
409- Revision or ownership conflict.
410- Expired code or proof.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Request quota exceeded; retry later.
503- Temporary failure; retain the same request and private access details.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"enum": [
"status"
]
},
"listing_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"origin": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"revision": {
"type": "integer",
"minimum": 0
},
"requester_key": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"changes": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"category": {
"enum": [
"data",
"research",
"web",
"compute",
"finance",
"email",
"images",
"other"
]
},
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"routes": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object",
"properties": {
"method": {
"enum": [
"GET",
"POST"
]
},
"path": {
"type": "string",
"minLength": 1,
"maxLength": 1500
}
},
"required": [
"method",
"path"
],
"additionalProperties": false
}
}
},
"required": [],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false,
"oneOf": [
{
"required": [
"action"
],
"oneOf": [
{
"required": [
"listing_id"
],
"not": {
"required": [
"origin"
]
}
},
{
"required": [
"origin"
],
"not": {
"required": [
"listing_id"
]
}
}
]
},
{
"required": [
"listing_id",
"revision",
"requester_key",
"changes"
],
"not": {
"anyOf": [
{
"required": [
"action"
]
},
{
"required": [
"origin"
]
},
{
"required": [
"request_id"
]
}
]
}
}
]
},
"example": {
"action": "status",
"origin": "https://api.mekler.ai"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Private status, confirmation or recoverable result.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"listing_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"origin": {
"type": "string"
},
"revision": {
"type": "integer"
},
"contact_verified": {
"type": "boolean"
},
"contact_verification_pending": {
"type": "boolean"
},
"preferences": {
"type": "object"
},
"branding": {
"type": "object"
},
"expires_at": {
"type": "integer"
},
"website_url": {
"type": "string"
},
"routes": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object"
}
},
"request": {
"type": "object"
}
},
"required": [
"listing_id",
"origin",
"revision",
"contact_verified",
"preferences",
"branding",
"expires_at",
"website_url",
"routes"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"state": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"url": {
"type": "string"
},
"document": {
"type": "object"
}
},
"required": [
"request_id",
"state",
"expires_at",
"url",
"document"
],
"additionalProperties": false
}
]
},
"example": {
"listing_id": "0000000000000000000000000000000000000000000000000000000000000000",
"origin": "https://api.mekler.ai",
"revision": 1,
"contact_verified": true,
"preferences": {
"hidden": false,
"suppress_branding": false
},
"branding": {},
"expires_at": 1800000000,
"website_url": "https://api.mekler.ai",
"routes": []
}
}
}
},
"202": {
"description": "Uniform recovery-request acknowledgment; does not prove a contact exists or email delivery."
},
"400": {
"description": "Invalid input."
},
"403": {
"description": "Invalid, revoked or expired private capability."
},
"404": {
"description": "Unavailable private request."
},
"409": {
"description": "Revision or ownership conflict."
},
"410": {
"description": "Expired code or proof."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Request quota exceeded; retry later."
},
"503": {
"description": "Temporary failure; retain the same request and private access details."
}
}Complete schema: parameters and headers
[
{
"name": "X-Mekler-Listing-Control",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
}
]Recover listing control by verified email
POST /v1/services/listings/reissue-owner-token
Follow the authentication, capability and prerequisite requirements below.
Request one email-based ownership-credential replacement for an existing verified private contact. POST origin for a uniform 202 response whether eligible or not. POST the same origin and recovery_code to confirm within 15 minutes. Domain control and original ownership scope are checked; success replaces the prior credential without extending the original 90 day expiry. The code is single-use with idempotent recovery of the same replacement. Revoked/expired grants or changed domains need a fresh ownership proof. Never put a recovery code or control credential in a URL.
Input fields
originRequired · string- See the complete request schema for values and bounds.
recovery_codeOptional · string- See the complete request schema for values and bounds.
Response status
200- Private status, confirmation or recoverable result.
202- Uniform recovery-request acknowledgment; does not prove a contact exists or email delivery.
400- Invalid input.
403- Invalid, revoked or expired private capability.
404- Unavailable private request.
409- Revision or ownership conflict.
410- Expired code or proof.
413- Body exceeds 65536 bytes.
415- Use application/json.
429- Request quota exceeded; retry later.
503- Temporary failure; retain the same request and private access details.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"recovery_code": {
"type": "string",
"minLength": 1,
"maxLength": 20
}
},
"required": [
"origin"
],
"additionalProperties": false
},
"example": {
"origin": "https://api.mekler.ai"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Private status, confirmation or recoverable result.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"listing_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"control_credential": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"revision": {
"type": "integer"
},
"expires_at": {
"type": "integer"
}
},
"required": [
"listing_id",
"control_credential",
"revision",
"expires_at"
],
"additionalProperties": false
},
"example": {
"listing_id": "0000000000000000000000000000000000000000000000000000000000000000",
"control_credential": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"revision": 2,
"expires_at": 1800000000
}
}
}
},
"202": {
"description": "Uniform recovery-request acknowledgment; does not prove a contact exists or email delivery.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"const": "received"
},
"message": {
"type": "string"
}
},
"required": [
"status",
"message"
],
"additionalProperties": false
},
"example": {
"status": "received",
"message": "If eligible, the verified private contact receives a recovery code."
}
}
}
},
"400": {
"description": "Invalid input."
},
"403": {
"description": "Invalid, revoked or expired private capability."
},
"404": {
"description": "Unavailable private request."
},
"409": {
"description": "Revision or ownership conflict."
},
"410": {
"description": "Expired code or proof."
},
"413": {
"description": "Body exceeds 65536 bytes."
},
"415": {
"description": "Use application/json."
},
"429": {
"description": "Request quota exceeded; retry later."
},
"503": {
"description": "Temporary failure; retain the same request and private access details."
}
}Complete schema: parameters and headers
[]
Retrieve a private inference job and completed result
GET /v1/compute/inference/retrieve-result
Follow the authentication, capability and prerequisite requirements below.
Call only after generate-completions returns 202 or 200 with job_id and recovery_token. A 402 quote creates no job. Use exactly job_id in the query and recovery_token in X-Mekler-Recovery; examples are synthetic and cannot retrieve a live job. Pending work must be recovered with its original proof or capability, never a new payment.
Response status
200- All completions stored and delivered; receipt reports payment finality separately.
202- Still pending.
400- Query must contain exactly job_id; use the private recovery header. The response includes corrective guidance.
404- Unknown job or incorrect private capability.
410- Expired or uncharged failure.
Complete schema: request body
{}Complete schema: responses and errors
{
"200": {
"description": "All completions stored and delivered; receipt reports payment finality separately.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"state": {
"enum": [
"complete",
"delivered",
"delivered-payment-failed"
]
},
"plan": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"models": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"model": {
"enum": [
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
]
},
"provider_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"reasoning_effort": {
"enum": [
"none",
"low",
"high",
null
]
},
"input_token_allowance": {
"type": "integer",
"minimum": 1
},
"max_output_tokens": {
"type": "integer",
"minimum": 32,
"maximum": 4096
},
"response_format": {
"enum": [
"text",
"json_object"
]
},
"provider": {
"enum": [
"openai",
"bedrock_mantle"
]
},
"region": {
"const": "us-east-1"
},
"json_policy": {
"const": "strict-object-or-one-outer-fence-v1"
},
"qualification": {
"type": "object",
"properties": {
"policy": {
"const": "qualified-value-v1"
},
"profile": {
"enum": [
"extract_fields",
"classify"
]
},
"prompt_version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"evidence_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[0-9a-f]{64}$"
},
"observed_passed": {
"type": "integer",
"minimum": 0
},
"observed_total": {
"type": "integer",
"minimum": 60
},
"observed_p95_seconds": {
"type": "number",
"minimum": 0,
"maximum": 30
},
"qualified_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"selection_basis": {
"enum": [
"caller_pin",
"highest_observed_lower_bound",
"lowest_observed_p95",
"lowest_qualified_supplier_allowance"
]
},
"scope": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"policy",
"profile",
"prompt_version",
"evidence_id",
"observed_passed",
"observed_total",
"observed_p95_seconds",
"qualified_at",
"expires_at",
"selection_basis",
"scope"
],
"additionalProperties": false
}
},
"required": [
"index",
"model",
"provider_model",
"reason",
"reasoning_effort",
"input_token_allowance",
"max_output_tokens",
"response_format"
],
"additionalProperties": false
}
},
"price_micros": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"processing": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"output_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"delivery_policy": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"version",
"models",
"price_micros",
"processing",
"output_policy"
],
"additionalProperties": false
},
"recovery_token": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"expires_at": {
"type": "integer"
},
"retry": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"results": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 19
},
"model": {
"enum": [
"gpt-6-luna",
"gpt-6.1-sol",
"ministral-3-3b",
"ministral-3-8b",
"ministral-3-14b",
"nemotron-3-nano",
"qwen3-next",
"qwen3-coder-next",
"gemma-4-e2b"
]
},
"provider_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"reported_model": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 65536
},
"finish_reason": {
"const": "stop"
},
"usage": {
"type": "object",
"properties": {
"prompt_tokens": {
"type": "integer",
"minimum": 0
},
"completion_tokens": {
"type": "integer",
"minimum": 0
},
"total_tokens": {
"type": "integer",
"minimum": 0
}
},
"required": [
"prompt_tokens",
"completion_tokens",
"total_tokens"
],
"additionalProperties": false
},
"validation": {
"type": "object",
"properties": {
"profile": {
"enum": [
"extract_fields",
"classify"
]
},
"prompt_version": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"checks_passed": {
"type": "array",
"items": {
"enum": [
"json_shape",
"allowed_fields_or_labels",
"literal_source_evidence"
]
}
},
"semantic_correctness_guaranteed": {
"const": false
}
},
"required": [
"profile",
"prompt_version",
"checks_passed",
"semantic_correctness_guaranteed"
],
"additionalProperties": false
}
},
"required": [
"index",
"model",
"provider_model",
"reported_model",
"content",
"finish_reason",
"usage"
],
"additionalProperties": false
}
},
"receipt": {
"type": "object",
"properties": {
"network": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"transaction": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"price_micros": {
"type": "integer"
},
"finalized": {
"type": "boolean"
}
},
"required": [
"network",
"transaction",
"price_micros",
"finalized"
],
"additionalProperties": false
}
},
"required": [
"job_id",
"state",
"plan",
"recovery_token",
"expires_at",
"retry",
"results",
"receipt"
],
"additionalProperties": false
},
"example": {
"job_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "complete",
"plan": {
"version": "inference-v4-purchase",
"models": [
{
"index": 0,
"model": "gpt-6-luna",
"provider_model": "gpt-6-luna",
"reason": "bounded_general_task",
"reasoning_effort": "none",
"input_token_allowance": 326,
"max_output_tokens": 64,
"response_format": "text"
}
],
"price_micros": 2796,
"delivery_policy": "Stored results delivered after independently verified payment inclusion; finality reconciles separately.",
"processing": "OpenAI direct API; store=false; standard processing",
"output_policy": "Complete text or JSON object; refusals, truncation and any failed item are uncharged."
},
"recovery_token": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"expires_at": 1794528000,
"retry": "Recover with the original proof or private token. Do not pay again.",
"results": [
{
"index": 0,
"model": "gpt-6-luna",
"provider_model": "gpt-6-luna",
"reported_model": "gpt-6-luna",
"content": "The meeting starts at noon.",
"finish_reason": "stop",
"usage": {
"prompt_tokens": 18,
"completion_tokens": 7,
"total_tokens": 25
}
}
],
"receipt": {
"network": "eip155:8453",
"transaction": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"price_micros": 2796,
"finalized": true
}
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 x402 finalized payment receipt.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 16384
}
}
}
},
"202": {
"description": "Still pending."
},
"400": {
"description": "Query must contain exactly job_id; use the private recovery header. The response includes corrective guidance."
},
"404": {
"description": "Unknown job or incorrect private capability."
},
"410": {
"description": "Expired or uncharged failure."
}
}Complete schema: parameters and headers
[
{
"in": "query",
"name": "job_id",
"required": true,
"description": "Use job_id returned by your own admitted job; no other query parameters.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
{
"in": "header",
"name": "X-Mekler-Recovery",
"required": true,
"description": "Private recovery_token returned with job_id; keep out of URLs and logs.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
]Monitor paid API listing and buyer-query visibility
POST /v1/services/listings/check-listing-visibility
0.005 USDC per accepted request
Service scope, examples and recovery →
Monitor one paid API operation across x402scan, CDP Bazaar and Agentic Market. Check exact listing presence, one to three buyer queries and optional description drift. Return dated evidence, confirmed change alerts, private history and the next polling request. Partial coverage and timeouts stay unknown; no ranking or indexing guarantee.
Input fields
resourceRequired · string- Public HTTPS operation URL, no query, fragment, credentials, IP literal or nonstandard port.
methodOptional · string- See the complete request schema for values and bounds.
queriesRequired · array- See the complete request schema for values and bounds.
poll_idRequired · string- See the complete request schema for values and bounds.
merchantOptional · string- CDP merchant address for direct feed, not a payment destination.
market_slugOptional · string- See the complete request schema for values and bounds.
expectedOptional · object- See the complete request schema for values and bounds.
cursorOptional · string- Private authenticated continuation from the previous result. Must match resource, queries and settings.
Response status
200- Completed check; inspect unknown and not_found_at_queried_name before acting. X-Mekler-Payment-State reports settlement.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"resource",
"queries",
"poll_id"
],
"properties": {
"resource": {
"type": "string",
"format": "uri",
"maxLength": 1024,
"description": "Public HTTPS operation URL, no query, fragment, credentials, IP literal or nonstandard port."
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
],
"default": "POST"
},
"queries": {
"type": "array",
"minItems": 1,
"maxItems": 3,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 2,
"maxLength": 160
}
},
"poll_id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{16,64}$"
},
"merchant": {
"type": "string",
"pattern": "^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$",
"description": "CDP merchant address for direct feed, not a payment destination."
},
"market_slug": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{0,127}$"
},
"expected": {
"type": "object",
"additionalProperties": false,
"properties": {
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500
}
}
},
"cursor": {
"type": "string",
"minLength": 1,
"maxLength": 16000,
"description": "Private authenticated continuation from the previous result. Must match resource, queries and settings."
}
}
},
"example": {
"resource": "https://api.mekler.ai/v1/email/domains/check-mail-configuration",
"queries": [
"check email address syntax and domain MX records"
],
"merchant": "0xF6c6E2e530bb311c14a49C1a07C720fc232c07c5",
"market_slug": "api-mekler-ai",
"poll_id": "listing_monitor_example_01"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed check; inspect unknown and not_found_at_queried_name before acting. X-Mekler-Payment-State reports settlement.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"resource",
"checked_at",
"observations",
"alerts",
"history",
"monitoring",
"cost",
"limits"
],
"properties": {
"status": {
"const": "ok"
},
"resource": {
"type": "string"
},
"checked_at": {
"type": "integer"
},
"observations": {
"type": "array",
"maxItems": 12,
"items": {
"type": "object",
"required": [
"dimension",
"state",
"attempts"
],
"properties": {
"dimension": {
"type": "string"
},
"state": {
"enum": [
"found",
"missing",
"unknown"
]
},
"attempts": {
"type": "array",
"maxItems": 2,
"items": {
"type": "object"
}
}
}
}
},
"alerts": {
"type": "array",
"maxItems": 24,
"items": {
"type": "object",
"required": [
"dimension",
"kind",
"at"
],
"properties": {
"dimension": {
"type": "string"
},
"kind": {
"enum": [
"missing",
"drift",
"recovered"
]
},
"at": {
"type": "integer"
}
},
"additionalProperties": false
}
},
"history": {
"type": "array",
"maxItems": 20,
"items": {
"type": "object"
}
},
"monitoring": {
"type": "object",
"required": [
"mode",
"next_request",
"history_limit",
"history_expires_after_seconds"
],
"properties": {
"mode": {
"const": "agent_polling"
},
"next_request": {
"type": "object",
"additionalProperties": false,
"required": [
"resource",
"queries",
"poll_id"
],
"properties": {
"resource": {
"type": "string",
"format": "uri",
"maxLength": 1024,
"description": "Public HTTPS operation URL, no query, fragment, credentials, IP literal or nonstandard port."
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
],
"default": "POST"
},
"queries": {
"type": "array",
"minItems": 1,
"maxItems": 3,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 2,
"maxLength": 160
}
},
"poll_id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{16,64}$"
},
"merchant": {
"type": "string",
"pattern": "^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$",
"description": "CDP merchant address for direct feed, not a payment destination."
},
"market_slug": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{0,127}$"
},
"expected": {
"type": "object",
"additionalProperties": false,
"properties": {
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500
}
}
},
"cursor": {
"type": "string",
"minLength": 1,
"maxLength": 16000,
"description": "Private authenticated continuation from the previous result. Must match resource, queries and settings."
}
}
},
"history_limit": {
"const": 20
},
"history_expires_after_seconds": {
"const": 2592000
},
"recommended_interval_seconds": {
"const": 3600
}
},
"additionalProperties": false
},
"cost": {
"type": "object",
"required": [
"directory_attempts",
"request_limit",
"supplier_charge_usd",
"infrastructure_actual_usd"
],
"properties": {
"directory_attempts": {
"type": "integer",
"minimum": 1,
"maximum": 24
},
"request_limit": {
"const": 24
},
"supplier_charge_usd": {
"const": "0"
},
"infrastructure_actual_usd": {
"type": "null"
}
},
"additionalProperties": false
},
"limits": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"resource": "https://api.mekler.ai/v1/email/domains/check-mail-configuration",
"checked_at": 1792155600,
"observations": [
{
"directory": "x402scan",
"dimension": "x402scan:listing",
"query": null,
"source": "https://www.x402scan.com/api/trpc/public.resources.checkRegistered?input=%7B%22json%22%3A%7B%22resources%22%3A%5B%7B%22url%22%3A%22https%3A%2F%2Fapi.mekler.ai%2Fv1%2Femail%2Fdomains%2Fcheck-mail-configuration%22%2C%22method%22%3A%22POST%22%7D%5D%7D%7D",
"scope": "exact_operation",
"state": "found",
"position": null,
"metadata": "not_exposed",
"elapsed_ms": 0,
"confirmation": "not_needed",
"attempts": [
{
"directory": "x402scan",
"dimension": "x402scan:listing",
"query": null,
"source": "https://www.x402scan.com/api/trpc/public.resources.checkRegistered?input=%7B%22json%22%3A%7B%22resources%22%3A%5B%7B%22url%22%3A%22https%3A%2F%2Fapi.mekler.ai%2Fv1%2Femail%2Fdomains%2Fcheck-mail-configuration%22%2C%22method%22%3A%22POST%22%7D%5D%7D%7D",
"scope": "exact_operation",
"state": "found",
"position": null,
"metadata": "not_exposed",
"elapsed_ms": 0
}
],
"requests_started": 1
},
{
"directory": "cdp",
"dimension": "cdp:listing",
"query": null,
"source": "https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=0xF6c6E2e530bb311c14a49C1a07C720fc232c07c5&limit=100",
"scope": "exact_operation",
"state": "found",
"position": null,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0,
"confirmation": "not_needed",
"attempts": [
{
"directory": "cdp",
"dimension": "cdp:listing",
"query": null,
"source": "https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=0xF6c6E2e530bb311c14a49C1a07C720fc232c07c5&limit=100",
"scope": "exact_operation",
"state": "found",
"position": null,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0
}
],
"requests_started": 1
},
{
"directory": "agentic-market",
"dimension": "agentic-market:listing",
"query": null,
"source": "https://api.agentic.market/v1/services/api-mekler-ai",
"scope": "exact_operation",
"state": "found",
"position": null,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0,
"confirmation": "not_needed",
"attempts": [
{
"directory": "agentic-market",
"dimension": "agentic-market:listing",
"query": null,
"source": "https://api.agentic.market/v1/services/api-mekler-ai",
"scope": "exact_operation",
"state": "found",
"position": null,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0
}
],
"requests_started": 1
},
{
"directory": "x402scan",
"dimension": "x402scan:query:0",
"query": "check email address syntax and domain MX records",
"source": "https://www.x402scan.com/api/trpc/public.discover.search?input=%7B%22json%22%3A%7B%22query%22%3A%22check%20email%20address%20syntax%20and%20domain%20MX%20records%22%7D%7D",
"scope": "first_20_endpoint_results",
"state": "found",
"position": 1,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0,
"confirmation": "not_needed",
"attempts": [
{
"directory": "x402scan",
"dimension": "x402scan:query:0",
"query": "check email address syntax and domain MX records",
"source": "https://www.x402scan.com/api/trpc/public.discover.search?input=%7B%22json%22%3A%7B%22query%22%3A%22check%20email%20address%20syntax%20and%20domain%20MX%20records%22%7D%7D",
"scope": "first_20_endpoint_results",
"state": "found",
"position": 1,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0
}
],
"requests_started": 1
},
{
"directory": "cdp",
"dimension": "cdp:query:0",
"query": "check email address syntax and domain MX records",
"source": "https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?query=check+email+address+syntax+and+domain+MX+records&limit=20",
"scope": "first_20_endpoint_results",
"state": "found",
"position": 1,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0,
"confirmation": "not_needed",
"attempts": [
{
"directory": "cdp",
"dimension": "cdp:query:0",
"query": "check email address syntax and domain MX records",
"source": "https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?query=check+email+address+syntax+and+domain+MX+records&limit=20",
"scope": "first_20_endpoint_results",
"state": "found",
"position": 1,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0
}
],
"requests_started": 1
},
{
"directory": "agentic-market",
"dimension": "agentic-market:query:0",
"query": "check email address syntax and domain MX records",
"source": "https://api.agentic.market/v1/search/services?q=check+email+address+syntax+and+domain+MX+records&limit=24&offset=0",
"scope": "first_20_endpoint_results",
"state": "found",
"position": 1,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0,
"confirmation": "not_needed",
"attempts": [
{
"directory": "agentic-market",
"dimension": "agentic-market:query:0",
"query": "check email address syntax and domain MX records",
"source": "https://api.agentic.market/v1/search/services?q=check+email+address+syntax+and+domain+MX+records&limit=24&offset=0",
"scope": "first_20_endpoint_results",
"state": "found",
"position": 1,
"metadata": "not_requested",
"metadata_hash": "4ce3794e2105e40f00da1d1dc9ac99600f175ee200f0660c82eeaab49b3cf2d9",
"elapsed_ms": 0
}
],
"requests_started": 1
}
],
"alerts": [],
"history": [
{
"at": 1792155600,
"states": {
"x402scan:listing": "found",
"cdp:listing": "found",
"agentic-market:listing": "found",
"x402scan:query:0": "found",
"cdp:query:0": "found",
"agentic-market:query:0": "found"
},
"alerts": []
}
],
"monitoring": {
"mode": "agent_polling",
"recommended_interval_seconds": 3600,
"history_limit": 20,
"history_expires_after_seconds": 2592000,
"next_request": {
"resource": "https://api.mekler.ai/v1/email/domains/check-mail-configuration",
"queries": [
"check email address syntax and domain MX records"
],
"merchant": "0xF6c6E2e530bb311c14a49C1a07C720fc232c07c5",
"market_slug": "api-mekler-ai",
"poll_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"method": "POST",
"expected": {},
"cursor": "eHh4eHh4eHh4eHh4rn9f6ZudEuRdWGhZGZuOiElKS80Vcac9SuzQAnEPhJS6a1ZeJwy3ZckecVMviXGyySoraKV7Aj5a4DEF4ivYXA2ADwXHppO6fRhdV3kEws7mSu5Bw-5w0jl7x9EbGUUrL-3oKkwuo2MHo1XJ958ZXtKKScePbk-E8ZShSyeMqgqYsZnepAn36na22-8TQWZz8IN1JFnicUqwqKpJ_N4arbdQhRGL3vKouK3rPrePzotYkV2ua55V1XHBGS89gjBmSZj0K1bFJ6Xn6NoPAQiyGNDgqfgAq6ew0t066g-J_zYYa0UUXUmGIq-Pn7qrR9DUunlkmMz7W8I8W5TAqCJd2_LKb9sdvyZQDnGVPASNsKP674nFrrpZiXKRoKyQwUgFjx0yekXBJSXZ01Pf4nVXgHqQpDOCjH3NQRWtOmrYkOtK1tWrVZ17l-kakZALzLZcF1kFCBPrfU6NcLC9WEDcRyOiB-vFnrNZrYZW8Ad_eZ6pnvWOi77q9MfDyAagia72U2YUxjlnA4tZTETZnW0pR6_HjkpE_CmQ1W7iEaRb6YI1-kK5JHSr-V5ewVAG"
}
},
"cost": {
"directory_attempts": 6,
"request_limit": 24,
"supplier_charge_usd": "0",
"infrastructure_actual_usd": null
},
"limits": [
"API observations, not browser verification.",
"Search misses concern the checked window, never global delisting.",
"No directory edits, automatic scheduling, external messages or ranking guarantee."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]SEC Filing Lookup: Find SEC filings by company CIK, form and filing date
POST /v1/finance/filings/find-company-filings
0.005 USDC per accepted request
Service scope, examples and recovery →
Find SEC filings by company CIK, form and filing date. Return accession identifiers, amendment flags and canonical SEC links, newest first. Includes recent submissions and up to five relevant archived partitions with explicit unread-history coverage. Metadata only; no filing contents, ticker resolution or investment advice.
Input fields
cikRequired · string- Nonzero SEC central index key; leading zeros optional. Company identifiers only.
formsOptional · array- Exact form names; amendments such as 10-K/A are separate forms. Empty means all forms.
from_dateOptional · string- Inclusive filing date lower bound.
to_dateOptional · string- Inclusive filing date upper bound.
limitOptional · integer- See the complete request schema for values and bounds.
request_idRequired · string- Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"cik",
"request_id"
],
"properties": {
"cik": {
"type": "string",
"pattern": "^[0-9]{1,10}$",
"description": "Nonzero SEC central index key; leading zeros optional. Company identifiers only."
},
"forms": {
"type": "array",
"maxItems": 5,
"items": {
"type": "string",
"pattern": "^[A-Z0-9][A-Z0-9 /-]{0,19}$"
},
"default": [],
"description": "Exact form names; amendments such as 10-K/A are separate forms. Empty means all forms."
},
"from_date": {
"type": "string",
"format": "date",
"description": "Inclusive filing date lower bound."
},
"to_date": {
"type": "string",
"format": "date",
"description": "Inclusive filing date upper bound."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery."
}
}
},
"example": {
"cik": "320193",
"forms": [
"10-K",
"10-K/A"
],
"limit": 5,
"request_id": "sec-filing-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"cik",
"retrieved_at",
"filings",
"returned",
"coverage",
"source",
"selection_policy",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"cik": {
"type": "string"
},
"retrieved_at": {
"type": "string"
},
"filings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"accession",
"form",
"filed",
"report_date",
"is_amendment",
"filing_url",
"document_url"
],
"properties": {
"accession": {
"type": "string"
},
"form": {
"type": "string"
},
"filed": {
"type": "string"
},
"report_date": {
"type": [
"string",
"null"
]
},
"is_amendment": {
"type": "boolean"
},
"filing_url": {
"type": "string"
},
"document_url": {
"type": [
"string",
"null"
]
}
}
}
},
"returned": {
"type": "integer"
},
"coverage": {
"type": "object",
"additionalProperties": false,
"required": [
"complete_source_history",
"unread_history_files",
"history_files_read",
"matched_in_read_sources",
"result_limit_reached"
],
"properties": {
"complete_source_history": {
"type": "boolean"
},
"unread_history_files": {
"type": "integer"
},
"history_files_read": {
"type": "integer"
},
"matched_in_read_sources": {
"type": "integer"
},
"result_limit_reached": {
"type": "boolean"
}
}
},
"source": {
"type": "string"
},
"selection_policy": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"cik": "0000320193",
"retrieved_at": "2026-10-18T00:00:00Z",
"filings": [
{
"accession": "0000000001-26-000001",
"form": "10-K",
"filed": "2026-01-31",
"report_date": "2025-12-31",
"is_amendment": false,
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000000000126000001/0000000001-26-000001-index.html",
"document_url": "https://www.sec.gov/Archives/edgar/data/320193/000000000126000001/annual.htm"
}
],
"returned": 1,
"coverage": {
"complete_source_history": true,
"unread_history_files": 0,
"history_files_read": 0,
"matched_in_read_sources": 1,
"result_limit_reached": false
},
"source": "https://data.sec.gov/submissions/CIK0000320193.json",
"selection_policy": "filing-date-descending-accession-descending-v1",
"limitations": [
"Amendments are distinct filings; no inference of the latest legal state.",
"At most five relevant archive partitions are read; unread history is explicit.",
"Metadata only; no filing contents or investment advice."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]URL Inspection: Inspect a public URL for HTTP status, redirect chain, content type and reported size before downloading it
POST /v1/web/urls/check-reachability
0.003 USDC per accepted request
Service scope, examples and recovery →
Inspect a public URL for HTTP status, redirect chain, content type and reported size before downloading it. Uses HEAD with bounded GET fallback, DNS-pinned public-address checks and up to five redirects. Reports server-declared sizes separately from observed sample bytes. No full download, content safety verdict or uptime guarantee.
Input fields
urlRequired · string- Public HTTP(S) URL, standard port 80/443. Credentials/private addresses are rejected; robots restrictions apply.
request_idRequired · string- Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"url",
"request_id"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"description": "Public HTTP(S) URL, standard port 80/443. Credentials/private addresses are rejected; robots restrictions apply."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery."
}
}
},
"example": {
"url": "https://mekler.ai/",
"request_id": "url-inspection-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"requested_url",
"final_url",
"outcome",
"http_status",
"redirects",
"content_type",
"reported_size_bytes",
"size_basis",
"sample_bytes_observed",
"sample_truncated",
"observed_at",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"requested_url": {
"type": "string"
},
"final_url": {
"type": "string"
},
"outcome": {
"type": "string"
},
"http_status": {
"type": [
"integer",
"null"
]
},
"redirects": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"url",
"status",
"method"
],
"properties": {
"url": {
"type": "string"
},
"status": {
"type": "integer"
},
"method": {
"type": "string"
}
}
}
},
"content_type": {
"type": [
"string",
"null"
]
},
"reported_size_bytes": {
"type": [
"integer",
"null"
]
},
"size_basis": {
"type": "string"
},
"sample_bytes_observed": {
"type": "integer"
},
"sample_truncated": {
"type": "boolean"
},
"observed_at": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"requested_url": "https://mekler.ai/",
"final_url": "https://mekler.ai/",
"outcome": "reachable",
"http_status": 200,
"redirects": [
{
"url": "https://mekler.ai/",
"status": 200,
"method": "HEAD"
}
],
"content_type": "text/html",
"reported_size_bytes": 1024,
"size_basis": "server_header",
"sample_bytes_observed": 0,
"sample_truncated": false,
"observed_at": "2026-10-18T00:00:00Z",
"limitations": [
"HEAD metadata and range samples do not verify full content or total download size.",
"Only public HTTP(S) ports80/443, up tofive redirects; robots restrictions apply.",
"An observed HTTP error or redirect loop is a completed diagnostic, not guaranteed future availability."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.003000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]QR Code Generation: Generate a standards-based QR code from supplied UTF-8 text or a payment URI
POST /v1/images/qr/generate-code
0.003 USDC per accepted request
Service scope, examples and recovery →
Generate a standards-based QR code from supplied UTF-8 text or a payment URI. Return SVG or PNG as base64 with dimensions, SHA-256, QR version and error-correction level. Maximum 1024 UTF-8 bytes, scale 1–8 and fixed four-module quiet zone. Encodes the supplied payload; does not validate a payment destination, execute payment or host an image.
Input fields
textRequired · string- Literal payload, at most 1024 UTF-8 bytes. Payment URIs are encoded unchanged and are not payment authorization.
formatOptional · string- See the complete request schema for values and bounds.
error_correctionOptional · string- See the complete request schema for values and bounds.
scaleOptional · integer- See the complete request schema for values and bounds.
request_idRequired · string- Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"text",
"request_id"
],
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "Literal payload, at most 1024 UTF-8 bytes. Payment URIs are encoded unchanged and are not payment authorization."
},
"format": {
"type": "string",
"enum": [
"svg",
"png"
],
"default": "svg"
},
"error_correction": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"default": "M"
},
"scale": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"default": 4
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery."
}
}
},
"example": {
"text": "https://mekler.ai/",
"format": "png",
"error_correction": "M",
"scale": 4,
"request_id": "qr-generation-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"format",
"mime_type",
"encoding",
"data",
"sha256",
"byte_length",
"width",
"height",
"version",
"error_correction",
"quiet_zone_modules",
"payload_bytes"
],
"properties": {
"status": {
"type": "string"
},
"format": {
"type": "string"
},
"mime_type": {
"type": "string"
},
"encoding": {
"type": "string"
},
"data": {
"type": "string"
},
"sha256": {
"type": "string"
},
"byte_length": {
"type": "integer"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"version": {
"type": "integer"
},
"error_correction": {
"type": "string"
},
"quiet_zone_modules": {
"type": "integer"
},
"payload_bytes": {
"type": "integer"
}
}
},
"example": {
"status": "ok",
"format": "png",
"mime_type": "image/png",
"encoding": "base64",
"data": "iVBORw0KGgoAAAANSUhEUgAAAIQAAACEAQAAAAB5P74KAAAAw0lEQVR42u1W0QkCUQwLLpD9t8wGtclDQUEQ4+cVOWo/QpumucO8hXBVXisAOCBOohve45vK4jC/zZIUOCAJDZ20OEPNH3CWGNb9jEd6EPU7jteUKPfl4FMSDT/Wj6wfVjikBD/Y8aPoWVl/gaPVII6oS348muGgSj8LpD2M0Nz1s5O5GXZ61rENk9zdlz2D+VPrOb2wvq8Vj3Lw7b3bxgblvo5tnCFbH4t7qPbDpbnWjyU0ee1oWj90VzO1H15fBR8qd5tY9Osict9SAAAAAElFTkSuQmCC",
"sha256": "c25a99d2a24dbe4f167e747c2af350ec7360c9630002aff31a5979b6cc665780",
"byte_length": 252,
"width": 132,
"height": 132,
"version": 2,
"error_correction": "M",
"quiet_zone_modules": 4,
"payload_bytes": 18
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.003000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Cryptographic Digests: Compute SHA-256, SHA-512, SHA3-256 or BLAKE2b-512 digests from explicit UTF-8, canonical base64 or hex bytes
POST /v1/data/digests/generate-digest
0.003 USDC per accepted request
Service scope, examples and recovery →
Compute SHA-256, SHA-512, SHA3-256 or BLAKE2b-512 digests from explicit UTF-8, canonical base64 or hex bytes. Optional HMAC supports SHA-256/SHA-512 and supplied keys. Return hex or base64 with byte count. Maximum 16 KiB decoded input and 1 KiB HMAC key. No signing, encryption, password hashing or authenticity judgment.
Input fields
dataRequired · string- Content using encoding; at most 16384 decoded bytes. Empty data is permitted.
encodingOptional · string- See the complete request schema for values and bounds.
algorithmOptional · string- See the complete request schema for values and bounds.
output_encodingOptional · string- See the complete request schema for values and bounds.
keyOptional · string- Optional HMAC key,1–1024 decoded bytes. Only SHA256/SHA512; never send wallet or signing private keys.
key_encodingOptional · string- See the complete request schema for values and bounds.
request_idRequired · string- Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"request_id"
],
"properties": {
"data": {
"type": "string",
"maxLength": 32768,
"description": "Content using encoding; at most 16384 decoded bytes. Empty data is permitted."
},
"encoding": {
"type": "string",
"enum": [
"utf8",
"base64",
"hex"
],
"default": "utf8"
},
"algorithm": {
"type": "string",
"enum": [
"sha256",
"sha512",
"sha3-256",
"blake2b-512"
],
"default": "sha256"
},
"output_encoding": {
"type": "string",
"enum": [
"hex",
"base64"
],
"default": "hex"
},
"key": {
"type": "string",
"maxLength": 2048,
"description": "Optional HMAC key,1–1024 decoded bytes. Only SHA256/SHA512; never send wallet or signing private keys."
},
"key_encoding": {
"type": "string",
"enum": [
"utf8",
"base64",
"hex"
],
"default": "utf8"
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery."
}
}
},
"example": {
"data": "abc",
"encoding": "utf8",
"algorithm": "sha256",
"output_encoding": "hex",
"request_id": "digest-generation-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"algorithm",
"mode",
"input_bytes",
"output_encoding",
"digest"
],
"properties": {
"status": {
"type": "string"
},
"algorithm": {
"type": "string"
},
"mode": {
"type": "string"
},
"input_bytes": {
"type": "integer"
},
"output_encoding": {
"type": "string"
},
"digest": {
"type": "string"
}
}
},
"example": {
"status": "ok",
"algorithm": "sha256",
"mode": "digest",
"input_bytes": 3,
"output_encoding": "hex",
"digest": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.003000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Page Metadata: Extract static page metadata and share previews from one public HTML URL: title, description, canonical candidates, Open Graph/Twitter fields, image and favicon references
POST /v1/web/pages/extract-metadata
0.003 USDC per accepted request
Service scope, examples and recovery →
Extract static page metadata and share previews from one public HTML URL: title, description, canonical candidates, Open Graph/Twitter fields, image and favicon references. Resolve relative links, disclose canonical conflicts and apply explicit precedence. Maximum 1 MiB HTML and five redirects. No JavaScript rendering, asset retrieval or reachability guarantee for linked images.
Input fields
urlRequired · string- Public HTTP(S) URL, standard port 80/443. Credentials/private addresses are rejected; robots restrictions apply.
request_idRequired · string- Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"url",
"request_id"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"description": "Public HTTP(S) URL, standard port 80/443. Credentials/private addresses are rejected; robots restrictions apply."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier per new paid operation. Preserve with identical JSON and original proof for recovery."
}
}
},
"example": {
"url": "https://mekler.ai/",
"request_id": "page-metadata-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"url",
"retrieved_at",
"title",
"description",
"canonical_url",
"canonical_candidates",
"canonical_conflict",
"images",
"icons",
"open_graph",
"twitter",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"url": {
"type": "string"
},
"retrieved_at": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"canonical_url": {
"type": "string"
},
"canonical_candidates": {
"type": "array",
"items": {
"type": "string"
}
},
"canonical_conflict": {
"type": "boolean"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"icons": {
"type": "array",
"items": {
"type": "string"
}
},
"open_graph": {
"type": "object",
"maxProperties": 4,
"additionalProperties": {
"type": "array",
"maxItems": 5,
"items": {
"type": "string",
"maxLength": 4096
}
}
},
"twitter": {
"type": "object",
"maxProperties": 4,
"additionalProperties": {
"type": "array",
"maxItems": 5,
"items": {
"type": "string",
"maxLength": 4096
}
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"url": "https://mekler.ai/",
"retrieved_at": "2026-10-18T00:00:00Z",
"title": "Mekler example",
"description": "Synthetic preview metadata",
"canonical_url": "https://mekler.ai/",
"canonical_candidates": [
"https://mekler.ai/"
],
"canonical_conflict": false,
"images": [
"https://mekler.ai/preview.png"
],
"icons": [
"https://mekler.ai/favicon.ico"
],
"open_graph": {
"title": [
"Mekler example"
],
"type": [
"website"
]
},
"twitter": {
"card": [
"summary"
]
},
"limitations": [
"Static HTML only; no JavaScript rendering or asset fetching.",
"First valid canonical link wins; conflicts are disclosed. Title uses HTML then OpenGraph then Twitter.",
"Linked images/icons/canonical destinations are references, not verified reachable assets."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.003000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Technical SEO Audit: Check one public static HTML page for observed HTTP status, title/description/canonical conflicts, robots directives, headings, language, viewport and missing image alternatives
POST /v1/web/seo/check-page
0.005 USDC per accepted request
Service scope, examples and recovery →
Check one public static HTML page for observed HTTP status, title/description/canonical conflicts, robots directives, headings, language, viewport and missing image alternatives. Return evidence-linked findings and practical corrections. Up to 1 MiB and five redirects; no rendering, ranking prediction, linked-page verification or actual index-coverage claim.
Input fields
urlRequired · string- Public HTTP(S) URL on standard port 80/443; no credentials/private addresses. Robots restrictions and DNS-pinned public-address checks apply.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"description": "Public HTTP(S) URL on standard port 80/443; no credentials/private addresses. Robots restrictions and DNS-pinned public-address checks apply."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"url",
"request_id"
]
},
"example": {
"url": "https://mekler.ai/",
"request_id": "technical-seo-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"url",
"observed_at",
"http_status",
"title",
"description",
"canonical_candidates",
"directives",
"headings",
"images",
"findings",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"url": {
"type": "string"
},
"observed_at": {
"type": "string"
},
"http_status": {
"type": "integer"
},
"title": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"canonical_candidates": {
"type": "array",
"items": {
"type": "string"
}
},
"directives": {
"type": "array",
"items": {
"type": "string"
}
},
"headings": {
"type": "object",
"additionalProperties": false,
"required": [
"1",
"2",
"3",
"4",
"5",
"6"
],
"properties": {
"1": {
"type": "integer"
},
"2": {
"type": "integer"
},
"3": {
"type": "integer"
},
"4": {
"type": "integer"
},
"5": {
"type": "integer"
},
"6": {
"type": "integer"
}
}
},
"images": {
"type": "object",
"additionalProperties": false,
"required": [
"total",
"missing_alt"
],
"properties": {
"total": {
"type": "integer"
},
"missing_alt": {
"type": "integer"
}
}
},
"findings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"severity": {
"type": "string"
},
"evidence": {
"type": "string"
},
"recommendation": {
"type": "string"
}
},
"required": [
"code",
"severity",
"evidence",
"recommendation"
]
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"url": "https://mekler.ai/",
"observed_at": "2026-10-20T00:00:00Z",
"http_status": 200,
"title": "Mekler example",
"description": "Synthetic page for documented diagnostics",
"canonical_candidates": [
"https://mekler.ai/"
],
"directives": [],
"headings": {
"1": 1,
"2": 0,
"3": 0,
"4": 0,
"5": 0,
"6": 0
},
"images": {
"total": 0,
"missing_alt": 0
},
"findings": [],
"limitations": [
"One static HTML response up to 1 MiB; robots restrictions and five-redirect bound apply. Metadata samples retain at most 20 values and four complete canonical URL candidates.",
"No JavaScript rendering, site-wide duplicate analysis, keyword strategy, ranking or actual search-index coverage.",
"Canonical targets and linked assets are references, not fetched or verified. Findings describe observations, not guaranteed search outcomes."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Currency Reference Rates: Convert an amount between two currency codes using dated public reference rates and decimal arithmetic
POST /v1/finance/currencies/convert-reference-amount
0.005 USDC per accepted request
Service scope, examples and recovery →
Convert an amount between two currency codes using dated public reference rates and decimal arithmetic. Return the rate date, age, source and explicit rounding. Optional historical date from 1999-01-04; holidays may use earlier observations. No executable payment quote, intraday market feed or trading execution.
Input fields
baseRequired · string- Uppercase source currency code supported by Frankfurter.
quoteRequired · string- Uppercase target currency code supported by Frankfurter.
amountRequired · string- Nonnegative decimal string, up to 1 trillion and 8 fractional digits. Never send binary floating-point amounts.
dateOptional · string- Optional past/current ISO date from 1999-01-04. Omit for latest available reference rate; actual rate_date can be earlier.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"base": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Uppercase source currency code supported by Frankfurter."
},
"quote": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Uppercase target currency code supported by Frankfurter."
},
"amount": {
"type": "string",
"pattern": "^[0-9]{1,13}(?:\\.[0-9]{1,8})?$",
"description": "Nonnegative decimal string, up to 1 trillion and 8 fractional digits. Never send binary floating-point amounts."
},
"date": {
"type": "string",
"format": "date",
"description": "Optional past/current ISO date from 1999-01-04. Omit for latest available reference rate; actual rate_date can be earlier."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"base",
"quote",
"amount",
"request_id"
]
},
"example": {
"base": "USD",
"quote": "EUR",
"amount": "100.00",
"request_id": "currency-reference-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"base",
"quote",
"amount",
"rate",
"converted_amount",
"rate_date",
"requested_date",
"observed_at",
"age_days",
"source",
"source_url",
"rate_type",
"rounding",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"base": {
"type": "string"
},
"quote": {
"type": "string"
},
"amount": {
"type": "string"
},
"rate": {
"type": "string"
},
"converted_amount": {
"type": "string"
},
"rate_date": {
"type": "string"
},
"requested_date": {
"type": [
"string",
"null"
]
},
"observed_at": {
"type": "string"
},
"age_days": {
"type": "integer"
},
"source": {
"type": "string"
},
"source_url": {
"type": [
"string",
"null"
]
},
"rate_type": {
"type": "string"
},
"rounding": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"base": "USD",
"quote": "EUR",
"amount": "100.00",
"rate": "0.9",
"converted_amount": "90.00000000",
"rate_date": "2026-10-19",
"requested_date": null,
"observed_at": "2026-10-20T00:00:00Z",
"age_days": 1,
"source": "Frankfurter daily blended reference rates",
"source_url": "https://api.frankfurter.dev/v2/rate/usd/eur",
"rate_type": "reference",
"rounding": "8 decimal places, ROUND_HALF_EVEN; not currency minor-unit rounding",
"limitations": [
"Reference conversion only; not an executable quote, payment or intraday trading price.",
"Historical requests may use an earlier observation for holidays or missing dates; inspect rate_date and age_days.",
"Source coverage and rates may change; conversion uses the dated retrieved observation."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Vehicle VIN Decoding: Decode a complete 17-character VIN into source-linked NHTSA manufacturer, model-year and equipment fields
POST /v1/data/vehicles/check-vin
0.005 USDC per accepted request
Service scope, examples and recovery →
Decode a complete 17-character VIN into source-linked NHTSA manufacturer, model-year and equipment fields. Return source errors, missing fields and independent check-digit evidence. Optional model year helps disambiguate the source. Coverage centers on US-market vehicles; no owner, title, accident-history, condition or valid-vehicle certification.
Input fields
vinRequired · string- Complete uppercase VIN; excludes I, O and Q. Check-digit mismatch is reported, not silently corrected.
model_yearOptional · integer- Optional requested model year for NHTSA disambiguation; output retains source errors.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"vin": {
"type": "string",
"pattern": "^[A-HJ-NPR-Z0-9]{17}$",
"description": "Complete uppercase VIN; excludes I, O and Q. Check-digit mismatch is reported, not silently corrected."
},
"model_year": {
"type": "integer",
"minimum": 1981,
"maximum": 2100,
"description": "Optional requested model year for NHTSA disambiguation; output retains source errors."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"vin",
"request_id"
]
},
"example": {
"vin": "5UXWX7C5XBA123456",
"model_year": 2011,
"request_id": "vehicle-vin-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"vin",
"requested_model_year",
"observed_at",
"specifications",
"check_digit",
"source_error_codes",
"source_message",
"decode_complete",
"source",
"source_url",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"vin": {
"type": "string"
},
"requested_model_year": {
"type": [
"integer",
"null"
]
},
"observed_at": {
"type": "string"
},
"specifications": {
"type": "object",
"additionalProperties": false,
"required": [
"make",
"model",
"model_year",
"manufacturer",
"body_class",
"vehicle_type",
"fuel_type",
"engine_cylinders",
"engine_liters",
"drive_type",
"plant_country",
"series",
"trim"
],
"properties": {
"make": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"model_year": {
"type": [
"string",
"null"
]
},
"manufacturer": {
"type": [
"string",
"null"
]
},
"body_class": {
"type": [
"string",
"null"
]
},
"vehicle_type": {
"type": [
"string",
"null"
]
},
"fuel_type": {
"type": [
"string",
"null"
]
},
"engine_cylinders": {
"type": [
"string",
"null"
]
},
"engine_liters": {
"type": [
"string",
"null"
]
},
"drive_type": {
"type": [
"string",
"null"
]
},
"plant_country": {
"type": [
"string",
"null"
]
},
"series": {
"type": [
"string",
"null"
]
},
"trim": {
"type": [
"string",
"null"
]
}
}
},
"check_digit": {
"type": "object",
"additionalProperties": false,
"required": [
"observed",
"expected",
"matches",
"north_american_rule_applicable"
],
"properties": {
"observed": {
"type": "string"
},
"expected": {
"type": "string"
},
"matches": {
"type": "boolean"
},
"north_american_rule_applicable": {
"type": "boolean"
}
}
},
"source_error_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"source_message": {
"type": "string"
},
"decode_complete": {
"type": "boolean"
},
"source": {
"type": "string"
},
"source_url": {
"type": "string"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"vin": "5UXWX7C5XBA123456",
"requested_model_year": 2011,
"observed_at": "2026-10-20T00:00:00Z",
"specifications": {
"make": "SYNTHETIC",
"model": "Example",
"model_year": "2011",
"manufacturer": null,
"body_class": null,
"vehicle_type": null,
"fuel_type": null,
"engine_cylinders": null,
"engine_liters": null,
"drive_type": null,
"plant_country": null,
"series": null,
"trim": null
},
"check_digit": {
"observed": "X",
"expected": "7",
"matches": false,
"north_american_rule_applicable": true
},
"source_error_codes": [
"0"
],
"source_message": "Synthetic fixture only",
"decode_complete": true,
"source": "NHTSA vPIC",
"source_url": "https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/5UXWX7C5XBA123456?format=json&modelyear=2011",
"limitations": [
"Manufacturer-submitted specifications for vehicles intended for the US market; other markets can have limited coverage.",
"A decoded field is not evidence of ownership, title, accident history, condition or installed equipment today.",
"Inspect source errors and check-digit evidence. A partial or invalid source decode is a completed diagnostic, not a valid-vehicle certification."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]HTTP Security and CORS Inspection: Inspect one public URL for observed security headers and cross-origin configuration
POST /v1/web/headers/check-security-policy
0.005 USDC per accepted request
Service scope, examples and recovery →
Inspect one public URL for observed security headers and cross-origin configuration. Send passive GET and credential-free OPTIONS with a supplied origin, requested method and optional header names; return exact selected headers and evidence-linked findings. No authorization/cookies, exploit attempts, state-changing requests, browser enforcement guarantee or full CSP/TLS analysis.
Input fields
urlRequired · string- Public HTTP(S) URL on standard port 80/443; no credentials/private addresses. Robots restrictions and DNS-pinned public-address checks apply.
originOptional · string- HTTP(S) origin only, without path/query/credentials. Sent as Origin, never as an authenticated identity.
requested_methodOptional · string- Method named in the OPTIONS preflight; this method is not executed.
request_headersOptional · array- Lowercase header names advertised in the preflight; no values or credentials are sent.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"description": "Public HTTP(S) URL on standard port 80/443; no credentials/private addresses. Robots restrictions and DNS-pinned public-address checks apply."
},
"origin": {
"type": "string",
"maxLength": 2048,
"default": "https://mekler.ai",
"description": "HTTP(S) origin only, without path/query/credentials. Sent as Origin, never as an authenticated identity."
},
"requested_method": {
"type": "string",
"enum": [
"GET",
"HEAD",
"POST",
"PUT",
"PATCH",
"DELETE"
],
"default": "GET",
"description": "Method named in the OPTIONS preflight; this method is not executed."
},
"request_headers": {
"type": "array",
"maxItems": 20,
"items": {
"type": "string",
"pattern": "^[a-z0-9-]{1,64}$"
},
"default": [],
"description": "Lowercase header names advertised in the preflight; no values or credentials are sent."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"url",
"request_id"
]
},
"example": {
"url": "https://mekler.ai/",
"origin": "https://mekler.ai",
"requested_method": "GET",
"request_headers": [],
"request_id": "http-security-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"url",
"observed_at",
"http_status",
"origin",
"requested_method",
"request_headers",
"response_headers",
"preflight",
"findings",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"url": {
"type": "string"
},
"observed_at": {
"type": "string"
},
"http_status": {
"type": "integer"
},
"origin": {
"type": "string"
},
"requested_method": {
"type": "string"
},
"request_headers": {
"type": "array",
"items": {
"type": "string"
}
},
"response_headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"maxProperties": 20
},
"preflight": {
"type": "object",
"additionalProperties": false,
"required": [
"http_status",
"url",
"headers"
],
"properties": {
"http_status": {
"type": "integer"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"maxProperties": 20
}
}
},
"findings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"severity": {
"type": "string"
},
"evidence": {
"type": "string"
},
"recommendation": {
"type": "string"
}
},
"required": [
"code",
"severity",
"evidence",
"recommendation"
]
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"url": "https://mekler.ai/",
"observed_at": "2026-10-20T00:00:00Z",
"http_status": 200,
"origin": "https://mekler.ai",
"requested_method": "GET",
"request_headers": [],
"response_headers": {
"x-content-type-options": "nosniff",
"access-control-allow-origin": "*",
"access-control-allow-methods": "GET, HEAD"
},
"preflight": {
"http_status": 200,
"url": "https://mekler.ai/",
"headers": {
"x-content-type-options": "nosniff",
"access-control-allow-origin": "*",
"access-control-allow-methods": "GET, HEAD"
}
},
"findings": [
{
"code": "hsts_absent",
"severity": "info",
"evidence": "No HSTS response header.",
"recommendation": "Consider HSTS after confirming HTTPS coverage for the intended host scope."
},
{
"code": "csp_absent",
"severity": "info",
"evidence": "No enforced CSP response header.",
"recommendation": "Consider a tested CSP appropriate to the application; report-only is not enforcement."
}
],
"limitations": [
"Passive GET and credential-free OPTIONS observations only; no cookies, authorization, exploit attempts or state-changing method is sent.",
"Observed policies may vary by route, origin, browser and authentication. This is not a vulnerability scan or a browser enforcement/safety certification.",
"CSP syntax/effective-policy analysis and TLS certificate inspection are outside this operation."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Link and Sitemap Inventory: Extract a bounded URL inventory from static HTML anchors or same-origin XML sitemaps
POST /v1/web/links/extract-inventory
0.005 USDC per accepted request
Service scope, examples and recovery →
Extract a bounded URL inventory from static HTML anchors or same-origin XML sitemaps. Return normalized URLs, anchor text, relation flags, source and coverage bounds; deduplicate links while retaining occurrence counts. Up to 200 URLs and five uncompressed 1 MiB sitemap documents. No JavaScript rendering, linked-page crawl, reachability checks or search-index completeness.
Input fields
urlRequired · string- Public HTTP(S) URL on standard port 80/443; no credentials/private addresses. Robots restrictions and DNS-pinned public-address checks apply.
modeOptional · string- links parses one HTML page; sitemap traverses the supplied uncompressed XML sitemap/index on the same origin.
max_urlsOptional · integer- See the complete request schema for values and bounds.
max_sitemapsOptional · integer- Includes the starting XML document; only relevant to sitemap mode.
request_idRequired · string- Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 262144 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"description": "Public HTTP(S) URL on standard port 80/443; no credentials/private addresses. Robots restrictions and DNS-pinned public-address checks apply."
},
"mode": {
"type": "string",
"enum": [
"links",
"sitemap"
],
"default": "links",
"description": "links parses one HTML page; sitemap traverses the supplied uncompressed XML sitemap/index on the same origin."
},
"max_urls": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 100
},
"max_sitemaps": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 3,
"description": "Includes the starting XML document; only relevant to sitemap mode."
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$",
"description": "Fresh identifier for each new purchase. Retain identical JSON and original payment proof for recovery."
}
},
"required": [
"url",
"request_id"
]
},
"example": {
"url": "https://mekler.ai/",
"mode": "links",
"max_urls": 100,
"max_sitemaps": 3,
"request_id": "link-inventory-example-001"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"url",
"mode",
"observed_at",
"links",
"canonical_candidates",
"sources_visited",
"pending_sitemaps",
"truncated",
"skipped",
"bounds",
"limitations"
],
"properties": {
"status": {
"type": "string"
},
"url": {
"type": "string"
},
"mode": {
"type": "string"
},
"observed_at": {
"type": "string"
},
"links": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"url",
"anchor",
"rel",
"internal",
"occurrences",
"source"
],
"properties": {
"url": {
"type": "string"
},
"anchor": {
"type": "string"
},
"rel": {
"type": "array",
"items": {
"type": "string"
}
},
"internal": {
"type": "boolean"
},
"occurrences": {
"type": "integer"
},
"source": {
"type": "string"
}
}
}
},
"canonical_candidates": {
"type": "array",
"items": {
"type": "string"
}
},
"sources_visited": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_sitemaps": {
"type": "integer"
},
"truncated": {
"type": "boolean"
},
"skipped": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"reason": {
"type": "string"
}
},
"required": [
"source",
"reason"
],
"additionalProperties": false
}
},
"bounds": {
"type": "object",
"additionalProperties": false,
"required": [
"max_urls",
"max_sitemaps"
],
"properties": {
"max_urls": {
"type": "integer"
},
"max_sitemaps": {
"type": "integer"
}
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"url": "https://mekler.ai/",
"mode": "links",
"observed_at": "2026-10-20T00:00:00Z",
"links": [
{
"url": "https://mekler.ai/start/",
"anchor": "Get started",
"rel": [
"help"
],
"internal": true,
"occurrences": 1,
"source": "https://mekler.ai/"
}
],
"canonical_candidates": [
"https://mekler.ai/"
],
"sources_visited": [
"https://mekler.ai/"
],
"pending_sitemaps": 0,
"truncated": false,
"skipped": [],
"bounds": {
"max_urls": 100,
"max_sitemaps": 3
},
"limitations": [
"Static anchors or uncompressed XML sitemaps only; no JavaScript execution, linked-page crawling, reachability checks or search-index coverage.",
"Fragments are removed; query strings are retained. Page links are deduplicated by normalized URL with occurrence counts. Link evidence is capped at 24 KiB; truncated marks either byte or count limits.",
"Sitemap traversal stays on the starting origin, follows at most 5 sitemap documents of 1 MiB each, and returns at most 200 URLs. Bounds/skips describe coverage, not completeness of the site."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.005000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 262144 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Renew a durable mailbox for 30 more days
POST /v1/messaging/mailboxes/renew-mailbox
2 USDC per 30-day receiving term; 1,000 messages and explicitly bounded recovery
Service scope, examples and recovery →
Extend the same private mailbox by a 30-day receiving term for 2 USDC. Early renewal preserves the current allowance until the new term begins. Use a new request_id and the original owner_key. Retained content keeps its original expiry.
Input fields
request_idRequired · string- See the complete request schema for values and bounds.
owner_keyRequired · string- See the complete request schema for values and bounds.
mailbox_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Finalized receiving term and original-proof recovery receipt. PAYMENT-RESPONSE confirms settlement.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- Input-bound x402 v2 quote for valid creation input. Empty unsigned JSON is nonpayable preflight; supply request_id and a private access_key before signing.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Decoded JSON request exceeds 8192 bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"owner_key",
"mailbox_id"
],
"properties": {
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"owner_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$"
},
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
}
},
"example": {
"request_id": "mekler-mail-renewal-01",
"owner_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE",
"mailbox_id": "1c2dee1d4ee689f629f57d2ba1ac2f40"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Finalized receiving term and original-proof recovery receipt. PAYMENT-RESPONSE confirms settlement.",
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"mailbox_id",
"purchase_id",
"email_address",
"receiving_term_seconds",
"next_step",
"receiving_term"
],
"properties": {
"status": {
"const": "ok"
},
"mailbox_id": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"purchase_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"email_address": {
"type": "string",
"format": "email"
},
"receiving_term_seconds": {
"const": 2592000
},
"next_step": {
"type": "string"
},
"receiving_term": {
"type": "object",
"additionalProperties": false,
"required": [
"starts_at",
"ends_at"
],
"properties": {
"starts_at": {
"type": "integer"
},
"ends_at": {
"type": "integer"
}
}
}
}
},
"example": {
"status": "ok",
"mailbox_id": "1c2dee1d4ee689f629f57d2ba1ac2f40",
"purchase_id": "4a21624bd19334a8cd73030d4ca07844b17d3d7089abbffd0ef50a28071556ea",
"email_address": "1c2dee1d4ee689f629f57d2ba1ac2f40@mail.mekler.ai",
"receiving_term_seconds": 2592000,
"next_step": "Retrieve mailbox status with your owner key after settlement.",
"receiving_term": {
"starts_at": 1795478400,
"ends_at": 1798070400
}
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "Input-bound x402 v2 quote for valid creation input. Empty unsigned JSON is nonpayable preflight; supply request_id and a private access_key before signing.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "2.000000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Decoded JSON request exceeds 8192 bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Retrieve mailbox lifetime, limits and usage
POST /v1/messaging/mailboxes/retrieve-mailbox
Follow the authentication, capability and prerequisite requirements below.
Retrieve mailbox lifetime, limits and usage. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
mailbox_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"mailbox_id"
],
"properties": {
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
}
},
"example": {
"mailbox_id": "48c93039de46652b3edbb29908213aea"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"email_address",
"email_enabled",
"latest_message_expiry",
"limits",
"mailbox_id",
"paid_until",
"receiving",
"retained_bytes",
"status",
"usage",
"webhook_secret"
],
"properties": {
"email_address": {
"type": "string"
},
"email_enabled": {
"type": "boolean"
},
"latest_message_expiry": {
"type": "integer"
},
"limits": {
"type": "object",
"additionalProperties": false,
"required": [
"connections",
"download_bytes",
"message_bytes",
"messages",
"operations",
"retained_bytes"
],
"properties": {
"connections": {
"type": "integer"
},
"download_bytes": {
"type": "integer"
},
"message_bytes": {
"type": "integer"
},
"messages": {
"type": "integer"
},
"operations": {
"type": "integer"
},
"retained_bytes": {
"type": "integer"
}
}
},
"mailbox_id": {
"type": "string"
},
"paid_until": {
"type": "integer"
},
"receiving": {
"type": "boolean"
},
"retained_bytes": {
"type": "integer"
},
"status": {
"type": "string"
},
"usage": {
"type": "object",
"additionalProperties": false,
"required": [
"download_bytes",
"email_messages",
"end",
"messages",
"native_messages",
"operations",
"purge_at",
"start"
],
"properties": {
"download_bytes": {
"type": "integer"
},
"email_messages": {
"type": "integer"
},
"end": {
"type": "integer"
},
"messages": {
"type": "integer"
},
"native_messages": {
"type": "integer"
},
"operations": {
"type": "integer"
},
"purge_at": {
"type": "integer"
},
"start": {
"type": "integer"
}
}
},
"webhook_secret": {
"type": "string"
}
}
},
"example": {
"email_address": "48c93039de46652b3edbb29908213aea@mail.mekler.ai",
"email_enabled": true,
"latest_message_expiry": 1795478400,
"limits": {
"connections": 1,
"download_bytes": 1073741824,
"message_bytes": 262144,
"messages": 1000,
"operations": 50000,
"retained_bytes": 536870912
},
"mailbox_id": "48c93039de46652b3edbb29908213aea",
"paid_until": 1795478400,
"receiving": true,
"retained_bytes": 291,
"status": "ok",
"usage": {
"download_bytes": 0,
"email_messages": 0,
"end": 1795478400,
"messages": 1,
"native_messages": 1,
"operations": 0,
"purge_at": 1800662400,
"start": 1792886400
},
"webhook_secret": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAI"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Configure email admission and notification settings
POST /v1/messaging/mailboxes/configure-mailbox
Follow the authentication, capability and prerequisite requirements below.
Configure email admission and notification settings. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
callbackOptional · string or null- See the complete request schema for values and bounds.
email_enabledRequired · boolean- See the complete request schema for values and bounds.
email_limitOptional · integer- See the complete request schema for values and bounds.
mailbox_idRequired · string- See the complete request schema for values and bounds.
native_limitOptional · integer- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"email_enabled",
"mailbox_id"
],
"properties": {
"callback": {
"type": [
"string",
"null"
],
"maxLength": 2048
},
"email_enabled": {
"type": "boolean"
},
"email_limit": {
"type": "integer",
"minimum": 0,
"maximum": 1000
},
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"native_limit": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
}
},
"example": {
"email_enabled": true,
"mailbox_id": "48c93039de46652b3edbb29908213aea"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"properties": {
"status": {
"type": "string"
}
}
},
"example": {
"status": "ok"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Create a scoped mailbox access grant
POST /v1/messaging/mailboxes/create-access-grant
Follow the authentication, capability and prerequisite requirements below.
Create a scoped mailbox access grant. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
allowanceOptional · integer- See the complete request schema for values and bounds.
conversation_idOptional · string- See the complete request schema for values and bounds.
expires_atRequired · integer- See the complete request schema for values and bounds.
keyRequired · string- See the complete request schema for values and bounds.
mailbox_idRequired · string- See the complete request schema for values and bounds.
message_idOptional · string- See the complete request schema for values and bounds.
scopesRequired · array- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"expires_at",
"key",
"mailbox_id",
"scopes"
],
"properties": {
"allowance": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"conversation_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"expires_at": {
"type": "integer"
},
"key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$"
},
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"message_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"scopes": {
"type": "array",
"minItems": 1,
"maxItems": 3,
"uniqueItems": true,
"items": {
"enum": [
"read",
"process",
"send"
]
}
}
}
},
"example": {
"expires_at": 1795478400,
"key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAI",
"mailbox_id": "48c93039de46652b3edbb29908213aea",
"scopes": [
"read",
"process"
]
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"expires_at",
"grant_id",
"status"
],
"properties": {
"expires_at": {
"type": "integer"
},
"grant_id": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"example": {
"expires_at": 1795478400,
"grant_id": "9267d3dbed802941483f1afa2a6bc68de5f653128aca9bf1461c5d0a3ad36ed2",
"status": "ok"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Revoke a mailbox access grant
POST /v1/messaging/mailboxes/revoke-access-grant
Follow the authentication, capability and prerequisite requirements below.
Revoke a mailbox access grant. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
grant_idRequired · string- See the complete request schema for values and bounds.
mailbox_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"grant_id",
"mailbox_id"
],
"properties": {
"grant_id": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
}
},
"example": {
"grant_id": "0000000000000000000000000000000000000000000000000000000000000000",
"mailbox_id": "48c93039de46652b3edbb29908213aea"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"revoked",
"status"
],
"properties": {
"revoked": {
"type": "boolean"
},
"status": {
"type": "string"
}
}
},
"example": {
"revoked": true,
"status": "ok"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Send a message with an idempotency key
POST /v1/messaging/mailboxes/send-message
Follow the authentication, capability and prerequisite requirements below.
Send a message with an idempotency key. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
contentRequired · object- See the complete request schema for values and bounds.
mailbox_idRequired · string- See the complete request schema for values and bounds.
request_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"content",
"mailbox_id",
"request_id"
],
"properties": {
"content": {
"type": "object",
"additionalProperties": false,
"required": [
"content_type",
"body"
],
"properties": {
"content_type": {
"enum": [
"text/plain",
"text/markdown",
"application/json",
"message/rfc822"
]
},
"body": {},
"conversation_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"reply_to": {
"type": "string",
"maxLength": 512
},
"encoding": {
"const": "base64"
},
"attachments": {
"type": "array",
"maxItems": 8,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"content_type",
"base64"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"content_type": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"base64": {
"type": "string",
"maxLength": 262144,
"contentEncoding": "base64"
}
}
}
}
}
},
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
}
},
"example": {
"content": {
"content_type": "application/json",
"body": {
"complete": true
}
},
"mailbox_id": "48c93039de46652b3edbb29908213aea",
"request_id": "sample_message_0002"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"accepted_at",
"expires_at",
"message_id",
"status"
],
"properties": {
"accepted_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"message_id": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"example": {
"accepted_at": 1792886400,
"expires_at": 1795478400,
"message_id": "00000000000000000000000000000001",
"status": "stored"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
List retained or unfinished messages
POST /v1/messaging/mailboxes/list-messages
Follow the authentication, capability and prerequisite requirements below.
List retained or unfinished messages. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
conversation_idOptional · string- See the complete request schema for values and bounds.
cursorOptional · string- See the complete request schema for values and bounds.
limitOptional · integer- See the complete request schema for values and bounds.
mailbox_idRequired · string- See the complete request schema for values and bounds.
unfinishedOptional · boolean- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"mailbox_id"
],
"properties": {
"conversation_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"cursor": {
"type": "string",
"maxLength": 64
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
},
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"unfinished": {
"type": "boolean"
}
}
},
"example": {
"mailbox_id": "48c93039de46652b3edbb29908213aea"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"cursor",
"messages",
"status"
],
"properties": {
"cursor": {
"type": [
"string",
"null"
]
},
"messages": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"accepted_at",
"channel",
"conversation_id",
"expires_at",
"message_id",
"state"
],
"properties": {
"accepted_at": {
"type": "integer"
},
"channel": {
"type": "string"
},
"conversation_id": {
"type": [
"string",
"null"
]
},
"expires_at": {
"type": "integer"
},
"message_id": {
"type": "string"
},
"state": {
"type": "string"
}
}
}
},
"status": {
"type": "string"
}
}
},
"example": {
"cursor": null,
"messages": [
{
"accepted_at": 1792886400,
"channel": "native",
"conversation_id": null,
"expires_at": 1795478400,
"message_id": "00000000000000000000000000000000",
"state": "pending"
}
],
"status": "ok"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Retrieve one retained message
POST /v1/messaging/mailboxes/retrieve-message
Follow the authentication, capability and prerequisite requirements below.
Retrieve one retained message. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
mailbox_idRequired · string- See the complete request schema for values and bounds.
message_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"mailbox_id",
"message_id"
],
"properties": {
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"message_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
}
},
"example": {
"mailbox_id": "48c93039de46652b3edbb29908213aea",
"message_id": "00000000000000000000000000000000"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message",
"processing",
"status"
],
"properties": {
"message": {
"type": "object",
"additionalProperties": false,
"required": [
"accepted_at",
"channel",
"content",
"expires_at",
"message_id",
"provenance",
"sender"
],
"properties": {
"accepted_at": {
"type": "integer"
},
"channel": {
"type": "string"
},
"content": {
"type": "object"
},
"expires_at": {
"type": "integer"
},
"message_id": {
"type": "string"
},
"provenance": {
"type": "object"
},
"sender": {
"type": "string"
}
}
},
"processing": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"example": {
"message": {
"accepted_at": 1792886400,
"channel": "native",
"content": {
"body": "Synthetic completed task result.",
"content_type": "text/plain"
},
"expires_at": 1795478400,
"message_id": "00000000000000000000000000000000",
"provenance": {},
"sender": "ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5"
},
"processing": "pending",
"status": "ok"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Claim, acknowledge, release or defer a message
POST /v1/messaging/mailboxes/update-message-processing
Follow the authentication, capability and prerequisite requirements below.
Claim, acknowledge, release or defer a message. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
actionRequired · See complete schema- See the complete request schema for values and bounds.
claim_tokenOptional · string- See the complete request schema for values and bounds.
mailbox_idRequired · string- See the complete request schema for values and bounds.
message_idRequired · string- See the complete request schema for values and bounds.
secondsOptional · integer- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"action",
"mailbox_id",
"message_id"
],
"properties": {
"action": {
"enum": [
"claim",
"extend",
"acknowledge",
"release",
"defer"
]
},
"claim_token": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"message_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"seconds": {
"type": "integer",
"minimum": 1,
"maximum": 900
}
}
},
"example": {
"action": "claim",
"mailbox_id": "48c93039de46652b3edbb29908213aea",
"message_id": "00000000000000000000000000000000"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"claim",
"message_id",
"state",
"status"
],
"properties": {
"claim": {
"type": [
"object",
"null"
],
"properties": {
"token": {
"type": "string"
},
"holder": {
"type": "string"
},
"until": {
"type": "integer"
}
}
},
"message_id": {
"type": "string"
},
"state": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"example": {
"claim": {
"holder": "ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5",
"token": "00000000000000000000000000000001",
"until": 1792886700
},
"message_id": "00000000000000000000000000000000",
"state": "claimed",
"status": "ok"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Delete a retained message
POST /v1/messaging/mailboxes/delete-message
Follow the authentication, capability and prerequisite requirements below.
Delete a retained message. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
mailbox_idRequired · string- See the complete request schema for values and bounds.
message_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"mailbox_id",
"message_id"
],
"properties": {
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"message_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
}
},
"example": {
"mailbox_id": "48c93039de46652b3edbb29908213aea",
"message_id": "00000000000000000000000000000000"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"deleted",
"status"
],
"properties": {
"deleted": {
"type": "boolean"
},
"status": {
"type": "string"
}
}
},
"example": {
"deleted": true,
"status": "ok"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Recover retained messages outside exhausted ordinary quotas
POST /v1/messaging/mailboxes/export-messages
Follow the authentication, capability and prerequisite requirements below.
Recover retained messages outside exhausted ordinary quotas. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
cursorOptional · string- See the complete request schema for values and bounds.
mailbox_idRequired · string- See the complete request schema for values and bounds.
restartOptional · boolean- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"mailbox_id"
],
"properties": {
"cursor": {
"type": "string",
"maxLength": 64
},
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"restart": {
"type": "boolean"
}
}
},
"example": {
"mailbox_id": "48c93039de46652b3edbb29908213aea"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"cursor",
"messages",
"status"
],
"properties": {
"cursor": {
"type": [
"string",
"null"
]
},
"messages": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"accepted_at",
"channel",
"content",
"expires_at",
"message_id",
"provenance",
"sender"
],
"properties": {
"accepted_at": {
"type": "integer"
},
"channel": {
"type": "string"
},
"content": {
"type": "object"
},
"expires_at": {
"type": "integer"
},
"message_id": {
"type": "string"
},
"provenance": {
"type": "object"
},
"sender": {
"type": "string"
}
}
}
},
"status": {
"type": "string"
}
}
},
"example": {
"cursor": null,
"messages": [
{
"accepted_at": 1792886400,
"channel": "native",
"content": {
"body": "Synthetic completed task result.",
"content_type": "text/plain"
},
"expires_at": 1795478400,
"message_id": "00000000000000000000000000000000",
"provenance": {},
"sender": "ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5"
}
],
"status": "ok"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Forward an independent authorized message copy
POST /v1/messaging/mailboxes/forward-message
Follow the authentication, capability and prerequisite requirements below.
Forward an independent authorized message copy. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
mailbox_idRequired · string- See the complete request schema for values and bounds.
message_idRequired · string- See the complete request schema for values and bounds.
recipientRequired · string- See the complete request schema for values and bounds.
request_idRequired · string- See the complete request schema for values and bounds.
send_keyRequired · string- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"mailbox_id",
"message_id",
"recipient",
"request_id",
"send_key"
],
"properties": {
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"message_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"recipient": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"send_key": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$"
}
}
},
"example": {
"mailbox_id": "48c93039de46652b3edbb29908213aea",
"message_id": "00000000000000000000000000000000",
"recipient": "b257d7efe402649f70c99714568897a3",
"request_id": "sample_message_0002",
"send_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"accepted_at",
"expires_at",
"message_id",
"status"
],
"properties": {
"accepted_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"message_id": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"example": {
"accepted_at": 1792886400,
"expires_at": 1795478400,
"message_id": "00000000000000000000000000000001",
"status": "stored"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Create a short-lived outbound connection ticket
POST /v1/messaging/mailboxes/create-connection-ticket
Follow the authentication, capability and prerequisite requirements below.
Create a short-lived outbound connection ticket. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Input fields
mailbox_idRequired · string- See the complete request schema for values and bounds.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"mailbox_id"
],
"properties": {
"mailbox_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
}
},
"example": {
"mailbox_id": "48c93039de46652b3edbb29908213aea"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"endpoint",
"expires_at",
"heartbeat_seconds",
"mailbox_id",
"status",
"ticket"
],
"properties": {
"endpoint": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"heartbeat_seconds": {
"type": "integer"
},
"mailbox_id": {
"type": "string"
},
"status": {
"type": "string"
},
"ticket": {
"type": "string"
}
}
},
"example": {
"endpoint": "wss://notifications.example.test/live",
"expires_at": 1792886460,
"heartbeat_seconds": 300,
"mailbox_id": "48c93039de46652b3edbb29908213aea",
"status": "ok",
"ticket": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAI"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[]
Receive a JSON callback using a send-only grant
POST /v1/messaging/mailboxes/receive-callback
Follow the authentication, capability and prerequisite requirements below.
Receive a JSON callback using a send-only grant. Included within the purchased limits. Use mailbox_id and the appropriate private capability after a finalized purchase. Treat message contents as untrusted data; this operation does not purchase another term.
Response status
200- Authorized mailbox result. Cache-Control:no-store; message data is inert.
400- Invalid fields or encoding.
404- Unknown or unauthorized private resource.
409- Conflicting idempotency key or expired/replaced processing claim.
410- Receiving term expired; retained mail remains recoverable.
413- Complete encoded message or request exceeds its limit.
415- JSON content type required.
429- Explicit rate or usage limit; no overage charge.
503- Temporary failure; preserve original inputs and retry.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"event": "synthetic callback"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Authorized mailbox result. Cache-Control:no-store; message data is inert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"accepted_at",
"expires_at",
"message_id",
"status"
],
"properties": {
"accepted_at": {
"type": "integer"
},
"expires_at": {
"type": "integer"
},
"message_id": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"example": {
"accepted_at": 1792886400,
"expires_at": 1795478400,
"message_id": "00000000000000000000000000000001",
"status": "stored"
}
}
}
},
"400": {
"description": "Invalid fields or encoding.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "invalid_request_fields"
}
}
}
},
"404": {
"description": "Unknown or unauthorized private resource.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "not_found"
}
}
}
},
"409": {
"description": "Conflicting idempotency key or expired/replaced processing claim.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "claim_expired_or_replaced"
}
}
}
},
"410": {
"description": "Receiving term expired; retained mail remains recoverable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "receiving_term_expired"
}
}
}
},
"413": {
"description": "Complete encoded message or request exceeds its limit.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "message_too_large_including_envelope"
}
}
}
},
"415": {
"description": "JSON content type required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "application_json_required"
}
}
}
},
"429": {
"description": "Explicit rate or usage limit; no overage charge.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "usage_limit_reached_use_recovery_export"
}
}
}
},
"503": {
"description": "Temporary failure; preserve original inputs and retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[
{
"name": "X-Mekler-Mailbox",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
}
}
]Create a seven-day public API schema monitor
POST /v1/services/schema-monitors/create-monitor
0.5 USDC per seven-day hourly monitoring term
Service scope, examples and recovery →
Monitor one public HTTPS JSON API against your explicit schema for seven days. Includes an initial observation and up to 167 hourly checks, confirmed contract fault/recovery alerts and private history. Source failures remain unknown. 0.50 USDC per term; retrieve and delete with your private capability.
Input fields
request_idRequired · string- Fresh purchase identity; preserve with the original payment proof.
owner_keyRequired · string- Generate 32 random bytes privately. Keep unchanged for this purchase and private retrieval/deletion. Never use the public example key.
urlRequired · string- Canonical public HTTPS URL on port 443; no query, fragment, credentials or redirects. Buyer must authorize monitoring.
schemaRequired · object- Explicit bounded Draft 2020-12 subset listed in the service guide. Required, optional and nullable values retain normal JSON Schema semantics.
Response status
200- Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"owner_key",
"url",
"schema"
],
"properties": {
"request_id": {
"type": "string",
"minLength": 16,
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"description": "Fresh purchase identity; preserve with the original payment proof."
},
"owner_key": {
"type": "string",
"minLength": 64,
"maxLength": 64,
"pattern": "^[a-f0-9]{64}$",
"description": "Generate 32 random bytes privately. Keep unchanged for this purchase and private retrieval/deletion. Never use the public example key."
},
"url": {
"type": "string",
"format": "uri",
"maxLength": 1024,
"description": "Canonical public HTTPS URL on port 443; no query, fragment, credentials or redirects. Buyer must authorize monitoring."
},
"schema": {
"type": "object",
"minProperties": 1,
"maxProperties": 24,
"description": "Explicit bounded Draft 2020-12 subset listed in the service guide. Required, optional and nullable values retain normal JSON Schema semantics."
}
}
},
"example": {
"request_id": "schema-monitor-example-01",
"owner_key": "1111111111111111111111111111111111111111111111111111111111111111",
"url": "https://api.mekler.ai/health",
"schema": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"const": "ok"
}
}
}
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Completed bounded operation. PAYMENT-RESPONSE confirms finalized settlement; provisional results are explicitly labeled. Original proof recovers the exact result for 30 days.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"monitor_id",
"term_seconds",
"interval_seconds",
"maximum_observations",
"initial_observation",
"limitations",
"next_step"
],
"properties": {
"status": {
"type": "string"
},
"monitor_id": {
"type": "string"
},
"term_seconds": {
"type": "integer"
},
"interval_seconds": {
"type": "integer"
},
"maximum_observations": {
"type": "integer"
},
"initial_observation": {
"type": "object",
"additionalProperties": false,
"required": [
"state",
"at",
"errors",
"error_limit_reached",
"sample_bytes",
"coverage",
"signature",
"attempts"
],
"properties": {
"state": {
"type": "string",
"enum": [
"healthy",
"violation"
]
},
"at": {
"type": "integer"
},
"errors": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"required": [
"pointer",
"keyword"
],
"additionalProperties": false,
"properties": {
"pointer": {
"type": "string"
},
"keyword": {
"type": "string"
}
}
}
},
"error_limit_reached": {
"type": "boolean"
},
"sample_bytes": {
"type": "integer"
},
"coverage": {
"type": "string"
},
"signature": {
"type": "string"
},
"attempts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"state",
"at",
"errors",
"error_limit_reached",
"sample_bytes",
"coverage",
"signature"
],
"properties": {
"state": {
"type": "string",
"enum": [
"healthy",
"violation"
]
},
"at": {
"type": "integer"
},
"errors": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"required": [
"pointer",
"keyword"
],
"additionalProperties": false,
"properties": {
"pointer": {
"type": "string"
},
"keyword": {
"type": "string"
}
}
}
},
"error_limit_reached": {
"type": "boolean"
},
"sample_bytes": {
"type": "integer"
},
"coverage": {
"type": "string"
},
"signature": {
"type": "string"
}
}
}
}
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
},
"next_step": {
"type": "string"
}
}
},
"example": {
"status": "ok",
"monitor_id": "7ba23e2c5cc7c11246d33660534b28f6a250ef749ec15ba3",
"term_seconds": 604800,
"interval_seconds": 3600,
"maximum_observations": 168,
"initial_observation": {
"state": "healthy",
"at": 1000,
"errors": [],
"error_limit_reached": false,
"sample_bytes": 15,
"coverage": "one_response_no_pagination",
"signature": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
"attempts": [
{
"state": "healthy",
"at": 1000,
"errors": [],
"error_limit_reached": false,
"sample_bytes": 15,
"coverage": "one_response_no_pagination",
"signature": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945"
}
]
},
"limitations": [
"Checks the supplied JSON Schema requirements against one fetched response only; no automatic semantic or universal compatibility claim.",
"Only public unauthenticated HTTPS GET without redirects, custom headers or cookies. Source authorization remains the buyer responsibility.",
"Pagination is not followed. Empty arrays validate unless minItems is specified. Optional fields may be absent.",
"Hourly scheduling is best effort. Missed slots, source errors and incomplete samples remain visible and cannot establish a healthy contract.",
"Alerts are private data returned by retrieve-monitor; no email, webhook or push delivery is included."
],
"next_step": "Retrieve the monitor privately with monitor_id and your original owner_key. Scheduling starts only after finalized settlement."
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "x402 v2 payment quote for valid input. An empty unsigned POST receives a preflight-only 402 for directory validation; submit a valid bundle before signing. Expired/invalid proofs may also return 402.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.500000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]Retrieve current monitor evidence and alerts
POST /v1/services/schema-monitors/retrieve-monitor
Follow the authentication, capability and prerequisite requirements below.
Retrieve current monitor evidence and alerts. Free private capability operation. Send the original owner_key as Authorization Bearer; no x402 payment is required.
Input fields
monitor_idRequired · string- Purchased monitor identity.
Response status
200- Private monitor result or deletion confirmation
404- Missing monitor or invalid capability
413- Request exceeds 2048 encoded bytes
415- application/json required
503- Temporary storage failure; retry the same request
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"monitor_id"
],
"additionalProperties": false,
"properties": {
"monitor_id": {
"type": "string",
"pattern": "^[a-f0-9]{48}$",
"description": "Purchased monitor identity."
}
}
},
"example": {
"monitor_id": "7ba23e2c5cc7c11246d33660534b28f6a250ef749ec15ba3"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Private monitor result or deletion confirmation",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"monitor_id",
"monitor_state",
"starts_at",
"ends_at",
"observations_completed",
"missed_slots",
"next_check_at",
"state",
"history",
"alerts",
"history_limit",
"alerts_limit",
"limitations"
],
"properties": {
"status": {
"type": "string",
"const": "ok"
},
"monitor_id": {
"type": "string",
"pattern": "^[a-f0-9]{48}$"
},
"monitor_state": {
"type": "string",
"enum": [
"prepared",
"active",
"expired",
"deleted"
]
},
"starts_at": {
"type": [
"integer",
"null"
]
},
"ends_at": {
"type": [
"integer",
"null"
]
},
"observations_completed": {
"type": "integer",
"minimum": 1,
"maximum": 168
},
"missed_slots": {
"type": "integer",
"minimum": 0,
"maximum": 167
},
"next_check_at": {
"type": [
"integer",
"null"
]
},
"state": {
"type": "object",
"description": "Last observed/confirmed state, source-gap flag and timestamps; unknown observations preserve confirmed_state and signature. Empty after deletion.",
"additionalProperties": false,
"properties": {
"confirmed_state": {
"type": "string",
"enum": [
"healthy",
"violation"
]
},
"observed_state": {
"type": "string",
"enum": [
"healthy",
"violation",
"unknown"
]
},
"source_gap": {
"type": "boolean"
},
"signature": {
"type": "string"
},
"last_assessed_at": {
"type": "integer"
},
"last_checked_at": {
"type": "integer"
}
}
},
"history": {
"type": "array",
"maxItems": 24,
"description": "Oldest to newest observations, further bounded by encrypted-record bytes. No raw source values are retained.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"state",
"at",
"source_attempts"
],
"properties": {
"state": {
"type": "string",
"enum": [
"healthy",
"violation",
"unknown"
]
},
"at": {
"type": "integer"
},
"source_attempts": {
"type": "integer",
"minimum": 1,
"maximum": 2
},
"reason": {
"type": "string"
},
"http_status": {
"type": "integer"
},
"sample_bytes": {
"type": "integer"
},
"coverage": {
"type": "string"
},
"signature": {
"type": "string"
},
"error_limit_reached": {
"type": "boolean"
},
"errors": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"required": [
"pointer",
"keyword"
],
"properties": {
"pointer": {
"type": "string"
},
"keyword": {
"type": "string"
}
},
"additionalProperties": false
}
}
}
}
},
"alerts": {
"type": "array",
"maxItems": 100,
"description": "Oldest to newest retained fault, recovery and source-gap events. Repeated identical faults are suppressed. Further bounded by encrypted-record bytes.",
"items": {
"type": "object",
"required": [
"kind",
"at"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"contract_violation",
"contract_recovered",
"source_unavailable",
"source_recovered"
]
},
"at": {
"type": "integer"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"pointer",
"keyword"
],
"properties": {
"pointer": {
"type": "string"
},
"keyword": {
"type": "string"
}
},
"additionalProperties": false
}
}
}
}
},
"history_limit": {
"type": "integer",
"const": 24
},
"alerts_limit": {
"type": "integer",
"const": 100
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"monitor_id": "7ba23e2c5cc7c11246d33660534b28f6a250ef749ec15ba3",
"monitor_state": "active",
"starts_at": 1000,
"ends_at": 605800,
"observations_completed": 1,
"missed_slots": 0,
"next_check_at": 4600,
"state": {
"source_gap": false,
"confirmed_state": "healthy",
"signature": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
"last_assessed_at": 1000,
"observed_state": "healthy",
"last_checked_at": 1000
},
"history": [
{
"state": "healthy",
"at": 1000,
"errors": [],
"error_limit_reached": false,
"sample_bytes": 15,
"coverage": "one_response_no_pagination",
"signature": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
"source_attempts": 1
}
],
"alerts": [],
"history_limit": 24,
"alerts_limit": 100,
"limitations": [
"Checks the supplied JSON Schema requirements against one fetched response only; no automatic semantic or universal compatibility claim.",
"Only public unauthenticated HTTPS GET without redirects, custom headers or cookies. Source authorization remains the buyer responsibility.",
"Pagination is not followed. Empty arrays validate unless minItems is specified. Optional fields may be absent.",
"Hourly scheduling is best effort. Missed slots, source errors and incomplete samples remain visible and cannot establish a healthy contract.",
"Alerts are private data returned by retrieve-monitor; no email, webhook or push delivery is included."
]
}
}
}
},
"404": {
"description": "Missing monitor or invalid capability",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "monitor_not_found"
}
}
}
},
"413": {
"description": "Request exceeds 2048 encoded bytes",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "request_unavailable"
}
}
}
},
"415": {
"description": "application/json required",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "request_unavailable"
}
}
}
},
"503": {
"description": "Temporary storage failure; retry the same request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "request_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "Authorization",
"required": true,
"description": "Bearer followed by the privately generated owner_key from the original purchase. Never put it in a URL.",
"schema": {
"type": "string",
"maxLength": 71
}
}
]Delete a monitor and cancel future observations
POST /v1/services/schema-monitors/delete-monitor
Follow the authentication, capability and prerequisite requirements below.
Delete a monitor and cancel future observations. Free private capability operation. Send the original owner_key as Authorization Bearer; no x402 payment is required.
Input fields
monitor_idRequired · string- Purchased monitor identity.
Response status
200- Private monitor result or deletion confirmation
404- Missing monitor or invalid capability
413- Request exceeds 2048 encoded bytes
415- application/json required
503- Temporary storage failure; retry the same request
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"monitor_id"
],
"additionalProperties": false,
"properties": {
"monitor_id": {
"type": "string",
"pattern": "^[a-f0-9]{48}$",
"description": "Purchased monitor identity."
}
}
},
"example": {
"monitor_id": "7ba23e2c5cc7c11246d33660534b28f6a250ef749ec15ba3"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Private monitor result or deletion confirmation",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"monitor_state"
],
"properties": {
"status": {
"type": "string",
"const": "ok"
},
"monitor_state": {
"type": "string",
"const": "deleted"
}
}
},
"example": {
"status": "ok",
"monitor_state": "deleted"
}
}
}
},
"404": {
"description": "Missing monitor or invalid capability",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "monitor_not_found"
}
}
}
},
"413": {
"description": "Request exceeds 2048 encoded bytes",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "request_unavailable"
}
}
}
},
"415": {
"description": "application/json required",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "request_unavailable"
}
}
}
},
"503": {
"description": "Temporary storage failure; retry the same request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "request_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "Authorization",
"required": true,
"description": "Bearer followed by the privately generated owner_key from the original purchase. Never put it in a URL.",
"schema": {
"type": "string",
"maxLength": 71
}
}
]Capture a website screenshot
POST /v1/web/pages/capture-screenshot
0.01 USDC per successful screenshot
Service scope, examples and recovery →
Capture a public HTTPS webpage as PNG or JPEG at a chosen desktop/mobile viewport, optionally its bounded full height. Return image bytes, dimensions, final URL, capture time and SHA-256. 0.01 USDC per successful capture; blocked, incomplete or oversized captures are uncharged. No login, CAPTCHA bypass or arbitrary scripting. Private original-proof recovery lasts 30 days.
Input fields
request_idRequired · string- See the complete request schema for values and bounds.
urlRequired · string- See the complete request schema for values and bounds.
widthOptional · integer- See the complete request schema for values and bounds.
heightOptional · integer- See the complete request schema for values and bounds.
full_pageOptional · boolean- See the complete request schema for values and bounds.
formatOptional · string- See the complete request schema for values and bounds.
Response status
200- Successful capture. Decode image_base64 to an image file; the timestamp identifies this capture. PAYMENT-RESPONSE confirms payment finality.
202- Payment pending. Retry identical input and proof; never create another payment.
400- Invalid input or payment; validate against this contract.
402- Input-bound quote with no browser work. Empty body yields a nonpayable discovery preflight. Sign only an offer for the intended capture.
409- The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.
413- Request exceeds 24000 decoded bytes.
415- application/json required.
503- Temporarily unavailable. Retry identical proof only.
429- API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.
410- Original result recovery expired.
422- Capture could not produce a useful supported image; uncharged.
504- Bounded work deadline exceeded. Retry original input and proof.
Complete schema: request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"url"
],
"properties": {
"request_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,64}$"
},
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"pattern": "^https://"
},
"width": {
"type": "integer",
"minimum": 320,
"maximum": 1920,
"default": 1280
},
"height": {
"type": "integer",
"minimum": 240,
"maximum": 2160,
"default": 900
},
"full_page": {
"type": "boolean",
"default": false
},
"format": {
"type": "string",
"enum": [
"png",
"jpeg"
],
"default": "png"
}
}
},
"example": {
"request_id": "screenshot_example_0001",
"url": "https://mekler.ai/",
"width": 1280,
"height": 900,
"full_page": false,
"format": "png"
}
}
}
}Complete schema: responses and errors
{
"200": {
"description": "Successful capture. Decode image_base64 to an image file; the timestamp identifies this capture. PAYMENT-RESPONSE confirms payment finality.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"final_url",
"title",
"captured_at",
"viewport",
"width",
"height",
"full_page",
"mime_type",
"image_base64",
"image_sha256",
"image_bytes",
"limitations"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"final_url": {
"type": "string"
},
"title": {
"type": "string"
},
"captured_at": {
"type": "string"
},
"viewport": {
"type": "object",
"required": [
"width",
"height"
],
"additionalProperties": false,
"properties": {
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
}
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"full_page": {
"type": "boolean"
},
"mime_type": {
"type": "string",
"enum": [
"image/png",
"image/jpeg"
]
},
"image_base64": {
"type": "string",
"description": "Base64-encoded complete image. Decode and save as PNG/JPEG; no public image URL."
},
"image_sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"image_bytes": {
"type": "integer"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"status": "ok",
"final_url": "https://mekler.ai/",
"title": "Mekler AI",
"captured_at": "2026-10-28T00:00:00+00:00",
"viewport": {
"width": 1280,
"height": 900
},
"width": 1280,
"height": 900,
"full_page": false,
"mime_type": "image/png",
"image_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jZ3sAAAAASUVORK5CYII=",
"image_sha256": "f0dd5aec26d234e99022c4a7b66538ec4650779a5ad278c8bb31c31bab09fc71",
"image_bytes": 68,
"limitations": [
"Prepared synthetic response; image bytes are a one-pixel placeholder. Actual captures contain the requested page dimensions."
]
}
}
},
"headers": {
"PAYMENT-RESPONSE": {
"description": "Base64 JSON settlement receipt: success, transaction, network, payer. Present only after finality.",
"schema": {
"type": "string"
}
},
"X-Mekler-Payment-State": {
"description": "finalized or provisional",
"schema": {
"type": "string"
}
},
"X-Mekler-Purchase-Id": {
"description": "Purchase ID on provisional results.",
"schema": {
"type": "string"
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "Payment pending. Retry identical input and proof; never create another payment.",
"headers": {
"Retry-After": {
"description": "Seconds before retrying identical body and proof.",
"schema": {
"type": "string",
"enum": [
"5"
]
}
},
"X-Mekler-Referral-Receipt": {
"description": "Optional base64 JSON attribution and locked-offer metadata. Does not alter the business result.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"payment_pending"
]
},
"purchase_id": {
"type": "string"
},
"retry": {
"type": "string"
}
},
"required": [
"status",
"purchase_id",
"retry"
]
},
"example": {
"status": "payment_pending",
"purchase_id": "example-purchase-id",
"retry": "Resend the identical request and PAYMENT-SIGNATURE. Do not pay again."
}
}
}
},
"400": {
"description": "Invalid input or payment; validate against this contract.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "invalid_request"
}
}
}
},
"402": {
"description": "Input-bound quote with no browser work. Empty body yields a nonpayable discovery preflight. Sign only an offer for the intended capture.",
"headers": {
"PAYMENT-REQUIRED": {
"description": "Base64 JSON x402 v2 quote for valid unsigned input. Expired/invalid-proof errors may omit this header.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
},
"preflight_only": {
"type": "boolean",
"description": "True only for an unsigned empty-body directory preflight; this offer must not be signed."
},
"next_step": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_required",
"price_usdc": "0.010000"
}
}
}
},
"409": {
"description": "The proof is already bound to another request, or its transaction failed. Inspect error and purchase_id; do not automatically create another payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_already_bound"
}
}
}
},
"413": {
"description": "Request exceeds 24000 decoded bytes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "body_too_large"
}
}
}
},
"415": {
"description": "application/json required.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "application_json_required"
}
}
}
},
"503": {
"description": "Temporarily unavailable. Retry identical proof only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"429": {
"description": "API gateway throttling. Respect Retry-After when supplied; otherwise back off. Preserve any existing payment proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
},
"example": {
"message": "Too Many Requests"
}
}
}
},
"410": {
"description": "Original result recovery expired.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"422": {
"description": "Capture could not produce a useful supported image; uncharged.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
},
"504": {
"description": "Bounded work deadline exceeded. Retry original input and proof.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retry": {
"type": "string"
},
"purchase_id": {
"type": "string"
},
"price_usdc": {
"type": "string"
}
},
"required": [
"error"
]
},
"example": {
"error": "payment_temporarily_unavailable"
}
}
}
}
}Complete schema: parameters and headers
[
{
"in": "header",
"name": "PAYMENT-SIGNATURE",
"required": false,
"schema": {
"type": "string"
},
"description": "x402 v2 signed payment. Resend the identical request and proof after a lost response."
}
]