{"openapi":"3.1.0","info":{"title":"DataGen Agentic API","description":"Synthetic data generation for **humans** (API keys) and **AI agents** (x402 pay-per-call).\n\n### Authentication modes\n- **X-API-Key** — Free key: `GET /api/v1/auth/free-key`. Tier limits apply.\n- **No API key** — On x402 **protected** POST routes, the service returns **402** with payment instructions, then accepts **`X-PAYMENT`** on retry after facilitator verification.\n\n### x402 (this deployment)\n- **Network id (x402):** `base-sepolia`\n- **USDC (asset in 402 accepts):** `0x036CbD53842c5426634e7929541eC2318f3dCF7e`\n- **Facilitator:** `https://x402.org` → `POST /verify`, `POST /settle`\n- **Pay-to configured:** True (`0x9370…8b18`)\n- **Micro-USDC brackets:** `{'generate_small': 2000, 'generate_medium': 5000, 'generate_large': 15000, 'validate': 0, 'capabilities': 0}`\n- **Protected POST paths (no key → 402 challenge):** `/api/v1/generate`, `/api/v1/generate-ai`, `/api/v1/generate-ai/stream`\n\n### Agentic + escrow canary\n- **DATAGEN_ENV:** `development`\n- **AGENTIC_LINEAGE_ENABLED (build-time):** `False` (stage `staging`)\n- **AGENTIC_ESCROW_ENABLED (build-time):** `False`\n- **Escrow canary path:** `/api/v1/canary/generate`\n- When escrow middleware is on and the request is **keyless** on that path, **402** returns an **on-chain invoice** JSON (not the x402 `accepts[]` shape). Chain **id 84532** (`base-sepolia`), USDC `0x036CbD53842c5426634e7929541eC2318f3dCF7e`.\n- **Escrow contract configured:** True (`0x9314…79e8`) · **Payee configured:** False (`(unset)`)\n\n### Agent workflow\n1. `GET /api/v1/capabilities` — tier, field types, **payment_environment** (same facts as this document).\n2. `GET /api/v1/field-types` — full catalog.\n3. `POST /api/v1/validate` — dry-run schema.\n4. `POST /api/v1/generate` / `generate-ai` / `generate-ai/stream` — generation (see 402 schemas on each operation).\n\n### Structured errors\nSend **`Accept: application/vnd.agentic+json`** on failures to receive agent-oriented error objects where supported.","version":"1.1.0"},"paths":{"/api/v1/capabilities":{"get":{"tags":["Discovery"],"summary":"Capabilities","operationId":"capabilities_api_v1_capabilities_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/field-types":{"get":{"tags":["Discovery"],"summary":"Field Types Catalog","description":"Full canonical field type list for integrators and LLM tool docs (not tier-filtered).","operationId":"field_types_catalog_api_v1_field_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/infer-schema":{"post":{"tags":["Generation"],"summary":"Infer Schema Endpoint","description":"Infer explicit schema contract without generating rows.","operationId":"infer_schema_endpoint_api_v1_infer_schema_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiInferSchemaRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiInferSchemaResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/generate-ai":{"post":{"tags":["Generation"],"summary":"Generate Ai","description":"AI mode: infer types from field names, then generate values (Ollama) with tier record caps.\nFree tier: max 100 rows per call; Pro/Enterprise: higher limits from config.\nSupports Idempotency-Key (or body fingerprint) for JSON responses when Redis is available.","operationId":"generate_ai_api_v1_generate_ai_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGenerateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required. **Shape A:** x402 facilitator `accepts[]` (no X-API-Key on `/api/v1/generate`, `/generate-ai`, `/generate-ai/stream`). **Shape B:** escrow invoice JSON on keyless POST to the configured canary path when `AGENTIC_ESCROW_ENABLED=1` (see `EscrowInvoice402Body`; includes `X-Payment-Required: true`).","headers":{"X-Payment-Required":{"description":"Set to `true` on escrow-invoice 402 responses.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402Body"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/generate-ai/stream":{"post":{"tags":["Generation"],"summary":"Generate Ai Stream","description":"SSE progress + final JSON payload (same limits as POST /generate-ai).","operationId":"generate_ai_stream_api_v1_generate_ai_stream_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGenerateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required. **Shape A:** x402 facilitator `accepts[]` (no X-API-Key on `/api/v1/generate`, `/generate-ai`, `/generate-ai/stream`). **Shape B:** escrow invoice JSON on keyless POST to the configured canary path when `AGENTIC_ESCROW_ENABLED=1` (see `EscrowInvoice402Body`; includes `X-Payment-Required: true`).","headers":{"X-Payment-Required":{"description":"Set to `true` on escrow-invoice 402 responses.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402Body"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/generate":{"post":{"tags":["Generation"],"summary":"Generate","operationId":"generate_api_v1_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required. **Shape A:** x402 facilitator `accepts[]` (no X-API-Key on `/api/v1/generate`, `/generate-ai`, `/generate-ai/stream`). **Shape B:** escrow invoice JSON on keyless POST to the configured canary path when `AGENTIC_ESCROW_ENABLED=1` (see `EscrowInvoice402Body`; includes `X-Payment-Required: true`).","headers":{"X-Payment-Required":{"description":"Set to `true` on escrow-invoice 402 responses.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402Body"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/canary/generate":{"post":{"tags":["Generation"],"summary":"Canary Generate","description":"Canary route: same body contract as `POST /api/v1/generate`.\n\nWhen `AGENTIC_ESCROW_ENABLED=1`, a **keyless** POST receives **402** with an on-chain **invoice** JSON\n(see OpenAPI `EscrowInvoice402Body`). With an API key or `X-PAYMENT`, behavior matches `/generate`.","operationId":"canary_generate_api_v1_canary_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required. **Shape A:** x402 facilitator `accepts[]` (no X-API-Key on `/api/v1/generate`, `/generate-ai`, `/generate-ai/stream`). **Shape B:** escrow invoice JSON on keyless POST to the configured canary path when `AGENTIC_ESCROW_ENABLED=1` (see `EscrowInvoice402Body`; includes `X-Payment-Required: true`).","headers":{"X-Payment-Required":{"description":"Set to `true` on escrow-invoice 402 responses.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402Body"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/validate":{"post":{"tags":["Generation"],"summary":"Validate Endpoint","operationId":"validate_endpoint_api_v1_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/health":{"get":{"tags":["Discovery"],"summary":"Health","operationId":"health_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Api V1 Health Get"}}}}}}},"/api/v1/auth/free-key":{"get":{"tags":["Discovery"],"summary":"Free Key","description":"Issue a low-privilege free-tier key. No user login — in production, per-IP rate limit uses Redis.","operationId":"free_key_api_v1_auth_free_key_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/pricing":{"get":{"tags":["Discovery"],"summary":"Pricing","operationId":"pricing_api_v1_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Pricing Api V1 Pricing Get"}}}}}}},"/api/v1/usage":{"get":{"tags":["Discovery"],"summary":"Usage","operationId":"usage_api_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"tags":["Discovery"],"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Root  Get"}}}}}}}},"components":{"schemas":{"AiGenerateRequest":{"properties":{"field_names":{"items":{"type":"string"},"type":"array","maxItems":80,"minItems":1,"title":"Field Names","description":"Output column names (snake_case or camelCase). Types are inferred; values are AI-generated."},"count":{"type":"integer","maximum":100000.0,"minimum":1.0,"title":"Count","description":"Rows to generate. Free tier: max 100 for AI mode. Pro/Enterprise: higher limits.","default":10},"locale":{"type":"string","title":"Locale","description":"Default locale hint for the model (en_US, en_AE, en_GB, ar_AE).","default":"en_US"},"output_format":{"type":"string","enum":["json","csv","jsonl"],"title":"Output Format","description":"Response serialization for records.","default":"json"},"domain_hint":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Domain Hint","description":"Optional short context (e.g. 'UAE ice cream shops') to steer type inference."},"require_validate":{"type":"boolean","title":"Require Validate","description":"If true, inferred schema must pass /validate-style checks before generation.","default":false},"strict_contract":{"type":"boolean","title":"Strict Contract","description":"If true, reject inference when any field falls back to heuristic inference.","default":false},"expected_contract_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expected Contract Hash","description":"Optional SHA-256 of expected inferred contract; request fails on mismatch."}},"type":"object","required":["field_names"],"title":"AiGenerateRequest","description":"AI mode: provide column names only; the service infers canonical types and generates values via LLM."},"AiInferSchemaRequest":{"properties":{"field_names":{"items":{"type":"string"},"type":"array","maxItems":80,"minItems":1,"title":"Field Names","description":"Output column names to infer into explicit schema fields."},"locale":{"type":"string","title":"Locale","description":"Locale hint for inference.","default":"en_US"},"domain_hint":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Domain Hint","description":"Optional domain context to steer type inference."}},"type":"object","required":["field_names"],"title":"AiInferSchemaRequest","description":"Infer explicit schema contract from field names (no row generation)."},"AiInferSchemaResponse":{"properties":{"proposed_schema":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Proposed Schema","description":"Inferred explicit schema fields (name/type/description)."},"contract_hash":{"type":"string","title":"Contract Hash","description":"SHA-256 hash of canonicalized proposed_schema for contract lock/replay checks."},"contract_id":{"type":"string","title":"Contract Id","description":"Ephemeral contract artifact id for traceability in logs."},"locale":{"type":"string","title":"Locale","description":"Locale used during schema inference."}},"type":"object","required":["proposed_schema","contract_hash","contract_id","locale"],"title":"AiInferSchemaResponse","description":"Response for inferred contract artifact."},"FieldDefinition":{"properties":{"name":{"type":"string","title":"Name","description":"Output column name. Use snake_case. e.g. 'customer_email'"},"type":{"type":"string","title":"Type","description":"Field type key from GET /capabilities. e.g. 'email', 'phone', 'iban', 'uuid'"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locale","description":"Locale override for this field. Inherits request locale if absent. e.g. 'en_AE'"},"constraints":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Constraints","description":"Type-specific constraints. e.g. {'country_code': '+971'} for UAE phone. See /capabilities for per-type constraints."},"blankPercentage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Blankpercentage","description":"Optional 0–100 chance the value is null (matches n8n simple-generator field option)."}},"type":"object","required":["name","type"],"title":"FieldDefinition","description":"A single field in the data generation schema."},"GenerationRequest":{"properties":{"schema_fields":{"items":{"$ref":"#/components/schemas/FieldDefinition"},"type":"array","title":"Schema Fields","description":"List of fields to generate. Minimum 1, maximum 50. Call GET /capabilities to see all available field types. JSON key `schema` is accepted (n8n / frontend)."},"count":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Count","description":"Number of records. Free tier max: 100. Pro max: 5000. x402 max: 10000. JSON key `recordCount` accepted.","default":10},"locale":{"type":"string","title":"Locale","description":"Default locale for all fields. Supported: en_US, en_AE, en_GB, ar_AE. Affects phone format, address style, currency.","default":"en_US"},"output_format":{"type":"string","enum":["json","csv","jsonl","excel","xml"],"title":"Output Format","description":"Response shape. Matches frontend exportFormat: csv, json, jsonl, excel, xml (excel/xml return JSON records).","default":"json"},"sampleData":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Sampledata","description":"Optional sample rows from Schema Builder / AI mode (n8n contract); ignored by this API for now."},"fieldPatterns":{"anyOf":[{"additionalProperties":{"items":{},"type":"array"},"type":"object"},{"type":"null"}],"title":"Fieldpatterns","description":"Optional pattern map from AI mode (n8n contract); ignored by this API for now."},"agent_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Address","description":"Optional payer wallet address for non-custodial escrow settlement."},"nonce":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Nonce","description":"Optional escrow nonce (required for concurrent escrowed requests)."},"payment_tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Tx Hash","description":"Optional Base transaction hash proving escrow lock (0x...)."}},"type":"object","required":["schema_fields"],"title":"GenerationRequest","description":"Request body for POST /api/v1/generate.\n\nDual-compatible: accepts legacy n8n keys (`schema`, `recordCount`, `exportFormat`)\nand new API keys (`schema_fields`, `count`, `output_format`)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"X402AcceptItem":{"type":"object","description":"Single entry inside payment_requirements.accepts[] from X402Middleware.","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base-sepolia"},"maxAmountRequired":{"type":"string","description":"Micro-USDC amount as decimal string."},"resource":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"asset":{"type":"string","description":"USDC contract on the named network."},"nonce":{"type":"string"},"expiry":{"type":"integer"},"extra":{"type":"object"}}},"X402PaymentRequiredBody":{"type":"object","required":["accepts"],"properties":{"accepts":{"type":"array","items":{"$ref":"#/components/schemas/X402AcceptItem"}}},"example":{"accepts":[{"scheme":"exact","network":"base-sepolia","maxAmountRequired":"2000","resource":"https://example.com/api/v1/generate","description":"DataGen synthetic data generation — 10 records","mimeType":"application/json","payTo":"0x93701c6ADD1a409a9ADC8643e999521c41d28b18","maxTimeoutSeconds":60,"asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","nonce":"abc123","expiry":1710000000,"extra":{"name":"DataGen Synthetic Data API","version":"1"}}]}},"EscrowInvoice402Body":{"type":"object","required":["error","message","invoice"],"properties":{"error":{"type":"string","example":"payment_required"},"message":{"type":"string"},"invoice":{"type":"object","properties":{"invoice_id":{"type":"string"},"chain_id":{"type":"integer"},"network":{"type":"string"},"asset":{"type":"object"},"amount_micro_usdc":{"type":"integer"},"escrow_contract":{"type":"string"},"payee":{"type":"string"},"nonce":{"type":"integer"},"record_count":{"type":"integer"},"resource":{"type":"string"},"issued_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}}}},"PaymentRequired402Body":{"oneOf":[{"$ref":"#/components/schemas/X402PaymentRequiredBody"},{"$ref":"#/components/schemas/EscrowInvoice402Body"}],"description":"HTTP 402 body: either x402 facilitator challenge (`accepts`) on generate routes without X-API-Key, or escrow invoice JSON on the canary path when AGENTIC_ESCROW_ENABLED=1."}},"securitySchemes":{"XApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional. Issue a free key: GET /api/v1/auth/free-key"},"XPayment":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"x402 facilitator payment payload after settling the 402 `accepts[]` challenge. Send on retry to the same URL and JSON body."}}},"security":[{},{"XApiKey":[]}]}