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 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 exceeds8192bytes.
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 exceeds8192bytes.",
"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.001939 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": 1939,
"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": 1939,
"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": 1939,
"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.001939",
"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": 1939,
"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
}
}
]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 most12 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 last7 dates.
end_dateOptional · string- UTC monitoring date, inclusive, not future. Range at most7 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 most5 source-linked headline highlights; no full-text reading or generated claims.
sinceOptional · string- UTC follow-up checkpoint within the last7 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 exceeds4096 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 most12 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 last7 dates."
},
"end_date": {
"type": "string",
"maxLength": 10,
"format": "date",
"description": "UTC monitoring date, inclusive, not future. Range at most7 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 most5 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 last7 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 most12 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 most5 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 last7 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 exceeds4096 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."
}
]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 to20 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 for30days.
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 for30days.",
"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.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."
}
]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
[]
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.002 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.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."
}
]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 x402 protocol and discovery configuration with separate linter and compliance grades. Optional quote_mode fast returns a payable first 402; resend the same input with proof, save the job/capability and poll. Default preserves compute-first admission. Base or Solana, 0.05 USDC per completed scan. Failed or expired unfinished work is uncharged; never replace a pending proof. Reports expire after 24 hours. Probes never pay targets or certify paid delivery.
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"
}
}
},
"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
}
}
},
"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."
}
]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": 1939,
"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": 1939,
"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.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."
}
]