{ "openapi": "3.1.0", "info": { "title": "Brainiall Public Pilot Acquisition API", "version": "2026-06-10", "description": "Public-safe acquisition endpoints for human buyers and for AI agents (procurement, solution-evaluator, developer and marketplace agents) to discover Brainiall pilot offers, request deterministic non-binding quotes, and submit qualified interest for human review. No endpoint in this API binds a contract, authorizes spend, or triggers external action: every quote and lead is non-binding and requires Brainiall human approval before any commercial step (see x-brainiall-guardrails). Do not submit credentials, secrets, tokens, real PII, or confidential data; string values containing secret-like markers are rejected with error `sensitive_value_rejected`. Rate limits (per client IP, per endpoint, 60-second sliding window): 240 requests/min for public GET endpoints and 30 requests/min for public POST endpoints. When a limit is exceeded the API returns HTTP 429 with body {\"ok\": false, \"error\": \"rate_limited\", \"retry_after_seconds\": 60}. Rate-limit state is NOT exposed via response headers \u2014 only via the 429 JSON body. POST bodies are limited to 32768 bytes and every string field to 2000 characters. All responses are sent with Cache-Control: no-store.", "termsOfService": "https://app.brainiall.com/terms", "contact": { "name": "Brainiall", "url": "https://app.brainiall.com" }, "x-legal-terms-json": "https://app.brainiall.com/legal/pilot-terms.json" }, "servers": [ { "url": "https://app.brainiall.com" } ], "x-brainiall-guardrails": { "human_approval_required": true, "external_actions_authorized": false, "sensitive_data_allowed": false, "production_fallback_capture_allowed": false }, "tags": [ { "name": "Discovery", "description": "Public catalog endpoints for human buyers and AI agents." }, { "name": "Quotes", "description": "Deterministic, non-binding pilot quotes. Human approval is required before any quote becomes an order." }, { "name": "Leads", "description": "Qualified-interest submissions. Every lead is scored deterministically and queued for human review; no automated outreach or contract action results from submission." }, { "name": "Schemas", "description": "Canonical JSON Schema (draft 2020-12) documents for request validation by AI agents." } ], "paths": { "/api/offers": { "get": { "operationId": "listPilotOffers", "tags": [ "Discovery" ], "summary": "List public Brainiall pilot offers", "description": "Returns the public summary of every Brainiall pilot offer: pricing, duration, annual commit minimum, required inputs, allowed deployment modes, and published credit-back terms. Every offer is non-binding and human-approval gated. Rate limit: 240 requests per 60-second sliding window per client IP for this endpoint; on excess, HTTP 429 with `retry_after_seconds` in the body (no rate-limit headers are returned).", "x-rate-limit": { "scope": "per_client_ip_per_endpoint", "algorithm": "sliding_window", "window_seconds": 60, "max_requests": 240, "on_limit_status": 429, "on_limit_body": { "ok": false, "error": "rate_limited", "retry_after_seconds": 60 }, "rate_limit_response_headers": false }, "responses": { "200": { "description": "Public offer list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferList" }, "examples": { "offerList": { "summary": "Public offer list with both published credit-back shapes", "value": { "currency": "USD", "offers": [ { "id": "trust-safety-review-queue-pilot", "name": "Trust & Safety Review Queue Pilot", "headline": "Reduce review backlog and policy inconsistency without autonomous enforcement.", "duration_days": 14, "pilot_price": 12500, "annual_commit_minimum": 60000, "required_inputs": [ "queue owner", "5000-25000 anonymized historical cases or smaller representative sample", "policy taxonomy", "success metric", "false-positive ceiling" ], "allowed_modes": [ "offline", "shadow", "human_in_the_loop" ], "credit": { "type": "fixed_credit_back", "min_credit": 5000, "max_credit": 8000, "expiration_days": 30, "applies_to": "platform_usage_only", "cash_value": false }, "sample_package_url": "https://app.brainiall.com/pilots/samples/brainiall-sample-evidence-trust-safety.pdf", "non_binding": true, "human_approval_required": true }, { "id": "agent-governance-evidence-pilot", "name": "Agent Governance Evidence Pilot", "headline": "Prove one agent workflow is safe enough to promote.", "duration_days": 30, "pilot_price": 25000, "annual_commit_minimum": 120000, "required_inputs": [ "workflow owner", "50-200 representative samples", "success metric", "risk owner", "target launch window" ], "allowed_modes": [ "staging", "read_only", "shadow", "human_in_the_loop" ], "credit": { "type": "partial_credit_back", "max_percent_of_pilot": 50, "expiration_days": 30, "applies_to": "platform_usage_only", "cash_value": false }, "sample_package_url": "https://app.brainiall.com/pilots/samples/brainiall-sample-evidence-agent-governance.pdf", "non_binding": true, "human_approval_required": true } ] } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/quote": { "post": { "operationId": "requestNonBindingQuote", "tags": [ "Quotes" ], "summary": "Request a non-binding pilot quote", "description": "Computes a deterministic, non-binding quote for one pilot offer and records it for human review. Pricing rules (exact server behavior): pilot_price starts at the offer's published price and is multiplied by 1.4 when `custom_integration` is true (with a change-order warning). The 30-day credit (`max_credit_if_annual_signed_within_30_days`) is computed from the offer's published credit terms and the provided `annual_commit` (defaulting to the offer's `annual_commit_minimum` when omitted): for `fixed_credit_back` offers it is 15% of the commit clamped to the published [min_credit, max_credit] range; for `partial_credit_back` offers it is min(max_percent_of_pilot% of the quoted pilot price, 15% of the commit). In both cases the credit is 0 when the provided commit is below `annual_commit_minimum`, and a warning explains that credit-back eligibility starts at the minimum commit. Request processing order: rate limit (429) \u2192 body size (413) \u2192 JSON parse (400 invalid_json) \u2192 field length (400 field_too_long) \u2192 secret-like values (400 sensitive_value_rejected) \u2192 required fields (400 missing_required_fields) \u2192 Idempotency-Key replay (200 with idempotent_replay) \u2192 offer lookup (404 offer_not_found) \u2192 quote creation (200). Rate limit: 30 requests per 60-second sliding window per client IP for this endpoint; no rate-limit headers are returned. The quote never binds a contract: `non_binding` and `human_approval_required` are always true.", "x-rate-limit": { "scope": "per_client_ip_per_endpoint", "algorithm": "sliding_window", "window_seconds": 60, "max_requests": 30, "on_limit_status": 429, "on_limit_body": { "ok": false, "error": "rate_limited", "retry_after_seconds": 60 }, "rate_limit_response_headers": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "standardCommit": { "summary": "Quote at an $80,000 annual commit (credit clamps to max_credit $8,000)", "value": { "offer_id": "trust-safety-review-queue-pilot", "annual_commit": 80000, "samples_available": true } }, "belowMinimumCommit": { "summary": "Commit below the offer minimum (credit = 0 with warning)", "value": { "offer_id": "trust-safety-review-queue-pilot", "annual_commit": 40000, "samples_available": true } } } } } }, "responses": { "200": { "description": "Quote created (or replayed when the Idempotency-Key matched a previously stored quote).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "examples": { "newQuote": { "summary": "Fresh quote: 15% of $80,000 = $12,000, clamped to max_credit $8,000", "value": { "ok": true, "quote": { "quote_id": "quote_3f9a1b2c4d5e", "created_at": "2026-06-10T14:32:11.482919+00:00", "offer_id": "trust-safety-review-queue-pilot", "offer_name": "Trust & Safety Review Queue Pilot", "pilot_price": 12500.0, "annual_commit_minimum": 60000, "provided_annual_commit": 80000.0, "max_credit_if_annual_signed_within_30_days": 8000.0, "credit_rules": { "expires_days": 30, "applies_to": "platform_usage_only", "cash_value": false, "non_refundable": true }, "warnings": [], "non_binding": true, "human_approval_required": true, "idempotency_key": "quote-tsrq-2026-06-10-001" } } }, "belowMinimumCommit": { "summary": "Commit $40,000 is below the $60,000 minimum: credit 0 plus warning", "value": { "ok": true, "quote": { "quote_id": "quote_9c2d4e6f8a1b", "created_at": "2026-06-10T14:35:02.110204+00:00", "offer_id": "trust-safety-review-queue-pilot", "offer_name": "Trust & Safety Review Queue Pilot", "pilot_price": 12500.0, "annual_commit_minimum": 60000, "provided_annual_commit": 40000.0, "max_credit_if_annual_signed_within_30_days": 0.0, "credit_rules": { "expires_days": 30, "applies_to": "platform_usage_only", "cash_value": false, "non_refundable": true }, "warnings": [ "Provided annual commit is below the offer minimum ($60,000); credit-back eligibility starts at the minimum commit." ], "non_binding": true, "human_approval_required": true, "idempotency_key": null } } }, "idempotentReplay": { "summary": "Retry with the same Idempotency-Key returns the stored quote", "value": { "ok": true, "quote": { "quote_id": "quote_3f9a1b2c4d5e", "created_at": "2026-06-10T14:32:11.482919+00:00", "offer_id": "trust-safety-review-queue-pilot", "offer_name": "Trust & Safety Review Queue Pilot", "pilot_price": 12500.0, "annual_commit_minimum": 60000, "provided_annual_commit": 80000.0, "max_credit_if_annual_signed_within_30_days": 8000.0, "credit_rules": { "expires_days": 30, "applies_to": "platform_usage_only", "cash_value": false, "non_refundable": true }, "warnings": [], "non_binding": true, "human_approval_required": true, "idempotency_key": "quote-tsrq-2026-06-10-001" }, "idempotent_replay": true } } } } } }, "400": { "description": "Invalid request: malformed JSON, missing required fields, a string field over 2000 characters, or a value containing secret-like content.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorMissingRequiredFields" }, { "$ref": "#/components/schemas/ErrorFieldTooLong" }, { "$ref": "#/components/schemas/ErrorSensitiveValueRejected" }, { "$ref": "#/components/schemas/ErrorInvalidJson" } ] }, "examples": { "missingRequiredFields": { "value": { "ok": false, "error": "missing_required_fields", "fields": [ "offer_id" ] } }, "fieldTooLong": { "value": { "ok": false, "error": "field_too_long", "fields": [ "offer_id" ], "max_chars": 2000 } }, "sensitiveValueRejected": { "value": { "ok": false, "error": "sensitive_value_rejected", "fields": [ "offer_id" ], "message": "Do not submit credentials, secrets, tokens or confidential data through public acquisition endpoints." } }, "invalidJson": { "value": { "ok": false, "error": "invalid_json" } } } } } }, "404": { "description": "The offer_id does not match any published offer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOfferNotFound" }, "examples": { "offerNotFound": { "value": { "ok": false, "error": "offer_not_found" } } } } } }, "413": { "description": "Request body exceeds the 32768-byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorPayloadTooLarge" }, "examples": { "payloadTooLarge": { "value": { "ok": false, "error": "payload_too_large", "max_bytes": 32768 } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/lead": { "post": { "operationId": "submitQualifiedInterest", "tags": [ "Leads" ], "summary": "Submit qualified interest for human review", "description": "Records a qualified-interest lead from a human buyer or an AI agent acting on a buyer's behalf, scores it deterministically (0-100, bands A-D) against published scoring rules, and queues it for human review. Submission never triggers outreach, contract, or spend: `external_action_authorized` is always false and `next_step` is always \"human review required\". `contact_consent` must be exactly true and required text fields must be non-empty after trimming, otherwise 400 missing_required_fields. `target_offer_id` is not validated against the catalog at submission time \u2014 use an id from GET /api/offers so human review can match it. Extra request properties beyond the documented set (including `risk_constraints` and `notes`) are accepted and pass the same length and sensitive-value checks, but only the documented lead-record fields are persisted and echoed back. Request processing order: rate limit (429) \u2192 body size (413) \u2192 JSON parse (400 invalid_json) \u2192 field length (400 field_too_long) \u2192 secret-like values (400 sensitive_value_rejected) \u2192 required fields (400 missing_required_fields) \u2192 Idempotency-Key replay (200 with idempotent_replay) \u2192 lead creation (200). Rate limit: 30 requests per 60-second sliding window per client IP for this endpoint; no rate-limit headers are returned. Privacy: submit anonymized samples and business contact data only \u2014 no credentials, secrets, or real end-user PII.", "x-rate-limit": { "scope": "per_client_ip_per_endpoint", "algorithm": "sliding_window", "window_seconds": 60, "max_requests": 30, "on_limit_status": 429, "on_limit_body": { "ok": false, "error": "rate_limited", "retry_after_seconds": 60 }, "rate_limit_response_headers": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadRequest" }, "examples": { "aiProcurementAgentLead": { "summary": "AI procurement agent submitting qualified interest for a trust & safety pilot", "value": { "buyer_type": "ai_procurement_agent", "company": "Acme Marketplace Inc", "contact_or_agent_id": "procurement-agent@acmemarketplace.example", "workflow": "Marketplace listing review queue triage", "target_offer_id": "trust-safety-review-queue-pilot", "success_metric": "False-positive rate below 2% with 30% backlog reduction", "contact_consent": true, "monthly_volume": 150000, "samples_available": true, "risk_constraints": "Anonymized historical cases only; no production PII until legal terms are approved.", "notes": "Evaluating on behalf of the VP Trust & Safety; human signer will join the review call." } } } } } }, "responses": { "200": { "description": "Lead recorded and scored (or replayed when the Idempotency-Key matched a previously stored lead).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" }, "examples": { "newLead": { "summary": "Lead scored 80 (band A): workflow 20 + samples 25 + success metric 20 + high volume 15", "value": { "ok": true, "lead": { "lead_id": "lead_7d1e3f5a9b2c", "created_at": "2026-06-10T14:40:27.918331+00:00", "source": "local_revenue_system", "buyer_type": "ai_procurement_agent", "contact_name": null, "contact_role": null, "company": "Acme Marketplace Inc", "contact_or_agent_id": "procurement-agent@acmemarketplace.example", "timeline": null, "workflow": "Marketplace listing review queue triage", "target_offer_id": "trust-safety-review-queue-pilot", "success_metric": "False-positive rate below 2% with 30% backlog reduction", "monthly_volume": 150000, "samples_available": true, "risk_owner": null, "annual_commit": null, "score": 80, "band": "A", "reasons": [ "Workflow named", "Representative samples available", "Success metric named", "High volume or high-risk workflow", "Founder handles immediately; propose pilot review" ], "external_action_authorized": false, "contact_consent": true, "idempotency_key": "lead-acme-2026-06-10-001", "next_step": "human review required" } } }, "idempotentReplay": { "summary": "Retry with the same Idempotency-Key returns the stored lead", "value": { "ok": true, "lead": { "lead_id": "lead_7d1e3f5a9b2c", "created_at": "2026-06-10T14:40:27.918331+00:00", "source": "local_revenue_system", "buyer_type": "ai_procurement_agent", "contact_name": null, "contact_role": null, "company": "Acme Marketplace Inc", "contact_or_agent_id": "procurement-agent@acmemarketplace.example", "timeline": null, "workflow": "Marketplace listing review queue triage", "target_offer_id": "trust-safety-review-queue-pilot", "success_metric": "False-positive rate below 2% with 30% backlog reduction", "monthly_volume": 150000, "samples_available": true, "risk_owner": null, "annual_commit": null, "score": 80, "band": "A", "reasons": [ "Workflow named", "Representative samples available", "Success metric named", "High volume or high-risk workflow", "Founder handles immediately; propose pilot review" ], "external_action_authorized": false, "contact_consent": true, "idempotency_key": "lead-acme-2026-06-10-001", "next_step": "human review required" }, "idempotent_replay": true } } } } } }, "400": { "description": "Invalid request: malformed JSON, missing required fields (including contact_consent not exactly true), a string field over 2000 characters, or a value containing secret-like content.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorMissingRequiredFields" }, { "$ref": "#/components/schemas/ErrorFieldTooLong" }, { "$ref": "#/components/schemas/ErrorSensitiveValueRejected" }, { "$ref": "#/components/schemas/ErrorInvalidJson" } ] }, "examples": { "missingRequiredFields": { "value": { "ok": false, "error": "missing_required_fields", "fields": [ "success_metric", "contact_consent" ] } }, "fieldTooLong": { "value": { "ok": false, "error": "field_too_long", "fields": [ "notes" ], "max_chars": 2000 } }, "sensitiveValueRejected": { "value": { "ok": false, "error": "sensitive_value_rejected", "fields": [ "notes" ], "message": "Do not submit credentials, secrets, tokens or confidential data through public acquisition endpoints." } }, "invalidJson": { "value": { "ok": false, "error": "invalid_json" } } } } } }, "413": { "description": "Request body exceeds the 32768-byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorPayloadTooLarge" }, "examples": { "payloadTooLarge": { "value": { "ok": false, "error": "payload_too_large", "max_bytes": 32768 } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/agent/catalog": { "get": { "operationId": "getAgentCatalog", "tags": [ "Discovery" ], "summary": "Machine-readable catalog for AI-agent evaluators", "description": "Agent-readable discovery document: endpoint map, supported buyer types, explicitly allowed and disallowed agent actions, privacy notice, and the full public offer list. AI agents should treat `disallowed_agent_actions` as hard constraints \u2014 this API never authorizes binding a contract, authorizing spend, external outreach, submitting sensitive data, or bypassing human approval. Rate limit: 240 requests per 60-second sliding window per client IP for this endpoint.", "x-rate-limit": { "scope": "per_client_ip_per_endpoint", "algorithm": "sliding_window", "window_seconds": 60, "max_requests": 240, "on_limit_status": 429, "on_limit_body": { "ok": false, "error": "rate_limited", "retry_after_seconds": 60 }, "rate_limit_response_headers": false }, "responses": { "200": { "description": "Agent-readable catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCatalog" }, "examples": { "agentCatalog": { "summary": "Agent catalog (offers array abbreviated to one entry)", "value": { "name": "Brainiall Agent-Readable Pilot Catalog", "version": "2026-06-10", "vendor": "Brainiall", "description": "Public-safe discovery catalog for human buyers and AI procurement or evaluator agents.", "base_url": "https://app.brainiall.com", "endpoints": { "offers": "/api/offers", "quote": "/api/quote", "lead": "/api/lead", "agent_catalog": "/api/agent/catalog", "openapi": "/openapi.json", "lead_schema": "/schemas/lead.schema.json", "quote_schema": "/schemas/quote-request.schema.json" }, "supported_buyer_types": [ "human_buyer", "ai_procurement_agent", "ai_solution_evaluator", "ai_developer_agent", "ai_marketplace_agent" ], "allowed_agent_actions": [ "read_catalog", "request_quote", "submit_qualified_interest" ], "disallowed_agent_actions": [ "bind_contract", "authorize_spend", "authorize_external_outreach", "submit_sensitive_data", "bypass_human_approval" ], "privacy_notice": "Do not submit confidential data or real PII through discovery endpoints. Use anonymized samples until legal terms are approved.", "human_approval_required": true, "external_actions_authorized": false, "offers": [ { "id": "trust-safety-review-queue-pilot", "name": "Trust & Safety Review Queue Pilot", "headline": "Reduce review backlog and policy inconsistency without autonomous enforcement.", "duration_days": 14, "pilot_price": 12500, "annual_commit_minimum": 60000, "required_inputs": [ "queue owner", "5000-25000 anonymized historical cases or smaller representative sample", "policy taxonomy", "success metric", "false-positive ceiling" ], "allowed_modes": [ "offline", "shadow", "human_in_the_loop" ], "credit": { "type": "fixed_credit_back", "min_credit": 5000, "max_credit": 8000, "expiration_days": 30, "applies_to": "platform_usage_only", "cash_value": false }, "sample_package_url": "https://app.brainiall.com/pilots/samples/brainiall-sample-evidence-trust-safety.pdf", "non_binding": true, "human_approval_required": true } ] } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/.well-known/brainiall-agent-catalog.json": { "get": { "operationId": "getWellKnownAgentCatalog", "tags": [ "Discovery" ], "summary": "Well-known agent catalog", "description": "Identical payload to GET /api/agent/catalog, served at a well-known location so AI agents can discover the catalog without prior knowledge of the API surface. Rate limit: 240 requests per 60-second sliding window per client IP for this endpoint.", "x-rate-limit": { "scope": "per_client_ip_per_endpoint", "algorithm": "sliding_window", "window_seconds": 60, "max_requests": 240, "on_limit_status": 429, "on_limit_body": { "ok": false, "error": "rate_limited", "retry_after_seconds": 60 }, "rate_limit_response_headers": false }, "responses": { "200": { "description": "Agent-readable catalog (same shape and content as /api/agent/catalog).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCatalog" }, "examples": { "agentCatalog": { "summary": "Abbreviated example \u2014 see GET /api/agent/catalog for the full payload", "value": { "name": "Brainiall Agent-Readable Pilot Catalog", "version": "2026-06-10", "vendor": "Brainiall", "description": "Public-safe discovery catalog for human buyers and AI procurement or evaluator agents.", "base_url": "https://app.brainiall.com", "endpoints": { "offers": "/api/offers", "quote": "/api/quote", "lead": "/api/lead", "agent_catalog": "/api/agent/catalog", "openapi": "/openapi.json", "lead_schema": "/schemas/lead.schema.json", "quote_schema": "/schemas/quote-request.schema.json" }, "supported_buyer_types": [ "human_buyer", "ai_procurement_agent", "ai_solution_evaluator", "ai_developer_agent", "ai_marketplace_agent" ], "allowed_agent_actions": [ "read_catalog", "request_quote", "submit_qualified_interest" ], "disallowed_agent_actions": [ "bind_contract", "authorize_spend", "authorize_external_outreach", "submit_sensitive_data", "bypass_human_approval" ], "privacy_notice": "Do not submit confidential data or real PII through discovery endpoints. Use anonymized samples until legal terms are approved.", "human_approval_required": true, "external_actions_authorized": false, "offers": [] } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schemas/lead.schema.json": { "get": { "operationId": "getLeadSchema", "tags": [ "Schemas" ], "summary": "Lead request JSON Schema", "description": "Canonical JSON Schema (draft 2020-12) for the POST /api/lead request body. AI agents should validate lead submissions against this document before posting. Rate limit: 240 requests per 60-second sliding window per client IP for this endpoint.", "x-rate-limit": { "scope": "per_client_ip_per_endpoint", "algorithm": "sliding_window", "window_seconds": 60, "max_requests": 240, "on_limit_status": 429, "on_limit_body": { "ok": false, "error": "rate_limited", "retry_after_seconds": 60 }, "rate_limit_response_headers": false }, "responses": { "200": { "description": "JSON Schema document for lead submissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonSchemaDocument" }, "examples": { "leadSchema": { "summary": "Canonical lead schema as served", "value": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://app.brainiall.com/schemas/lead.schema.json", "title": "Brainiall qualified interest lead", "type": "object", "additionalProperties": true, "required": [ "buyer_type", "company", "contact_or_agent_id", "workflow", "target_offer_id", "success_metric", "contact_consent" ], "properties": { "source": { "type": "string" }, "buyer_type": { "type": "string", "enum": [ "human_buyer", "ai_procurement_agent", "partner_agent", "ai_solution_evaluator", "ai_developer_agent", "ai_marketplace_agent" ] }, "contact_name": { "type": "string" }, "contact_role": { "type": "string" }, "company": { "type": "string" }, "contact_or_agent_id": { "type": "string" }, "timeline": { "type": "string" }, "workflow": { "type": "string" }, "target_offer_id": { "type": "string" }, "success_metric": { "type": "string" }, "monthly_volume": { "type": "number" }, "samples_available": { "type": "boolean" }, "risk_owner": { "type": "string" }, "contact_consent": { "type": "boolean", "const": true }, "high_volume_or_high_risk": { "type": "boolean" }, "annual_commit": { "type": "number" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schemas/quote-request.schema.json": { "get": { "operationId": "getQuoteSchema", "tags": [ "Schemas" ], "summary": "Quote request JSON Schema", "description": "Canonical JSON Schema (draft 2020-12) for the POST /api/quote request body. AI agents should validate quote requests against this document before posting. Rate limit: 240 requests per 60-second sliding window per client IP for this endpoint.", "x-rate-limit": { "scope": "per_client_ip_per_endpoint", "algorithm": "sliding_window", "window_seconds": 60, "max_requests": 240, "on_limit_status": 429, "on_limit_body": { "ok": false, "error": "rate_limited", "retry_after_seconds": 60 }, "rate_limit_response_headers": false }, "responses": { "200": { "description": "JSON Schema document for quote requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonSchemaDocument" }, "examples": { "quoteRequestSchema": { "summary": "Canonical quote-request schema as served", "value": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://app.brainiall.com/schemas/quote-request.schema.json", "title": "Brainiall non-binding quote request", "type": "object", "additionalProperties": false, "required": [ "offer_id" ], "properties": { "offer_id": { "type": "string" }, "annual_commit": { "type": "number", "minimum": 0 }, "samples_available": { "type": "boolean" }, "custom_integration": { "type": "boolean" }, "pii_real": { "type": "boolean" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional client-chosen key for safe retries. If a previously stored record (quote or lead, per endpoint) carries the same key, the API returns that stored record with HTTP 200 and `idempotent_replay: true` instead of creating a new one \u2014 the request body of the retry is NOT re-evaluated or compared, so reuse a key only for retries of the exact same payload. When no stored record matches, a new record is created and the key is persisted on it (echoed back as `idempotency_key`). Validation errors (4xx) are never cached or replayed. Without this header every accepted POST creates a new record.", "schema": { "type": "string", "maxLength": 2000, "examples": [ "quote-tsrq-2026-06-10-001" ] } } }, "responses": { "RateLimited": { "description": "Rate limit exceeded for this endpoint (per client IP, 60-second sliding window: 240/min for GET endpoints, 30/min for POST endpoints). Retry timing is provided ONLY in the JSON body (`retry_after_seconds` = the window length in seconds); no Retry-After or RateLimit-* response headers are returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorRateLimited" }, "examples": { "rateLimited": { "value": { "ok": false, "error": "rate_limited", "retry_after_seconds": 60 } } } } } } }, "schemas": { "CreditTerms": { "type": "object", "description": "Published credit-back terms for an offer. `fixed_credit_back` offers publish a [min_credit, max_credit] clamp range; `partial_credit_back` offers publish max_percent_of_pilot. Credits apply to platform usage only, have no cash value, and expire `expiration_days` after pilot completion if the annual agreement is not signed.", "properties": { "type": { "type": "string", "enum": [ "fixed_credit_back", "partial_credit_back" ], "description": "Credit mechanism. fixed_credit_back: 15% of the annual commit clamped to [min_credit, max_credit]. partial_credit_back: min(max_percent_of_pilot% of the pilot price, 15% of the annual commit). Both are 0 when the commit is below the offer's annual_commit_minimum." }, "min_credit": { "type": "number", "description": "Lower clamp bound in USD (fixed_credit_back offers only)." }, "max_credit": { "type": "number", "description": "Upper clamp bound in USD (fixed_credit_back offers only)." }, "max_percent_of_pilot": { "type": "number", "description": "Maximum credit as a percentage of the quoted pilot price (partial_credit_back offers only)." }, "expiration_days": { "type": "integer", "description": "Days after pilot completion within which the annual agreement must be signed for the credit to apply.", "default": 30 }, "applies_to": { "type": "string", "description": "What the credit can be applied to.", "default": "platform_usage_only" }, "cash_value": { "type": "boolean", "const": false, "description": "Credits never have cash value." } } }, "Offer": { "type": "object", "description": "Public summary of one Brainiall pilot offer. Always non-binding and human-approval gated.", "required": [ "id", "name", "headline", "duration_days", "pilot_price", "annual_commit_minimum", "required_inputs", "allowed_modes", "credit", "non_binding", "human_approval_required" ], "properties": { "id": { "type": "string", "description": "Stable offer identifier. Use as `offer_id` in POST /api/quote and `target_offer_id` in POST /api/lead.", "examples": [ "trust-safety-review-queue-pilot" ] }, "name": { "type": "string", "description": "Human-readable offer name.", "examples": [ "Trust & Safety Review Queue Pilot" ] }, "headline": { "type": "string", "description": "One-line positioning of the pilot outcome." }, "duration_days": { "type": "integer", "description": "Pilot duration in days." }, "pilot_price": { "type": "number", "description": "Standard pilot price in USD before any custom-integration uplift." }, "annual_commit_minimum": { "type": "number", "description": "Minimum annual commit in USD for credit-back eligibility. Quotes with a provided commit below this value carry a credit of 0 and a warning." }, "required_inputs": { "type": "array", "items": { "type": "string" }, "description": "Inputs the buyer must provide before the pilot can start (owners, anonymized samples, success metric, etc.)." }, "allowed_modes": { "type": "array", "items": { "type": "string" }, "description": "Deployment modes permitted during the pilot (e.g. offline, shadow, staging, read_only, human_in_the_loop). Autonomous production action is never an allowed pilot mode." }, "credit": { "$ref": "#/components/schemas/CreditTerms" }, "sample_package_url": { "type": "string", "format": "uri-reference", "description": "URL of the public anonymized sample evidence package for this offer (deliverable examples with no real customer data). Present when a sample package has been published for the offer." }, "non_binding": { "type": "boolean", "const": true, "description": "Always true: offer listings never bind a contract." }, "human_approval_required": { "type": "boolean", "const": true, "description": "Always true: a Brainiall human must approve any commercial step." }, "sample_package_json_url": { "type": "string", "description": "Machine-readable JSON twin of the sample evidence package PDF.", "format": "uri-reference" }, "deliverables_ownership": { "type": "string", "description": "Buyer keeps all evidence deliverables regardless of verdict." }, "mid_pilot_checkpoint": { "type": "object", "description": "Mid-pilot stop/continue checkpoint with phased billing (50% at start, 50% at checkpoint).", "properties": { "day": { "type": "integer", "description": "Pilot day of the checkpoint." }, "billing": { "type": "string" }, "stop_right": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_founder_ratification", "committed" ] } } } } }, "OfferList": { "type": "object", "description": "Response of GET /api/offers.", "required": [ "currency", "offers" ], "properties": { "currency": { "type": "string", "description": "Currency for all monetary fields.", "examples": [ "USD" ] }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } }, "QuoteRequest": { "type": "object", "description": "Request body for POST /api/quote. Canonical contract: https://app.brainiall.com/schemas/quote-request.schema.json (additionalProperties: false \u2014 unknown fields are ignored by the server but are invalid per the canonical contract). All string fields are limited to 2000 characters and must not contain secret-like values.", "additionalProperties": false, "required": [ "offer_id" ], "properties": { "offer_id": { "type": "string", "description": "Offer identifier from GET /api/offers. Must be a non-empty string; unknown ids return 404 offer_not_found.", "examples": [ "trust-safety-review-queue-pilot" ] }, "annual_commit": { "type": "number", "minimum": 0, "description": "Intended annual commit in USD used for the deterministic credit computation. If omitted, the offer's annual_commit_minimum is used. Values below the offer minimum produce a credit of 0 and a warning." }, "custom_integration": { "type": "boolean", "default": false, "description": "Set true if custom integration beyond base pilot scope is needed. Multiplies the quoted pilot_price by 1.4 and adds a change-order warning." }, "pii_real": { "type": "boolean", "default": false, "description": "Set true if real end-user PII would be involved. Adds a warning that a data processing agreement, retention/deletion terms, subprocessor disclosure, and a named risk owner are required before the pilot. Do NOT submit any actual PII through this API." }, "samples_available": { "type": "boolean", "default": false, "description": "Set true if representative (anonymized) samples are available. When false or omitted, the quote carries a warning that samples are required before a paid pilot proposal." } } }, "CreditRules": { "type": "object", "description": "Credit conditions attached to a quote.", "required": [ "expires_days", "applies_to", "cash_value", "non_refundable" ], "properties": { "expires_days": { "type": "integer", "description": "Days after pilot completion within which the annual agreement must be signed for the credit to apply (from the offer's published credit terms; 30 when unspecified)." }, "applies_to": { "type": "string", "description": "What the credit can be applied to.", "examples": [ "platform_usage_only" ] }, "cash_value": { "type": "boolean", "const": false, "description": "Always false: credits have no cash value." }, "non_refundable": { "type": "boolean", "const": true, "description": "Always true: credits are non-refundable." } } }, "Quote": { "type": "object", "description": "A deterministic, non-binding pilot quote. Recorded for human review; never an order, invoice, or contract.", "required": [ "quote_id", "created_at", "offer_id", "offer_name", "pilot_price", "annual_commit_minimum", "provided_annual_commit", "max_credit_if_annual_signed_within_30_days", "credit_rules", "warnings", "non_binding", "human_approval_required", "idempotency_key" ], "properties": { "quote_id": { "type": "string", "description": "Server-generated quote identifier (prefix `quote_`).", "examples": [ "quote_3f9a1b2c4d5e" ] }, "created_at": { "type": "string", "format": "date-time", "description": "UTC creation timestamp (ISO 8601)." }, "offer_id": { "type": "string", "description": "The quoted offer's identifier." }, "offer_name": { "type": "string", "description": "The quoted offer's human-readable name." }, "pilot_price": { "type": "number", "description": "Quoted pilot price in USD, rounded to 2 decimals: the offer's standard price, multiplied by 1.4 when custom_integration was requested." }, "annual_commit_minimum": { "type": "number", "description": "The offer's published minimum annual commit in USD for credit-back eligibility." }, "provided_annual_commit": { "type": "number", "description": "Annual commit used for the credit computation: the request's annual_commit, or the offer's annual_commit_minimum when omitted." }, "max_credit_if_annual_signed_within_30_days": { "type": "number", "description": "Deterministic maximum credit in USD, rounded to 2 decimals. fixed_credit_back offers: 15% of provided_annual_commit clamped to the published [min_credit, max_credit] range. partial_credit_back offers: min(max_percent_of_pilot% of the quoted pilot_price, 15% of provided_annual_commit). Always 0 when provided_annual_commit is below annual_commit_minimum (a warning is added). Example: $80,000 commit on a fixed_credit_back offer with range [$5,000, $8,000] yields 15% \u00d7 80,000 = $12,000, clamped to $8,000." }, "credit_rules": { "$ref": "#/components/schemas/CreditRules" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Conditions attached to the quote. Possible warnings: custom integration is out of base pilot scope and requires a change order; real PII requires DPA, retention/deletion terms, subprocessors and a risk owner before the pilot; representative samples are required before a paid pilot proposal; provided annual commit is below the offer minimum so credit-back eligibility starts at the minimum commit." }, "non_binding": { "type": "boolean", "const": true, "description": "Always true: this quote does not bind either party." }, "human_approval_required": { "type": "boolean", "const": true, "description": "Always true: a Brainiall human must approve before any commercial step." }, "idempotency_key": { "type": [ "string", "null" ], "description": "Echo of the Idempotency-Key request header, or null when none was sent." } } }, "QuoteResponse": { "type": "object", "description": "Successful response of POST /api/quote.", "required": [ "ok", "quote" ], "properties": { "ok": { "type": "boolean", "const": true }, "quote": { "$ref": "#/components/schemas/Quote" }, "idempotent_replay": { "type": "boolean", "const": true, "description": "Present (true) only when the Idempotency-Key matched a previously stored quote and that stored quote was returned instead of creating a new one. Absent on fresh quotes." } } }, "LeadRequest": { "type": "object", "description": "Request body for POST /api/lead. Canonical contract: https://app.brainiall.com/schemas/lead.schema.json (additionalProperties: true). Required text fields must be non-empty after trimming and contact_consent must be exactly true. All string fields are limited to 2000 characters and must not contain secret-like values. Extra properties (including risk_constraints and notes) are accepted and validated, but only the documented lead-record fields are persisted and echoed back in the response.", "additionalProperties": true, "required": [ "buyer_type", "company", "contact_or_agent_id", "workflow", "target_offer_id", "success_metric", "contact_consent" ], "properties": { "buyer_type": { "type": "string", "enum": [ "human_buyer", "ai_procurement_agent", "partner_agent", "ai_solution_evaluator", "ai_developer_agent", "ai_marketplace_agent" ], "description": "Who is submitting: a human buyer or an AI agent class acting on a buyer's behalf." }, "company": { "type": "string", "description": "Buyer company name." }, "contact_or_agent_id": { "type": "string", "description": "Email, handle, or stable AI-agent identifier Brainiall can use for human follow-up." }, "workflow": { "type": "string", "description": "The single concrete workflow the pilot would address. Naming a workflow contributes to the lead score." }, "target_offer_id": { "type": "string", "description": "Offer id from GET /api/offers this interest targets. Not validated against the catalog at submission time.", "examples": [ "trust-safety-review-queue-pilot" ] }, "success_metric": { "type": "string", "description": "How pilot success would be measured. Naming a metric contributes to the lead score." }, "contact_consent": { "type": "boolean", "const": true, "description": "Must be exactly true: consent for Brainiall to follow up using contact_or_agent_id. Any other value is rejected as missing_required_fields." }, "monthly_volume": { "type": "number", "description": "Approximate monthly volume of the workflow (items, cases, calls). Volumes of 100000 or more mark the lead as high-volume for scoring." }, "samples_available": { "type": "boolean", "description": "Whether representative anonymized samples are available. Contributes to the lead score." }, "risk_constraints": { "type": "string", "description": "Optional free text describing deployment or risk constraints (e.g. anonymized-data-only requirements). Accepted and validated for length and sensitive content, but not persisted as a structured field on the lead record \u2014 name a risk owner in risk_owner for anything that must influence scoring." }, "notes": { "type": "string", "description": "Optional free-text context for the human reviewer. Accepted and validated for length and sensitive content, but not persisted as a structured field on the lead record." }, "source": { "type": "string", "description": "Optional origin label for the submission. Defaults to local_revenue_system when omitted." }, "contact_name": { "type": "string", "description": "Optional human contact name." }, "contact_role": { "type": "string", "description": "Optional human contact role/title." }, "timeline": { "type": "string", "description": "Optional target timeline for the pilot." }, "risk_owner": { "type": "string", "description": "Optional named risk/security/legal owner. Contributes to the lead score." }, "high_volume_or_high_risk": { "type": "boolean", "description": "Optional explicit high-volume/high-risk flag; also inferred automatically when monthly_volume is 100000 or more." }, "annual_commit": { "type": "number", "description": "Optional intended annual commit in USD. Values of 60000 or more contribute to the lead score." } } }, "Lead": { "type": "object", "description": "The stored lead record echoed back by POST /api/lead. Optional request fields that were not provided are returned as null.", "required": [ "lead_id", "created_at", "source", "buyer_type", "contact_name", "contact_role", "company", "contact_or_agent_id", "timeline", "workflow", "target_offer_id", "success_metric", "monthly_volume", "samples_available", "risk_owner", "annual_commit", "score", "band", "reasons", "external_action_authorized", "contact_consent", "idempotency_key", "next_step" ], "properties": { "lead_id": { "type": "string", "description": "Server-generated lead identifier (prefix `lead_`).", "examples": [ "lead_7d1e3f5a9b2c" ] }, "created_at": { "type": "string", "format": "date-time", "description": "UTC creation timestamp (ISO 8601)." }, "source": { "type": "string", "description": "Origin label; local_revenue_system when not provided." }, "buyer_type": { "type": "string", "enum": [ "human_buyer", "ai_procurement_agent", "partner_agent", "ai_solution_evaluator", "ai_developer_agent", "ai_marketplace_agent" ] }, "contact_name": { "type": [ "string", "null" ] }, "contact_role": { "type": [ "string", "null" ] }, "company": { "type": "string" }, "contact_or_agent_id": { "type": "string" }, "timeline": { "type": [ "string", "null" ] }, "workflow": { "type": "string" }, "target_offer_id": { "type": "string" }, "success_metric": { "type": "string" }, "monthly_volume": { "type": [ "number", "null" ] }, "samples_available": { "type": "boolean", "description": "Coerced to a boolean (false when omitted)." }, "risk_owner": { "type": [ "string", "null" ] }, "annual_commit": { "type": [ "number", "null" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Deterministic qualification score from published scoring rules: workflow named (20), representative samples available (25), success metric named (20), risk owner identified (10), high volume or high risk (15), annual commit potential >= $60,000 (10)." }, "band": { "type": "string", "enum": [ "A", "B", "C", "D" ], "description": "Score band: A (>= 80), B (>= 60), C (>= 40), D (below 40)." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Matched scoring-rule labels followed by the recommended internal action for the band." }, "external_action_authorized": { "type": "boolean", "const": false, "description": "Always false: lead submission never authorizes outreach, contract, or spend." }, "contact_consent": { "type": "boolean", "const": true, "description": "Always true on stored leads (submissions without explicit consent are rejected)." }, "idempotency_key": { "type": [ "string", "null" ], "description": "Echo of the Idempotency-Key request header, or null when none was sent." }, "next_step": { "type": "string", "const": "human review required", "description": "Always \"human review required\"." } } }, "LeadResponse": { "type": "object", "description": "Successful response of POST /api/lead.", "required": [ "ok", "lead" ], "properties": { "ok": { "type": "boolean", "const": true }, "lead": { "$ref": "#/components/schemas/Lead" }, "idempotent_replay": { "type": "boolean", "const": true, "description": "Present (true) only when the Idempotency-Key matched a previously stored lead and that stored lead was returned instead of creating a new one. Absent on fresh leads." } } }, "AgentCatalog": { "type": "object", "description": "Agent-readable discovery catalog served at /api/agent/catalog and /.well-known/brainiall-agent-catalog.json.", "required": [ "name", "version", "vendor", "description", "base_url", "endpoints", "supported_buyer_types", "allowed_agent_actions", "disallowed_agent_actions", "privacy_notice", "human_approval_required", "external_actions_authorized", "offers" ], "properties": { "name": { "type": "string" }, "version": { "type": "string", "description": "Catalog content version (date-stamped)." }, "vendor": { "type": "string", "const": "Brainiall" }, "description": { "type": "string" }, "base_url": { "type": "string", "format": "uri", "description": "Base URL all endpoint paths are relative to." }, "endpoints": { "type": "object", "description": "Relative paths of every public acquisition endpoint.", "required": [ "offers", "quote", "lead", "agent_catalog", "openapi", "lead_schema", "quote_schema" ], "properties": { "offers": { "type": "string" }, "quote": { "type": "string" }, "lead": { "type": "string" }, "agent_catalog": { "type": "string" }, "openapi": { "type": "string" }, "lead_schema": { "type": "string" }, "quote_schema": { "type": "string" }, "legal_terms": { "type": "string", "examples": [ "/legal/pilot-terms.json" ] } } }, "supported_buyer_types": { "type": "array", "items": { "type": "string" }, "description": "Buyer types this API is designed for (human buyers plus AI agent classes)." }, "allowed_agent_actions": { "type": "array", "items": { "type": "string" }, "description": "The only actions an AI agent is authorized to take: read_catalog, request_quote, submit_qualified_interest." }, "disallowed_agent_actions": { "type": "array", "items": { "type": "string" }, "description": "Hard constraints for AI agents: bind_contract, authorize_spend, authorize_external_outreach, submit_sensitive_data, bypass_human_approval." }, "privacy_notice": { "type": "string" }, "human_approval_required": { "type": "boolean", "const": true }, "external_actions_authorized": { "type": "boolean", "const": false }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } }, "JsonSchemaDocument": { "type": "object", "description": "A JSON Schema (draft 2020-12) document as served from /schemas/*. Validate request bodies against it before posting.", "required": [ "$schema", "$id", "title", "type", "required", "properties" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "$id": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "type": { "type": "string" }, "additionalProperties": { "type": "boolean" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object" } } }, "ErrorMissingRequiredFields": { "type": "object", "description": "One or more required fields are missing, empty after trimming, or (for contact_consent) not exactly true.", "required": [ "ok", "error", "fields" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "missing_required_fields" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Names of the missing or invalid required fields." } } }, "ErrorFieldTooLong": { "type": "object", "description": "One or more string values exceed the per-field character limit. Checked recursively through nested objects and arrays; at most 20 offending field paths are reported.", "required": [ "ok", "error", "fields", "max_chars" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "field_too_long" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Dot/bracket paths of the offending string fields (max 20 entries)." }, "max_chars": { "type": "integer", "description": "Per-field character limit.", "examples": [ 2000 ] } } }, "ErrorSensitiveValueRejected": { "type": "object", "description": "A string value contained secret-like content (API keys, passwords, bearer tokens, or similar markers). The request is rejected and the event is logged for abuse monitoring. Never submit credentials or confidential data through public acquisition endpoints.", "required": [ "ok", "error", "fields", "message" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "sensitive_value_rejected" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Dot/bracket paths of the offending fields (max 20 entries)." }, "message": { "type": "string", "examples": [ "Do not submit credentials, secrets, tokens or confidential data through public acquisition endpoints." ] } } }, "ErrorInvalidJson": { "type": "object", "description": "The request body is not valid JSON.", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "invalid_json" } } }, "ErrorOfferNotFound": { "type": "object", "description": "The offer_id does not match any published offer. List valid ids via GET /api/offers.", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "offer_not_found" } } }, "ErrorPayloadTooLarge": { "type": "object", "description": "The request body exceeds the maximum allowed size.", "required": [ "ok", "error", "max_bytes" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "payload_too_large" }, "max_bytes": { "type": "integer", "description": "Maximum request body size in bytes.", "examples": [ 32768 ] } } }, "ErrorRateLimited": { "type": "object", "description": "Per-IP, per-endpoint sliding-window rate limit exceeded (window: 60 seconds; budgets: 240/min for GET endpoints, 30/min for POST endpoints). retry_after_seconds is the window length in seconds \u2014 waiting that long always restores budget. No rate-limit response headers are returned; this body is the only rate-limit signal.", "required": [ "ok", "error", "retry_after_seconds" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "rate_limited" }, "retry_after_seconds": { "type": "integer", "description": "Sliding-window length in seconds. Retry after at most this long.", "examples": [ 60 ] } } } } } }