{ "openapi": "3.1.0", "info": { "title": "Kynth Core", "version": "1.0.0", "description": "**The AI back-end for your product.**\n\nParse a document, extract fields, redact PII, analyze a contract, fight a chargeback, enrich a company — 39 production AI endpoints, the same capabilities behind the software we run in production. **One key, one wallet, one bill.** Pay only for the calls you make; failed calls are never charged.\n\nSign in, top up your wallet, and call any endpoint. Every panel is live: drop in your key and run it from the browser.\n\nSee **Quickstart** to make your first call, **SDKs & MCP** for the TypeScript / Python clients and the MCP server, or **Pricing & credits** for the full rate card.", "contact": { "name": "Kynth", "url": "https://kynth.studio" } }, "servers": [ { "url": "https://api.kynth.studio" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Quickstart", "description": "Sign up at [the dashboard](https://api.kynth.studio/dashboard) — every account gets **500 free credits every month, no card** — mint a key, and call any endpoint.\n\n```bash\ncurl https://api.kynth.studio/v1/parse \\\n -H \"Authorization: Bearer ksk_live_…\" \\\n -d '{ \"fileUrl\": \"https://…/invoice.pdf\" }'\n```\n\nEvery successful response returns its result plus `usage: { credits, balanceRemaining }`. A failed call is never charged." }, { "name": "Authentication", "description": "Every request authenticates with a bearer API key (`ksk_live_…`). Mint and revoke keys in the [dashboard](https://api.kynth.studio/dashboard); the secret is shown once.\n\n```\nAuthorization: Bearer ksk_live_…\n```\n\nKeep keys server-side, store them in an env var (e.g. `KYNTH_API_KEY`), and revoke any time." }, { "name": "SDKs & MCP", "description": "Call Kynth Core from TypeScript, Python, or any MCP client.\n\n```bash\nnpm i @kynth/api # TypeScript / JavaScript\npip install kynth # Python\nnpx @kynth/api-mcp # MCP server — native tools for Claude, Cursor, any MCP client\n```\n\n```ts\nimport { KynthCore } from \"@kynth/api\";\nconst kynth = new KynthCore({ apiKey: process.env.KYNTH_API_KEY! });\nconst doc = await kynth.parse({ fileUrl });\nconsole.log(doc.totalAmount, doc.usage.balanceRemaining);\n```" }, { "name": "Pricing & credits", "description": "Credits, not seats — **1 credit = $0.01**. Every endpoint burns at its own rate, you're only charged on success, and credits never expire.\n\n**Free tier** — every account starts each month with at least **500 free credits** (no card required). Your wallet is topped back up to the floor on the 1st.\n\n**Monthly plans** — the best rate per credit; a fresh bundle lands every billing period.\n\n- **Developer — $29/mo** — 3,500 credits every month — ~20% more per dollar than the Starter pack.\n- **Team — $99/mo** — 13,000 credits every month — more per dollar than every pack, even Scale.\n\n**Credit packs** — one-time top-ups for overflow.\n\n- **Starter — $20** — 2,000 credits\n- **Growth — $100 (+5% bonus)** — 10,500 credits\n- **Scale — $500 (+10% bonus)** — 55,000 credits\n\n| Endpoint | Capability | Cost |\n| --- | --- | --- |\n| `POST /v1/parse` | Document parse | **$0.10/document** (10 cr) |\n| `POST /v1/extract` | Field extraction | **$0.04/call** (4 cr) |\n| `POST /v1/classify` | Classification | **$0.02/call** (2 cr) |\n| `POST /v1/summarize` | Summarize | **$0.03/call** (3 cr) |\n| `POST /v1/redact` | PII redaction | **$0.03/call** (3 cr) |\n| `POST /v1/sentiment` | Sentiment | **$0.02/call** (2 cr) |\n| `POST /v1/contract` | Contract analysis | **$0.12/contract** (12 cr) |\n| `POST /v1/chargeback` | Chargeback representment | **$0.15/dispute** (15 cr) |\n| `POST /v1/enrich` | Company enrichment | **$0.05/lookup** (5 cr) |\n| `POST /v1/invoice` | Invoice extraction | **$0.08/invoice** (8 cr) |\n| `POST /v1/receipt` | Receipt extraction | **$0.06/receipt** (6 cr) |\n| `POST /v1/statement` | Statement parsing | **$0.12/statement** (12 cr) |\n| `POST /v1/resume` | Resume parsing | **$0.08/resume** (8 cr) |\n| `POST /v1/tables` | Table extraction | **$0.08/document** (8 cr) |\n| `POST /v1/split` | Document splitting | **$0.10/bundle** (10 cr) |\n| `POST /v1/compare` | Document comparison | **$0.15/comparison** (15 cr) |\n| `POST /v1/structure` | Structure to your schema | **$0.06/call** (6 cr) |\n| `POST /v1/normalize` | Record normalization | **$0.05/batch** (5 cr) |\n| `POST /v1/match` | Entity matching | **$0.08/run** (8 cr) |\n| `POST /v1/categorize` | Batch categorization | **$0.03/batch** (3 cr) |\n| `POST /v1/dunning` | Collections sequence | **$0.08/sequence** (8 cr) |\n| `POST /v1/po-match` | 3-way match | **$0.10/match** (10 cr) |\n| `POST /v1/quote` | Quote builder | **$0.08/quote** (8 cr) |\n| `POST /v1/fraud-flag` | Fraud triage | **$0.06/check** (6 cr) |\n| `POST /v1/reply` | Reply drafting | **$0.05/reply** (5 cr) |\n| `POST /v1/triage` | Ticket triage | **$0.03/ticket** (3 cr) |\n| `POST /v1/minutes` | Meeting minutes | **$0.06/transcript** (6 cr) |\n| `POST /v1/outreach` | Outreach sequence | **$0.06/sequence** (6 cr) |\n| `POST /v1/review-reply` | Review response | **$0.03/review** (3 cr) |\n| `POST /v1/moderate` | Content moderation | **$0.02/item** (2 cr) |\n| `POST /v1/rewrite` | Brand-voice rewrite | **$0.03/call** (3 cr) |\n| `POST /v1/product-copy` | Product copy | **$0.05/product** (5 cr) |\n| `POST /v1/describe` | Image description | **$0.03/image** (3 cr) |\n| `POST /v1/research` | Research brief | **$0.50/brief** (50 cr) |\n| `POST /v1/screen` | Lead screening | **$0.10/lead** (10 cr) |\n| `POST /v1/transcribe` | Transcription | **$0.10/recording** (10 cr) |\n| `POST /v1/memory` | Agent memory | **$0.02/operation** (2 cr) |\n| `POST /v1/image` | Image generation | **$0.10/image** (10 cr) |\n| `POST /v1/speak` | Text to speech | **$0.05/clip** (5 cr) |" }, { "name": "Document parse", "description": "Any invoice, receipt, EOB, ERA, or COI — PDF or image — into structured, validated JSON." }, { "name": "Field extraction", "description": "Pull a field set you define out of any block of text. You name the fields; you get typed values with confidence." }, { "name": "Classification", "description": "Route or tag text against your own taxonomy — a label, a confidence, and a one-line rationale." }, { "name": "Summarize", "description": "A meeting transcript, thread, or report → a tight summary, key points, and extracted action items." }, { "name": "PII redaction", "description": "Detect and strip names, emails, phones, SSNs, cards, and PHI from text before you store or log it." }, { "name": "Sentiment", "description": "Turn a review or support message into a sentiment score, per-aspect breakdown, and the themes driving it." }, { "name": "Contract analysis", "description": "A contract → parties, effective date, term, renewal, governing law, obligations, and flagged risk clauses." }, { "name": "Chargeback representment", "description": "Dispute details → a representment narrative, an evidence checklist, the right reason code, and a win-likelihood." }, { "name": "Company enrichment", "description": "A domain or work email → a structured company profile: name, description, industry, HQ, size, and links." }, { "name": "Invoice extraction", "description": "An invoice — PDF, photo, or text — into vendor, dates, PO refs, tax, totals, and clean line items." }, { "name": "Receipt extraction", "description": "A receipt into merchant, items, totals, payment method, and an expense category — built for expense flows." }, { "name": "Statement parsing", "description": "A bank or card statement into the account, the period, balances, and every transaction as a normalized row." }, { "name": "Resume parsing", "description": "A resume or CV into a structured candidate profile: contact, skills, experience, education, and links." }, { "name": "Table extraction", "description": "Every table in a document — even scanned — as clean headers and rows, ready for your spreadsheet or DB." }, { "name": "Document splitting", "description": "A multi-document scan bundle classified and split: what each document is, where it starts and ends, and a summary." }, { "name": "Document comparison", "description": "Two versions of a contract or document → every material change, what it means, and the risk it carries." }, { "name": "Structure to your schema", "description": "Any messy input — text, HTML, an email — plus YOUR JSON schema → output shaped to it, validated against your required fields and property types, with an automatic corrective retry and a `valid` flag." }, { "name": "Record normalization", "description": "A batch of messy records → clean canonical rows, with a change log of every fix (casing, formats, dedup-ready values)." }, { "name": "Entity matching", "description": "Two record sets → which rows are the same real-world thing, with confidence and reasoning. Fuzzy names, typos, aliases handled." }, { "name": "Batch categorization", "description": "Up to a hundred items against your taxonomy in one call — products, transactions, tickets — each with a confidence." }, { "name": "Collections sequence", "description": "An overdue invoice → a ready-to-send collection sequence, escalating at the right pace and tone for how late it is." }, { "name": "3-way match", "description": "Invoice vs purchase order vs receipt → matched, partial, or mismatched, with every discrepancy flagged and sized." }, { "name": "Quote builder", "description": "A job description plus your rates → an itemized, professional quote with assumptions and scope notes spelled out." }, { "name": "Fraud triage", "description": "An order or transaction in context → a risk score, the signals driving it, and the checks worth running before you ship." }, { "name": "Reply drafting", "description": "A customer thread plus your context → a ready-to-send reply in the right tone, with an internal note for the agent." }, { "name": "Ticket triage", "description": "A support ticket → priority, category, the team it belongs to, sentiment, SLA risk, and a suggested first response." }, { "name": "Meeting minutes", "description": "A meeting transcript → clean minutes: summary, decisions made, action items with owners, and open questions." }, { "name": "Outreach sequence", "description": "An enriched lead plus what you sell → a personalized outreach sequence that references what actually makes them a fit." }, { "name": "Review response", "description": "A customer review → a brand-safe public response, the issues to log, and whether it needs human escalation." }, { "name": "Content moderation", "description": "Text or an image against YOUR policy → allow, review, or block, with the categories and excerpts that drove the call." }, { "name": "Brand-voice rewrite", "description": "Any copy → your brand voice. Describe the voice or paste a sample; get the rewrite and what changed." }, { "name": "Product copy", "description": "Specs and an audience → listing-ready titles, bullets, a description, and SEO keywords — per channel." }, { "name": "Image description", "description": "An image → accessible alt text, a caption, tags, and any text found inside it. Accessibility and catalogs in one call." }, { "name": "Research brief", "description": "A company or topic → a multi-source, citation-backed brief: what it is, what changed lately, and what matters. Real web work." }, { "name": "Lead screening", "description": "A lead plus your ICP criteria → a web-grounded qualification verdict with the evidence for and against." }, { "name": "Transcription", "description": "An audio recording → accurate text with speakers and paragraph timestamps. Meetings, calls, voice notes." }, { "name": "Agent memory", "description": "Store, search, and forget memories for your agents — semantic recall on your own namespace, no vector DB to run." }, { "name": "Image generation", "description": "A prompt → a production-ready image. Marketing visuals, product scenes, and consistent brand imagery." }, { "name": "Text to speech", "description": "Text → natural speech audio, ready to embed. Voice notes, IVR lines, narration." } ], "x-tagGroups": [ { "name": "Guides", "tags": [ "Quickstart", "Authentication", "SDKs & MCP", "Pricing & credits" ] }, { "name": "API Reference", "tags": [ "Document parse", "Field extraction", "Classification", "Summarize", "PII redaction", "Sentiment", "Contract analysis", "Chargeback representment", "Company enrichment", "Invoice extraction", "Receipt extraction", "Statement parsing", "Resume parsing", "Table extraction", "Document splitting", "Document comparison", "Structure to your schema", "Record normalization", "Entity matching", "Batch categorization", "Collections sequence", "3-way match", "Quote builder", "Fraud triage", "Reply drafting", "Ticket triage", "Meeting minutes", "Outreach sequence", "Review response", "Content moderation", "Brand-voice rewrite", "Product copy", "Image description", "Research brief", "Lead screening", "Transcription", "Agent memory", "Image generation", "Text to speech" ] } ], "paths": { "/v1/parse": { "post": { "operationId": "parse", "summary": "Document parse", "description": "Any invoice, receipt, EOB, ERA, or COI — PDF or image — into structured, validated JSON.\n\nCost: 10 credits ($0.10) — charged only on success.", "tags": [ "Document parse" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Provide exactly one of: file, fileUrl, or text.", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } ], "x-doc-input": true, "properties": { "docType": { "type": "string", "maxLength": 64, "description": "Optional hint, e.g. \"invoice\"." } } }, "example": { "fileUrl": "https://…/invoice.pdf" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "docType", "fields" ], "properties": { "docType": { "type": "string", "description": "Classified document type, e.g. \"invoice\"." }, "party": { "type": "string", "description": "Primary party — vendor / payer / carrier." }, "documentNumber": { "type": "string" }, "date": { "type": "string", "description": "Primary date, YYYY-MM-DD." }, "totalAmount": { "type": "number" }, "lineItems": { "type": "array", "items": { "type": "object", "required": [ "description", "amount" ], "properties": { "description": { "type": "string" }, "amount": { "type": "number" } } } }, "fields": { "type": "array", "items": { "type": "object", "required": [ "label", "value", "confidence" ], "properties": { "label": { "type": "string" }, "value": { "type": [ "string", "number", "null" ] }, "confidence": { "type": "number", "description": "0–1." } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "docType": "invoice", "party": "Acme Supplies Inc.", "documentNumber": "INV-10428", "date": "2026-06-30", "totalAmount": 4820.5, "lineItems": [ { "description": "…", "amount": 1200 } ], "fields": [ { "label": "PO Number", "value": "PO-88", "confidence": 0.98 } ], "usage": { "credits": 10, "balanceRemaining": 490 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/extract": { "post": { "operationId": "extract", "summary": "Field extraction", "description": "Pull a field set you define out of any block of text. You name the fields; you get typed values with confidence.\n\nCost: 4 credits ($0.04) — charged only on success.", "tags": [ "Field extraction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text", "fields" ], "properties": { "text": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The field names to pull out." }, "instructions": { "type": "string", "description": "Optional extra guidance." } } }, "example": { "text": "Order 5561 ships Jul 8 to Denver, CO. Total $412.", "fields": [ "order number", "ship date", "destination", "total" ] } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "field", "value", "confidence" ], "properties": { "field": { "type": "string" }, "value": { "type": [ "string", "null" ] }, "confidence": { "type": "number", "description": "0–1." } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "results": [ { "field": "order number", "value": "5561", "confidence": 0.99 }, { "field": "ship date", "value": "2026-07-08", "confidence": 0.9 } ], "usage": { "credits": 4, "balanceRemaining": 486 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/classify": { "post": { "operationId": "classify", "summary": "Classification", "description": "Route or tag text against your own taxonomy — a label, a confidence, and a one-line rationale.\n\nCost: 2 credits ($0.02) — charged only on success.", "tags": [ "Classification" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text", "labels" ], "properties": { "text": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 50 }, "multi": { "type": "boolean", "description": "Allow multiple labels.", "default": false }, "instructions": { "type": "string" } } }, "example": { "text": "My card was charged twice for one order.", "labels": [ "billing", "shipping", "technical", "refund" ] } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "label", "confidence", "rationale" ], "properties": { "label": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "All labels when multi is set." }, "confidence": { "type": "number", "description": "0–1." }, "rationale": { "type": "string" } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "label": "billing", "confidence": 0.96, "rationale": "Duplicate charge is a billing dispute.", "usage": { "credits": 2, "balanceRemaining": 484 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/summarize": { "post": { "operationId": "summarize", "summary": "Summarize", "description": "A meeting transcript, thread, or report → a tight summary, key points, and extracted action items.\n\nCost: 3 credits ($0.03) — charged only on success.", "tags": [ "Summarize" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "length": { "type": "string", "enum": [ "brief", "standard", "detailed" ], "default": "standard" }, "actionItems": { "type": "boolean", "default": true } } }, "example": { "text": "", "length": "standard" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "summary", "keyPoints", "actionItems" ], "properties": { "summary": { "type": "string" }, "keyPoints": { "type": "array", "items": { "type": "string" } }, "actionItems": { "type": "array", "items": { "type": "object", "required": [ "task" ], "properties": { "task": { "type": "string" }, "owner": { "type": "string" } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "summary": "The team agreed to ship the billing fix Friday…", "keyPoints": [ "Billing bug root-caused", "Launch moved to Fri" ], "actionItems": [ { "task": "Deploy the fix", "owner": "Priya" } ], "usage": { "credits": 3, "balanceRemaining": 481 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/redact": { "post": { "operationId": "redact", "summary": "PII redaction", "description": "Detect and strip names, emails, phones, SSNs, cards, and PHI from text before you store or log it.\n\nCost: 3 credits ($0.03) — charged only on success.", "tags": [ "PII redaction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "types": { "type": "array", "items": { "type": "string" }, "description": "Entity types to redact; omit for all." }, "placeholder": { "type": "string", "default": "[REDACTED]" } } }, "example": { "text": "Call Jane Doe at 415-555-0199 or jane@acme.com." } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "redacted", "entities", "entityCount" ], "properties": { "redacted": { "type": "string" }, "entities": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } }, "entityCount": { "type": "integer" } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "redacted": "Call [REDACTED] at [REDACTED] or [REDACTED].", "entities": [ { "type": "name", "text": "Jane Doe" }, { "type": "phone", "text": "415-555-0199" }, { "type": "email", "text": "jane@acme.com" } ], "entityCount": 3, "usage": { "credits": 3, "balanceRemaining": 478 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sentiment": { "post": { "operationId": "sentiment", "summary": "Sentiment", "description": "Turn a review or support message into a sentiment score, per-aspect breakdown, and the themes driving it.\n\nCost: 2 credits ($0.02) — charged only on success.", "tags": [ "Sentiment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "aspects": { "type": "array", "items": { "type": "string" }, "description": "Optional aspects to break out." } } }, "example": { "text": "Love the product but support took days to reply.", "aspects": [ "product", "support" ] } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "sentiment", "score", "confidence", "aspects", "themes" ], "properties": { "sentiment": { "type": "string" }, "score": { "type": "number", "description": "-1..1." }, "confidence": { "type": "number", "description": "0–1." }, "aspects": { "type": "array", "items": { "type": "object", "required": [ "aspect", "sentiment", "score" ], "properties": { "aspect": { "type": "string" }, "sentiment": { "type": "string" }, "score": { "type": "number" } } } }, "themes": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "sentiment": "neutral", "score": 0.1, "confidence": 0.88, "aspects": [ { "aspect": "product", "sentiment": "positive", "score": 0.8 }, { "aspect": "support", "sentiment": "negative", "score": -0.6 } ], "themes": [ "slow support response" ], "usage": { "credits": 2, "balanceRemaining": 476 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contract": { "post": { "operationId": "contract", "summary": "Contract analysis", "description": "A contract → parties, effective date, term, renewal, governing law, obligations, and flagged risk clauses.\n\nCost: 12 credits ($0.12) — charged only on success.", "tags": [ "Contract analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Provide exactly one of: file, fileUrl, or text.", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } ], "x-doc-input": true, "properties": {} }, "example": { "fileUrl": "https://…/msa.pdf" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "contractType", "parties", "obligations", "riskFlags" ], "properties": { "contractType": { "type": "string" }, "parties": { "type": "array", "items": { "type": "object", "required": [ "name", "role" ], "properties": { "name": { "type": "string" }, "role": { "type": "string" } } } }, "effectiveDate": { "type": "string" }, "term": { "type": "string" }, "renewal": { "type": "object", "required": [ "autoRenews" ], "properties": { "autoRenews": { "type": "boolean" }, "noticePeriod": { "type": "string" } } }, "governingLaw": { "type": "string" }, "obligations": { "type": "array", "items": { "type": "string" } }, "riskFlags": { "type": "array", "items": { "type": "object", "required": [ "clause", "severity", "reason" ], "properties": { "clause": { "type": "string" }, "severity": { "type": "string", "description": "low | medium | high." }, "reason": { "type": "string" } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "contractType": "Master Services Agreement", "parties": [ { "name": "Acme Inc.", "role": "Client" }, { "name": "Vendor LLC", "role": "Provider" } ], "effectiveDate": "2026-01-01", "term": "12 months", "renewal": { "autoRenews": true, "noticePeriod": "30 days" }, "governingLaw": "Delaware", "obligations": [ "Provider delivers monthly reports" ], "riskFlags": [ { "clause": "Auto-renewal", "severity": "medium", "reason": "Renews unless cancelled 30d prior." } ], "usage": { "credits": 12, "balanceRemaining": 464 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/chargeback": { "post": { "operationId": "chargeback", "summary": "Chargeback representment", "description": "Dispute details → a representment narrative, an evidence checklist, the right reason code, and a win-likelihood.\n\nCost: 15 credits ($0.15) — charged only on success.", "tags": [ "Chargeback representment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason", "transaction" ], "properties": { "reason": { "type": "string", "description": "The cardholder's dispute reason." }, "transaction": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "example": "USD" }, "date": { "type": "string", "format": "date" }, "descriptor": { "type": "string" } } }, "evidence": { "type": "array", "items": { "type": "string" } }, "context": { "type": "string" }, "network": { "type": "string", "enum": [ "visa", "mastercard", "amex", "discover" ] } } }, "example": { "reason": "Cardholder claims product never arrived", "transaction": { "amount": 129, "currency": "USD", "date": "2026-06-12", "descriptor": "ACME STORE" }, "evidence": [ "Tracking shows delivered 2026-06-15", "Signed at door" ], "network": "visa" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "reasonCategory", "recommendedAction", "narrative", "evidenceChecklist", "winLikelihood", "rationale" ], "properties": { "reasonCategory": { "type": "string" }, "recommendedAction": { "type": "string", "description": "fight | accept." }, "narrative": { "type": "string" }, "evidenceChecklist": { "type": "array", "items": { "type": "object", "required": [ "item", "have" ], "properties": { "item": { "type": "string" }, "have": { "type": "boolean" } } } }, "winLikelihood": { "type": "number", "description": "0–1." }, "rationale": { "type": "string" } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "reasonCategory": "product_not_received", "recommendedAction": "fight", "narrative": "The cardholder disputes non-receipt; however carrier tracking…", "evidenceChecklist": [ { "item": "Carrier tracking with delivery confirmation", "have": true } ], "winLikelihood": 0.82, "rationale": "Delivery confirmation directly rebuts non-receipt.", "usage": { "credits": 15, "balanceRemaining": 449 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/enrich": { "post": { "operationId": "enrich", "summary": "Company enrichment", "description": "A domain or work email → a structured company profile: name, description, industry, HQ, size, and links.\n\nCost: 5 credits ($0.05) — charged only on success.", "tags": [ "Company enrichment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provide one of: domain or email.", "x-ts-input": "{ domain: string } | { email: string }", "properties": { "domain": { "type": "string", "example": "stripe.com" }, "email": { "type": "string", "format": "email", "example": "sam@stripe.com" } } }, "example": { "email": "sam@stripe.com" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "name", "domain", "grounded" ], "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "description": { "type": "string" }, "industry": { "type": "string" }, "headquarters": { "type": "string" }, "employeeRange": { "type": "string" }, "founded": { "type": "integer" }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "grounded": { "type": "boolean", "description": "True when web-grounded sources backed the profile." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "name": "Stripe", "domain": "stripe.com", "description": "Payments infrastructure for the internet.", "industry": "Financial technology", "headquarters": "South San Francisco, CA", "employeeRange": "5001-10000", "founded": 2010, "links": { "website": "https://stripe.com", "linkedin": "…", "twitter": "…" }, "grounded": true, "usage": { "credits": 5, "balanceRemaining": 444 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/invoice": { "post": { "operationId": "invoice", "summary": "Invoice extraction", "description": "An invoice — PDF, photo, or text — into vendor, dates, PO refs, tax, totals, and clean line items.\n\nCost: 8 credits ($0.08) — charged only on success.", "tags": [ "Invoice extraction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Provide exactly one of: file, fileUrl, or text.", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } ], "x-doc-input": true, "properties": {} }, "example": { "fileUrl": "https://…/invoice.pdf" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "vendor", "lineItems" ], "properties": { "vendor": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "taxId": { "type": [ "string", "null" ] } } }, "customer": { "type": [ "string", "null" ] }, "invoiceNumber": { "type": [ "string", "null" ] }, "poNumber": { "type": [ "string", "null" ] }, "issueDate": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "dueDate": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "currency": { "type": [ "string", "null" ], "description": "ISO code, e.g. USD." }, "subtotal": { "type": [ "number", "null" ] }, "tax": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "paymentTerms": { "type": [ "string", "null" ] }, "lineItems": { "type": "array", "items": { "type": "object", "required": [ "description", "amount" ], "properties": { "description": { "type": "string" }, "quantity": { "type": [ "number", "null" ] }, "unitPrice": { "type": [ "number", "null" ] }, "amount": { "type": "number" } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "vendor": { "name": "Acme Supplies Inc.", "address": "123 Warehouse Rd, Columbus OH", "taxId": null }, "customer": "Northwind Coffee LLC", "invoiceNumber": "INV-10428", "poNumber": "PO-88", "issueDate": "2026-06-30", "dueDate": "2026-07-30", "currency": "USD", "subtotal": 1200, "tax": 55.5, "total": 1255.5, "paymentTerms": "Net 30", "lineItems": [ { "description": "Widget A", "quantity": 12, "unitPrice": 100, "amount": 1200 } ], "usage": { "credits": 8, "balanceRemaining": 436 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/receipt": { "post": { "operationId": "receipt", "summary": "Receipt extraction", "description": "A receipt into merchant, items, totals, payment method, and an expense category — built for expense flows.\n\nCost: 6 credits ($0.06) — charged only on success.", "tags": [ "Receipt extraction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Provide exactly one of: file, fileUrl, or text.", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } ], "x-doc-input": true, "properties": {} }, "example": { "fileUrl": "https://…/receipt.jpg" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "merchant", "category", "items" ], "properties": { "merchant": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "time": { "type": [ "string", "null" ], "description": "HH:MM, 24h." }, "currency": { "type": [ "string", "null" ] }, "subtotal": { "type": [ "number", "null" ] }, "tax": { "type": [ "number", "null" ] }, "tip": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "paymentMethod": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "meals", "travel", "lodging", "transport", "office", "software", "utilities", "entertainment", "groceries", "health", "other" ], "description": "Expense category, ready to post." }, "items": { "type": "array", "items": { "type": "object", "required": [ "description", "amount" ], "properties": { "description": { "type": "string" }, "quantity": { "type": [ "number", "null" ] }, "amount": { "type": "number" } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "merchant": "Blue Bottle Coffee", "location": "315 Linden St, Oakland CA", "date": "2026-07-02", "time": "09:41", "currency": "USD", "subtotal": 10.25, "tax": 0.95, "tip": null, "total": 11.2, "paymentMethod": "visa ****4242", "category": "meals", "items": [ { "description": "Latte 12oz", "quantity": 1, "amount": 5.75 }, { "description": "Croissant", "quantity": 1, "amount": 4.5 } ], "usage": { "credits": 6, "balanceRemaining": 430 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/statement": { "post": { "operationId": "statement", "summary": "Statement parsing", "description": "A bank or card statement into the account, the period, balances, and every transaction as a normalized row.\n\nCost: 12 credits ($0.12) — charged only on success.", "tags": [ "Statement parsing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Provide exactly one of: file, fileUrl, or text.", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } ], "x-doc-input": true, "properties": {} }, "example": { "fileUrl": "https://…/statement.pdf" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "transactions", "transactionCount" ], "properties": { "institution": { "type": [ "string", "null" ] }, "accountHolder": { "type": [ "string", "null" ] }, "accountNumberMasked": { "type": [ "string", "null" ], "description": "As printed, e.g. ****1234." }, "periodStart": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "periodEnd": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "currency": { "type": [ "string", "null" ] }, "openingBalance": { "type": [ "number", "null" ] }, "closingBalance": { "type": [ "number", "null" ] }, "transactions": { "type": "array", "items": { "type": "object", "required": [ "description", "amount", "direction" ], "properties": { "date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "description": { "type": "string" }, "amount": { "type": "number", "description": "Positive; see direction." }, "direction": { "type": "string", "enum": [ "debit", "credit" ] }, "category": { "type": [ "string", "null" ] }, "balance": { "type": [ "number", "null" ], "description": "Running balance when printed." } } } }, "transactionCount": { "type": "integer" } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "institution": "Chase", "accountHolder": "Northwind Coffee LLC", "accountNumberMasked": "****4821", "periodStart": "2026-06-01", "periodEnd": "2026-06-30", "currency": "USD", "openingBalance": 18240.11, "closingBalance": 21694.6, "transactions": [ { "date": "2026-06-03", "description": "STRIPE PAYOUT", "amount": 4820.5, "direction": "credit", "category": "revenue", "balance": 23060.61 }, { "date": "2026-06-05", "description": "WEWORK RENT", "amount": 2100, "direction": "debit", "category": "rent", "balance": 20960.61 } ], "transactionCount": 42, "usage": { "credits": 12, "balanceRemaining": 418 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resume": { "post": { "operationId": "resume", "summary": "Resume parsing", "description": "A resume or CV into a structured candidate profile: contact, skills, experience, education, and links.\n\nCost: 8 credits ($0.08) — charged only on success.", "tags": [ "Resume parsing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Provide exactly one of: file, fileUrl, or text.", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } ], "x-doc-input": true, "properties": {} }, "example": { "fileUrl": "https://…/resume.pdf" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "name", "skills", "experience", "education" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "yearsExperience": { "type": [ "number", "null" ] }, "skills": { "type": "array", "items": { "type": "string" } }, "experience": { "type": "array", "items": { "type": "object", "required": [ "title", "company", "highlights" ], "properties": { "title": { "type": "string" }, "company": { "type": "string" }, "startDate": { "type": [ "string", "null" ], "description": "YYYY-MM or 'present'." }, "endDate": { "type": [ "string", "null" ] }, "highlights": { "type": "array", "items": { "type": "string" } } } } }, "education": { "type": "array", "items": { "type": "object", "required": [ "school" ], "properties": { "degree": { "type": [ "string", "null" ] }, "school": { "type": "string" }, "year": { "type": [ "string", "null" ] } } } }, "links": { "type": "object", "properties": { "linkedin": { "type": [ "string", "null" ] }, "github": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "name": "Maya Chen", "email": "maya@…", "phone": "+1 415 …", "location": "Brooklyn, NY", "headline": "Senior Backend Engineer", "summary": "Backend engineer focused on payments infrastructure…", "yearsExperience": 8, "skills": [ "Go", "Postgres", "Kafka", "Kubernetes" ], "experience": [ { "title": "Senior Backend Engineer", "company": "Meridian Labs", "startDate": "2023-02", "endDate": "present", "highlights": [ "Cut settlement latency 70%" ] } ], "education": [ { "degree": "BS Computer Science", "school": "UC Berkeley", "year": "2018" } ], "links": { "linkedin": "https://linkedin.com/in/…", "github": "https://github.com/…", "website": null }, "usage": { "credits": 8, "balanceRemaining": 410 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tables": { "post": { "operationId": "tables", "summary": "Table extraction", "description": "Every table in a document — even scanned — as clean headers and rows, ready for your spreadsheet or DB.\n\nCost: 8 credits ($0.08) — charged only on success.", "tags": [ "Table extraction" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Provide exactly one of: file, fileUrl, or text.", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } ], "x-doc-input": true, "properties": {} }, "example": { "fileUrl": "https://…/quarterly-report.pdf" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "tables", "tableCount" ], "properties": { "tables": { "type": "array", "items": { "type": "object", "required": [ "headers", "rows" ], "properties": { "title": { "type": [ "string", "null" ] }, "page": { "type": [ "number", "null" ] }, "headers": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } } } }, "tableCount": { "type": "integer" } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "tables": [ { "title": "Revenue by region", "page": 4, "headers": [ "Region", "Q1", "Q2" ], "rows": [ [ "North America", "$1.2M", "$1.4M" ], [ "EMEA", "$800k", "$950k" ] ] } ], "tableCount": 3, "usage": { "credits": 8, "balanceRemaining": 402 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/split": { "post": { "operationId": "split", "summary": "Document splitting", "description": "A multi-document scan bundle classified and split: what each document is, where it starts and ends, and a summary.\n\nCost: 10 credits ($0.10) — charged only on success.", "tags": [ "Document splitting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Provide exactly one of: file, fileUrl, or text.", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } ], "x-doc-input": true, "properties": {} }, "example": { "fileUrl": "https://…/scan-bundle.pdf" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "documents", "documentCount" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "required": [ "docType", "title", "pageStart", "pageEnd", "summary" ], "properties": { "docType": { "type": "string" }, "title": { "type": "string" }, "pageStart": { "type": "number" }, "pageEnd": { "type": "number" }, "party": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "summary": { "type": "string" } } } }, "documentCount": { "type": "integer" } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "documents": [ { "docType": "invoice", "title": "Acme Supplies invoice INV-10428", "pageStart": 1, "pageEnd": 2, "party": "Acme Supplies Inc.", "date": "2026-06-30", "summary": "Invoice for 12 Widget A units, $1,255.50 total." }, { "docType": "coi", "title": "Certificate of insurance", "pageStart": 3, "pageEnd": 3, "party": "Hartford", "date": "2026-01-15", "summary": "GL certificate, $2M aggregate, expires 2027-01-15." } ], "documentCount": 2, "usage": { "credits": 10, "balanceRemaining": 392 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/compare": { "post": { "operationId": "compare", "summary": "Document comparison", "description": "Two versions of a contract or document → every material change, what it means, and the risk it carries.\n\nCost: 15 credits ($0.15) — charged only on success.", "tags": [ "Document comparison" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "a", "b" ], "x-ts-input": "{ a: DocumentInput; b: DocumentInput }", "properties": { "a": { "type": "object", "description": "The earlier version (file, fileUrl, or text).", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } }, "b": { "type": "object", "description": "The later version (file, fileUrl, or text).", "properties": { "file": { "type": "object", "description": "Inline document.", "properties": { "data": { "type": "string", "description": "Base64-encoded file bytes." }, "mimeType": { "type": "string", "example": "application/pdf" } }, "required": [ "data", "mimeType" ] }, "fileUrl": { "type": "string", "format": "uri", "description": "Public URL to a PDF or image." }, "text": { "type": "string", "description": "Raw text, if you already have it." } } } } }, "example": { "a": { "fileUrl": "https://…/msa-2025.pdf" }, "b": { "fileUrl": "https://…/msa-2026.pdf" } } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "changes", "changeCount", "summary", "riskNotes" ], "properties": { "changes": { "type": "array", "items": { "type": "object", "required": [ "section", "change", "materiality", "note" ], "properties": { "section": { "type": "string" }, "change": { "type": "string", "enum": [ "added", "removed", "modified" ] }, "before": { "type": [ "string", "null" ] }, "after": { "type": [ "string", "null" ] }, "materiality": { "type": "string", "enum": [ "low", "medium", "high" ] }, "note": { "type": "string" } } } }, "changeCount": { "type": "integer" }, "summary": { "type": "string" }, "riskNotes": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "changes": [ { "section": "Term & Renewal", "change": "modified", "before": "30 days' notice", "after": "90 days' notice", "materiality": "high", "note": "Cancellation window tripled — easy to miss the exit." } ], "changeCount": 6, "summary": "The 2026 draft raises fees 8% and tightens the renewal window…", "riskNotes": [ "Notice period tripled to 90 days", "Liability cap now excludes data breaches" ], "usage": { "credits": 15, "balanceRemaining": 377 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/structure": { "post": { "operationId": "structure", "summary": "Structure to your schema", "description": "Any messy input — text, HTML, an email — plus YOUR JSON schema → output shaped to it, validated against your required fields and property types, with an automatic corrective retry and a `valid` flag.\n\nCost: 6 credits ($0.06) — charged only on success.", "tags": [ "Structure to your schema" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input", "schema" ], "properties": { "input": { "type": "string", "description": "Any messy input — text, HTML, an email, a JSON blob." }, "schema": { "type": "object", "description": "The JSON Schema the output must conform to.", "additionalProperties": true }, "instructions": { "type": "string", "description": "Optional extra guidance." } } }, "example": { "input": "Hey — new order from Dana Reyes, dana@brightco.io. 3 large planters, ship to 44 Vine St Portland OR by the 20th.", "schema": { "type": "object", "required": [ "customer", "items" ], "properties": { "customer": { "type": "object" }, "items": { "type": "array" }, "shipTo": { "type": "string" }, "deadline": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "data", "valid" ], "properties": { "data": { "type": "object", "additionalProperties": true, "description": "The output, conforming to your schema." }, "valid": { "type": "boolean", "description": "True when every required field of your schema was satisfiable." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Anything the input couldn't support (missing required fields, ambiguities)." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "data": { "customer": { "name": "Dana Reyes", "email": "dana@brightco.io" }, "items": [ { "product": "large planter", "quantity": 3 } ], "shipTo": "44 Vine St, Portland OR", "deadline": "2026-07-20" }, "valid": true, "notes": [], "usage": { "credits": 6, "balanceRemaining": 371 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/normalize": { "post": { "operationId": "normalize", "summary": "Record normalization", "description": "A batch of messy records → clean canonical rows, with a change log of every fix (casing, formats, dedup-ready values).\n\nCost: 5 credits ($0.05) — charged only on success.", "tags": [ "Record normalization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 500, "description": "The messy records." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Canonical field names to normalize into; omit to keep the input's fields." }, "instructions": { "type": "string", "description": "House rules, e.g. \"US phone format, uppercase state codes\"." } } }, "example": { "records": [ { "name": "SMITH, jon", "phone": "415.555.0199", "state": "california" } ], "instructions": "US phone format, 2-letter state codes, Title Case names" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "records", "changes" ], "properties": { "records": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The cleaned records, same order as input." }, "changes": { "type": "array", "items": { "type": "object", "required": [ "index", "field", "to" ], "properties": { "index": { "type": "integer", "description": "Input record index." }, "field": { "type": "string" }, "from": { "type": [ "string", "null" ] }, "to": { "type": "string" }, "reason": { "type": "string" } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "records": [ { "name": "Jon Smith", "phone": "(415) 555-0199", "state": "CA" } ], "changes": [ { "index": 0, "field": "state", "from": "california", "to": "CA", "reason": "2-letter state code" } ], "usage": { "credits": 5, "balanceRemaining": 366 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/match": { "post": { "operationId": "match", "summary": "Entity matching", "description": "Two record sets → which rows are the same real-world thing, with confidence and reasoning. Fuzzy names, typos, aliases handled.\n\nCost: 8 credits ($0.08) — charged only on success.", "tags": [ "Entity matching" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "a", "b" ], "properties": { "a": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 200, "description": "First record set." }, "b": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 200, "description": "Second record set." }, "keys": { "type": "array", "items": { "type": "string" }, "description": "Fields that most identify an entity, e.g. [\"name\",\"email\"]." } } }, "example": { "a": [ { "name": "Acme Supplies Inc", "city": "Columbus" } ], "b": [ { "vendor": "ACME SUPPLY, INC.", "location": "Columbus, OH" } ], "keys": [ "name" ] } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "matches", "unmatchedA", "unmatchedB" ], "properties": { "matches": { "type": "array", "items": { "type": "object", "required": [ "aIndex", "bIndex", "confidence" ], "properties": { "aIndex": { "type": "integer" }, "bIndex": { "type": "integer" }, "confidence": { "type": "number", "description": "0–1." }, "reason": { "type": "string" } } } }, "unmatchedA": { "type": "array", "items": { "type": "integer" } }, "unmatchedB": { "type": "array", "items": { "type": "integer" } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "matches": [ { "aIndex": 0, "bIndex": 0, "confidence": 0.94, "reason": "Same entity: name variant + same city." } ], "unmatchedA": [], "unmatchedB": [], "usage": { "credits": 8, "balanceRemaining": 358 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/categorize": { "post": { "operationId": "categorize", "summary": "Batch categorization", "description": "Up to a hundred items against your taxonomy in one call — products, transactions, tickets — each with a confidence.\n\nCost: 3 credits ($0.03) — charged only on success.", "tags": [ "Batch categorization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "taxonomy" ], "properties": { "items": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "The things to categorize." }, "taxonomy": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 100, "description": "Your categories." }, "multi": { "type": "boolean", "description": "Allow multiple categories per item.", "default": false }, "instructions": { "type": "string" } } }, "example": { "items": [ "AWS invoice June", "Uber to airport", "Figma annual" ], "taxonomy": [ "software", "travel", "office", "other" ] } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "index", "category", "confidence" ], "properties": { "index": { "type": "integer", "description": "Input item index." }, "category": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "All categories when multi is set." }, "confidence": { "type": "number" } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "results": [ { "index": 0, "category": "software", "confidence": 0.97 }, { "index": 1, "category": "travel", "confidence": 0.98 }, { "index": 2, "category": "software", "confidence": 0.96 } ], "usage": { "credits": 3, "balanceRemaining": 355 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/dunning": { "post": { "operationId": "dunning", "summary": "Collections sequence", "description": "An overdue invoice → a ready-to-send collection sequence, escalating at the right pace and tone for how late it is.\n\nCost: 8 credits ($0.08) — charged only on success.", "tags": [ "Collections sequence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invoice", "customer" ], "properties": { "invoice": { "type": "object", "required": [ "amount" ], "properties": { "number": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "dueDate": { "type": "string", "description": "YYYY-MM-DD." }, "daysOverdue": { "type": "integer" } } }, "customer": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "history": { "type": "string", "description": "Payment history / relationship context." } } }, "tone": { "type": "string", "enum": [ "friendly", "firm", "final" ], "description": "Where to start the escalation." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "default": "email" }, "steps": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 } } }, "example": { "invoice": { "number": "INV-10428", "amount": 1255.5, "dueDate": "2026-06-15", "daysOverdue": 23 }, "customer": { "name": "Northwind Coffee", "history": "Usually pays on time; second late invoice this year." }, "steps": 3 } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "sequence", "escalationAdvice" ], "properties": { "sequence": { "type": "array", "items": { "type": "object", "required": [ "day", "channel", "message" ], "properties": { "day": { "type": "integer", "description": "Days from now to send." }, "channel": { "type": "string", "enum": [ "email", "sms" ] }, "subject": { "type": [ "string", "null" ] }, "message": { "type": "string" } } } }, "escalationAdvice": { "type": "string", "description": "What to do if the sequence completes unpaid." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "sequence": [ { "day": 0, "channel": "email", "subject": "Invoice INV-10428 — friendly nudge", "message": "Hi Northwind team…" }, { "day": 7, "channel": "email", "subject": "Invoice INV-10428 is 30 days past due", "message": "…" } ], "escalationAdvice": "If unpaid after step 3, move to a payment plan offer before collections — history suggests goodwill.", "usage": { "credits": 8, "balanceRemaining": 347 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/po-match": { "post": { "operationId": "po-match", "summary": "3-way match", "description": "Invoice vs purchase order vs receipt → matched, partial, or mismatched, with every discrepancy flagged and sized.\n\nCost: 10 credits ($0.10) — charged only on success.", "tags": [ "3-way match" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invoice", "purchaseOrder" ], "properties": { "invoice": { "type": "string", "description": "The invoice — structured JSON (e.g. /v1/invoice output) or raw text." }, "purchaseOrder": { "type": "string", "description": "The PO — structured JSON or raw text." }, "receipt": { "type": "string", "description": "Optional goods receipt / delivery note for a 3-way match." }, "tolerancePct": { "type": "number", "description": "Price variance tolerance in percent (default 2)." } } }, "example": { "invoice": "{…/v1/invoice output…}", "purchaseOrder": "PO-88: 12x Widget A @ $95, ship to Columbus", "receipt": "GRN: 12 Widget A received 2026-06-28" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "status", "discrepancies", "recommendation" ], "properties": { "status": { "type": "string", "enum": [ "matched", "partial", "mismatched" ] }, "discrepancies": { "type": "array", "items": { "type": "object", "required": [ "field", "severity", "note" ], "properties": { "field": { "type": "string" }, "invoice": { "type": [ "string", "null" ] }, "purchaseOrder": { "type": [ "string", "null" ] }, "receipt": { "type": [ "string", "null" ] }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "note": { "type": "string" } } } }, "recommendation": { "type": "string", "description": "approve | hold | reject, with the reason." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "status": "partial", "discrepancies": [ { "field": "unitPrice", "invoice": "$100.00", "purchaseOrder": "$95.00", "receipt": null, "severity": "high", "note": "5.3% over PO price — beyond 2% tolerance." } ], "recommendation": "hold — quantities match but unit price exceeds the PO; request a corrected invoice.", "usage": { "credits": 10, "balanceRemaining": 337 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/quote": { "post": { "operationId": "quote", "summary": "Quote builder", "description": "A job description plus your rates → an itemized, professional quote with assumptions and scope notes spelled out.\n\nCost: 8 credits ($0.08) — charged only on success.", "tags": [ "Quote builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "job" ], "properties": { "job": { "type": "string", "description": "What the customer needs, in plain words." }, "rates": { "type": "string", "description": "Your rate card / pricing rules, any format." }, "pastQuotes": { "type": "string", "description": "Optional examples of quotes you've sent." }, "currency": { "type": "string", "default": "USD" } } }, "example": { "job": "Repaint a 2-bedroom apartment, walls + trim, tenant moves in Aug 1", "rates": "$65/hr labor, materials at cost +10%" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "lineItems", "total", "assumptions" ], "properties": { "lineItems": { "type": "array", "items": { "type": "object", "required": [ "description", "amount" ], "properties": { "description": { "type": "string" }, "quantity": { "type": [ "number", "null" ] }, "unitPrice": { "type": [ "number", "null" ] }, "amount": { "type": "number" } } } }, "subtotal": { "type": [ "number", "null" ] }, "tax": { "type": [ "number", "null" ] }, "total": { "type": "number" }, "currency": { "type": "string" }, "assumptions": { "type": "array", "items": { "type": "string" } }, "scopeNotes": { "type": [ "string", "null" ], "description": "What's explicitly out of scope." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "lineItems": [ { "description": "Prep + painting labor (2BR walls & trim)", "quantity": 26, "unitPrice": 65, "amount": 1690 }, { "description": "Paint & materials (est.)", "quantity": null, "unitPrice": null, "amount": 420 } ], "subtotal": 2110, "tax": null, "total": 2110, "currency": "USD", "assumptions": [ "Standard 8-ft ceilings", "Two coats", "Unit empty during work" ], "scopeNotes": "Ceilings and cabinet interiors excluded.", "usage": { "credits": 8, "balanceRemaining": 329 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fraud-flag": { "post": { "operationId": "fraud-flag", "summary": "Fraud triage", "description": "An order or transaction in context → a risk score, the signals driving it, and the checks worth running before you ship.\n\nCost: 6 credits ($0.06) — charged only on success.", "tags": [ "Fraud triage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "order" ], "properties": { "order": { "type": "object", "additionalProperties": true, "description": "The order/transaction: amount, email, addresses, IP, device, history — whatever you have." }, "context": { "type": "string", "description": "Store context: typical order size, known patterns." } } }, "example": { "order": { "amount": 950, "email": "qq1998x@tempmail.dev", "shippingCity": "Miami", "billingCity": "Portland", "ip": "203.0.113.9", "accountAgeDays": 0, "expedited": true } } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "riskScore", "riskLevel", "signals", "recommendation" ], "properties": { "riskScore": { "type": "number", "description": "0–1." }, "riskLevel": { "type": "string", "enum": [ "low", "medium", "high" ] }, "signals": { "type": "array", "items": { "type": "object", "required": [ "signal", "weight", "note" ], "properties": { "signal": { "type": "string" }, "weight": { "type": "string", "enum": [ "low", "medium", "high" ] }, "note": { "type": "string" } } } }, "recommendedChecks": { "type": "array", "items": { "type": "string" } }, "recommendation": { "type": "string", "enum": [ "allow", "review", "block" ] } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "riskScore": 0.82, "riskLevel": "high", "signals": [ { "signal": "Disposable email domain", "weight": "high", "note": "tempmail.dev is a throwaway provider." }, { "signal": "Billing/shipping mismatch + rush shipping", "weight": "medium", "note": "Classic resale pattern on a new account." } ], "recommendedChecks": [ "3DS challenge", "Verify phone", "Match IP geolocation to billing" ], "recommendation": "review", "usage": { "credits": 6, "balanceRemaining": 323 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reply": { "post": { "operationId": "reply", "summary": "Reply drafting", "description": "A customer thread plus your context → a ready-to-send reply in the right tone, with an internal note for the agent.\n\nCost: 5 credits ($0.05) — charged only on success.", "tags": [ "Reply drafting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "thread" ], "properties": { "thread": { "type": "string", "description": "The email/ticket thread, newest last." }, "context": { "type": "string", "description": "Policies, KB extracts, account facts the reply may use." }, "tone": { "type": "string", "enum": [ "professional", "friendly", "apologetic", "firm" ], "default": "professional" }, "goal": { "type": "string", "description": "What the reply should achieve, e.g. \"offer refund, keep them\"." }, "senderName": { "type": "string", "description": "Sign-off name." } } }, "example": { "thread": "Customer: I was charged twice for order 5561 and support hasn't replied in 3 days.", "context": "Duplicate charge confirmed in Stripe; refund takes 5-10 days.", "tone": "apologetic", "goal": "Refund the duplicate, keep the customer", "senderName": "Sam" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "reply" ], "properties": { "reply": { "type": "string", "description": "Ready to send." }, "subject": { "type": [ "string", "null" ] }, "internalNote": { "type": [ "string", "null" ], "description": "For the human agent: caveats, things to verify." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "reply": "Hi — you're right, and I'm sorry about the silence. I've refunded the duplicate charge just now…", "subject": "Re: Double charge on order 5561 — refunded", "internalNote": "Refund issued; check why the retry fired twice on this order.", "usage": { "credits": 5, "balanceRemaining": 318 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/triage": { "post": { "operationId": "triage", "summary": "Ticket triage", "description": "A support ticket → priority, category, the team it belongs to, sentiment, SLA risk, and a suggested first response.\n\nCost: 3 credits ($0.03) — charged only on success.", "tags": [ "Ticket triage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ticket" ], "properties": { "ticket": { "type": "string", "description": "The ticket text (subject + body)." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Your category set; omit for sensible defaults." }, "teams": { "type": "array", "items": { "type": "string" }, "description": "Routable teams." } } }, "example": { "ticket": "Subject: URGENT site down\nOur checkout has been erroring for 2 hours, we're losing sales.", "categories": [ "bug", "billing", "how-to" ], "teams": [ "payments", "platform", "support" ] } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "priority", "category", "sentiment", "slaRisk", "summary" ], "properties": { "priority": { "type": "string", "enum": [ "urgent", "high", "normal", "low" ] }, "category": { "type": "string" }, "team": { "type": [ "string", "null" ] }, "sentiment": { "type": "string" }, "slaRisk": { "type": "boolean", "description": "True when this smells like churn/escalation." }, "summary": { "type": "string", "description": "One line for the queue view." }, "suggestedFirstResponse": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "priority": "urgent", "category": "bug", "team": "payments", "sentiment": "frustrated", "slaRisk": true, "summary": "Checkout erroring 2h in production — revenue impact.", "suggestedFirstResponse": "Acknowledge outage, confirm engineers engaged, promise 30-min updates.", "usage": { "credits": 3, "balanceRemaining": 315 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/minutes": { "post": { "operationId": "minutes", "summary": "Meeting minutes", "description": "A meeting transcript → clean minutes: summary, decisions made, action items with owners, and open questions.\n\nCost: 6 credits ($0.06) — charged only on success.", "tags": [ "Meeting minutes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transcript" ], "properties": { "transcript": { "type": "string", "description": "The meeting transcript." }, "attendees": { "type": "array", "items": { "type": "string" } } } }, "example": { "transcript": "<45-minute product sync transcript…>", "attendees": [ "Priya", "Marco", "Dana" ] } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "title", "summary", "decisions", "actionItems", "openQuestions" ], "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "decisions": { "type": "array", "items": { "type": "string" } }, "actionItems": { "type": "array", "items": { "type": "object", "required": [ "task" ], "properties": { "task": { "type": "string" }, "owner": { "type": [ "string", "null" ] }, "due": { "type": [ "string", "null" ] } } } }, "openQuestions": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "title": "Product sync — launch readiness", "summary": "Launch moves to Friday behind the payment fix…", "decisions": [ "Launch Friday, not Thursday" ], "actionItems": [ { "task": "Deploy duplicate-charge fix", "owner": "Priya", "due": "2026-07-10" } ], "openQuestions": [ "Does the churn dashboard need the new events?" ], "usage": { "credits": 6, "balanceRemaining": 309 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/outreach": { "post": { "operationId": "outreach", "summary": "Outreach sequence", "description": "An enriched lead plus what you sell → a personalized outreach sequence that references what actually makes them a fit.\n\nCost: 6 credits ($0.06) — charged only on success.", "tags": [ "Outreach sequence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead", "product" ], "properties": { "lead": { "type": "string", "description": "Who you're writing to — an enriched profile (e.g. /v1/enrich output) or notes." }, "product": { "type": "string", "description": "What you sell and the value proposition." }, "sender": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "company": { "type": "string" } } }, "channel": { "type": "string", "enum": [ "email", "linkedin" ], "default": "email" }, "steps": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 } } }, "example": { "lead": "{…/v1/enrich output for brightco.io…}", "product": "Kynth Verbatim — meeting notes that write themselves", "sender": { "name": "Isaiah", "role": "Founder", "company": "Kynth" }, "steps": 2 } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "sequence", "personalizationPoints" ], "properties": { "sequence": { "type": "array", "items": { "type": "object", "required": [ "day", "message" ], "properties": { "day": { "type": "integer" }, "subject": { "type": [ "string", "null" ] }, "message": { "type": "string" } } } }, "personalizationPoints": { "type": "array", "items": { "type": "string" }, "description": "The lead-specific facts the copy leans on." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "sequence": [ { "day": 0, "subject": "Notes for BrightCo's client calls", "message": "Hi Dana — saw BrightCo runs 20+ client calls a week…" }, { "day": 4, "subject": null, "message": "Bumping this — one line…" } ], "personalizationPoints": [ "Agency model = heavy client-call volume", "Recent hiring spree in account management" ], "usage": { "credits": 6, "balanceRemaining": 303 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/review-reply": { "post": { "operationId": "review-reply", "summary": "Review response", "description": "A customer review → a brand-safe public response, the issues to log, and whether it needs human escalation.\n\nCost: 3 credits ($0.03) — charged only on success.", "tags": [ "Review response" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "review" ], "properties": { "review": { "type": "string", "description": "The customer review text." }, "rating": { "type": "number", "description": "Star rating if known." }, "business": { "type": "object", "properties": { "name": { "type": "string" }, "voice": { "type": "string", "description": "Brand voice notes." } } }, "resolution": { "type": "string", "description": "What you can offer, e.g. \"replacement or refund\"." } } }, "example": { "review": "Two stars. The product is fine but delivery took three weeks and nobody answered my emails.", "rating": 2, "business": { "name": "Loomworks", "voice": "warm, direct, no corporate speak" }, "resolution": "free shipping on next order" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "reply", "sentiment", "issues", "escalate" ], "properties": { "reply": { "type": "string", "description": "Public response, brand-safe." }, "sentiment": { "type": "string" }, "issues": { "type": "array", "items": { "type": "string" }, "description": "Product/ops issues worth logging." }, "escalate": { "type": "boolean", "description": "True when a human should take over." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "reply": "That's on us — three weeks is far too long, and going quiet made it worse…", "sentiment": "negative", "issues": [ "Shipping delay (3 weeks)", "Support unresponsive via email" ], "escalate": false, "usage": { "credits": 3, "balanceRemaining": 300 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/moderate": { "post": { "operationId": "moderate", "summary": "Content moderation", "description": "Text or an image against YOUR policy → allow, review, or block, with the categories and excerpts that drove the call.\n\nCost: 2 credits ($0.02) — charged only on success.", "tags": [ "Content moderation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provide text and/or an image.", "properties": { "text": { "type": "string" }, "image": { "type": "object", "properties": { "data": { "type": "string", "description": "Base64." }, "mimeType": { "type": "string" } }, "required": [ "data", "mimeType" ] }, "imageUrl": { "type": "string", "format": "uri" }, "policy": { "type": "string", "description": "YOUR rules, plain words — e.g. \"no medical claims, no competitor names\". Adds to the safety baseline." } } }, "example": { "text": "This supplement cures anxiety in 3 days, guaranteed — DM me for a discount code.", "policy": "No medical claims. No off-platform solicitation." } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "flagged", "decision", "categories", "rationale" ], "properties": { "flagged": { "type": "boolean" }, "decision": { "type": "string", "enum": [ "allow", "review", "block" ] }, "categories": { "type": "array", "items": { "type": "object", "required": [ "category", "severity" ], "properties": { "category": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "excerpt": { "type": [ "string", "null" ], "description": "The offending span, when text." } } } }, "rationale": { "type": "string" } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "flagged": true, "decision": "block", "categories": [ { "category": "medical claim", "severity": "high", "excerpt": "cures anxiety in 3 days, guaranteed" }, { "category": "off-platform solicitation", "severity": "medium", "excerpt": "DM me for a discount code" } ], "rationale": "Direct cure claim violates the medical-claims rule; DM solicitation violates platform policy.", "usage": { "credits": 2, "balanceRemaining": 298 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rewrite": { "post": { "operationId": "rewrite", "summary": "Brand-voice rewrite", "description": "Any copy → your brand voice. Describe the voice or paste a sample; get the rewrite and what changed.\n\nCost: 3 credits ($0.03) — charged only on success.", "tags": [ "Brand-voice rewrite" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "voice": { "type": "string", "description": "Describe the voice or paste a sample of it." }, "goal": { "type": "string", "description": "e.g. \"tighter, more confident\"." }, "audience": { "type": "string" }, "length": { "type": "string", "enum": [ "shorter", "same", "longer" ], "default": "same" } } }, "example": { "text": "We are pleased to announce our new feature is now available to all users.", "voice": "Confident, plain-spoken, a little wry. Short sentences.", "goal": "sound human", "length": "same" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "rewritten", "changes" ], "properties": { "rewritten": { "type": "string" }, "changes": { "type": "array", "items": { "type": "string" }, "description": "What was changed and why." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "rewritten": "It's live. Every account has the new feature as of today — go try it.", "changes": [ "Dropped the press-release opener", "Active voice, shorter sentences" ], "usage": { "credits": 3, "balanceRemaining": 295 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/product-copy": { "post": { "operationId": "product-copy", "summary": "Product copy", "description": "Specs and an audience → listing-ready titles, bullets, a description, and SEO keywords — per channel.\n\nCost: 5 credits ($0.05) — charged only on success.", "tags": [ "Product copy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "features": { "type": "string", "description": "Specs / features, any format." }, "audience": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } } } }, "channel": { "type": "string", "enum": [ "amazon", "shopify", "generic" ], "default": "generic" } } }, "example": { "product": { "name": "Meridian standing desk", "features": "Dual motor, 48x30 bamboo top, memory presets, 300lb capacity", "audience": "home-office workers", "keywords": [ "standing desk", "adjustable desk" ] }, "channel": "shopify" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "titles", "bullets", "description", "seoKeywords" ], "properties": { "titles": { "type": "array", "items": { "type": "string" }, "description": "Ranked title options." }, "bullets": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "seoKeywords": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "titles": [ "Meridian Standing Desk — dual-motor bamboo, four memory heights" ], "bullets": [ "Dual motors lift 300 lbs without the wobble", "48\"×30\" solid bamboo top" ], "description": "The Meridian is the desk you stop thinking about…", "seoKeywords": [ "standing desk", "adjustable height desk", "bamboo standing desk" ], "usage": { "credits": 5, "balanceRemaining": 290 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/describe": { "post": { "operationId": "describe", "summary": "Image description", "description": "An image → accessible alt text, a caption, tags, and any text found inside it. Accessibility and catalogs in one call.\n\nCost: 3 credits ($0.03) — charged only on success.", "tags": [ "Image description" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provide image or imageUrl.", "properties": { "image": { "type": "object", "properties": { "data": { "type": "string", "description": "Base64." }, "mimeType": { "type": "string" } }, "required": [ "data", "mimeType" ] }, "imageUrl": { "type": "string", "format": "uri" }, "purpose": { "type": "string", "enum": [ "alt", "caption", "product", "detailed" ], "default": "alt" } } }, "example": { "imageUrl": "https://…/product-shot.jpg", "purpose": "product" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "altText", "caption", "tags" ], "properties": { "altText": { "type": "string", "description": "Concise, accessibility-grade." }, "caption": { "type": "string" }, "detailed": { "type": [ "string", "null" ], "description": "Long-form description when purpose=detailed." }, "tags": { "type": "array", "items": { "type": "string" } }, "embeddedText": { "type": [ "string", "null" ], "description": "Any text found inside the image." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "altText": "Matte-black standing desk with a bamboo top in a sunlit home office", "caption": "The Meridian desk at full height, morning light.", "detailed": null, "tags": [ "standing desk", "bamboo", "home office" ], "embeddedText": null, "usage": { "credits": 3, "balanceRemaining": 287 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/research": { "post": { "operationId": "research", "summary": "Research brief", "description": "A company or topic → a multi-source, citation-backed brief: what it is, what changed lately, and what matters. Real web work.\n\nCost: 50 credits ($0.50) — charged only on success.", "tags": [ "Research brief" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The company, topic, or question to research." }, "focus": { "type": "string", "description": "What matters to you, e.g. \"pricing changes and funding\"." }, "depth": { "type": "string", "enum": [ "standard", "deep" ], "default": "standard", "description": "deep reads more sources." } } }, "example": { "query": "brightco.io", "focus": "funding, pricing changes, hiring signals" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "brief", "findings", "sources" ], "properties": { "brief": { "type": "string", "description": "The synthesized answer, a few paragraphs." }, "findings": { "type": "array", "items": { "type": "object", "required": [ "finding", "sourceIndexes" ], "properties": { "finding": { "type": "string" }, "sourceIndexes": { "type": "array", "items": { "type": "integer" }, "description": "Indexes into sources[]." } } } }, "sources": { "type": "array", "items": { "type": "object", "required": [ "url", "title" ], "properties": { "url": { "type": "string" }, "title": { "type": "string" } } } } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "brief": "BrightCo is a 40-person client-services platform that raised an $8M Series A in March…", "findings": [ { "finding": "Raised $8M Series A led by Foundry (March 2026)", "sourceIndexes": [ 0, 2 ] }, { "finding": "Pricing page moved from seats to usage tiers in May", "sourceIndexes": [ 1 ] } ], "sources": [ { "url": "https://techcrunch.com/…", "title": "BrightCo raises $8M…" }, { "url": "https://brightco.io/pricing", "title": "BrightCo pricing" } ], "usage": { "credits": 50, "balanceRemaining": 237 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/screen": { "post": { "operationId": "screen", "summary": "Lead screening", "description": "A lead plus your ICP criteria → a web-grounded qualification verdict with the evidence for and against.\n\nCost: 10 credits ($0.10) — charged only on success.", "tags": [ "Lead screening" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead", "criteria" ], "properties": { "lead": { "type": "string", "description": "Company domain, name, or a pasted profile." }, "criteria": { "type": "string", "description": "Your ICP, plain words — e.g. \"B2B SaaS, 20-200 employees, US, sells to finance teams\"." } } }, "example": { "lead": "brightco.io", "criteria": "B2B SaaS or agency, 20-200 people, US-based, runs client meetings at volume" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "verdict", "score", "evidenceFor", "evidenceAgainst" ], "properties": { "verdict": { "type": "string", "enum": [ "qualified", "maybe", "disqualified" ] }, "score": { "type": "number", "description": "0–1 fit." }, "evidenceFor": { "type": "array", "items": { "type": "string" } }, "evidenceAgainst": { "type": "array", "items": { "type": "string" } }, "profile": { "type": "object", "additionalProperties": true, "description": "What we learned about the lead." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "verdict": "qualified", "score": 0.86, "evidenceFor": [ "~40 employees (LinkedIn)", "US HQ, Denver", "Agency model — client calls are the core motion" ], "evidenceAgainst": [ "Recently switched tooling — may be locked in a contract" ], "profile": { "name": "BrightCo", "employees": "~40", "hq": "Denver, CO" }, "usage": { "credits": 10, "balanceRemaining": 227 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/transcribe": { "post": { "operationId": "transcribe", "summary": "Transcription", "description": "An audio recording → accurate text with speakers and paragraph timestamps. Meetings, calls, voice notes.\n\nCost: 10 credits ($0.10) — charged only on success.", "tags": [ "Transcription" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provide audio { data, mimeType } or audioUrl.", "properties": { "audio": { "type": "object", "properties": { "data": { "type": "string", "description": "Base64 audio." }, "mimeType": { "type": "string", "example": "audio/mp3" } }, "required": [ "data", "mimeType" ] }, "audioUrl": { "type": "string", "format": "uri" }, "diarize": { "type": "boolean", "default": true, "description": "Label speakers." }, "language": { "type": "string", "description": "BCP-47 hint, e.g. \"en\"." } } }, "example": { "audioUrl": "https://…/standup.mp3", "diarize": true } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "text", "segments" ], "properties": { "text": { "type": "string", "description": "The full transcript." }, "segments": { "type": "array", "items": { "type": "object", "required": [ "text" ], "properties": { "speaker": { "type": [ "string", "null" ], "description": "e.g. \"Speaker 1\"." }, "start": { "type": [ "string", "null" ], "description": "MM:SS." }, "text": { "type": "string" } } } }, "language": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "text": "Alright, quick standup. Priya, want to start? …", "segments": [ { "speaker": "Speaker 1", "start": "00:00", "text": "Alright, quick standup. Priya, want to start?" }, { "speaker": "Speaker 2", "start": "00:04", "text": "Sure — the duplicate-charge fix is reviewed…" } ], "language": "en", "usage": { "credits": 10, "balanceRemaining": 217 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/memory": { "post": { "operationId": "memory", "summary": "Agent memory", "description": "Store, search, and forget memories for your agents — semantic recall on your own namespace, no vector DB to run.\n\nCost: 2 credits ($0.02) — charged only on success.", "tags": [ "Agent memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "enum": [ "store", "search", "forget" ], "description": "The operation." }, "namespace": { "type": "string", "description": "Your partition key — an agent id, a user id. Defaults to \"default\"." }, "content": { "type": "string", "description": "store: the memory text." }, "metadata": { "type": "object", "additionalProperties": true, "description": "store: attached metadata, returned on recall." }, "query": { "type": "string", "description": "search: what to recall." }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 5, "description": "search: max results." }, "id": { "type": "string", "description": "forget: the memory id (or omit with namespace to wipe it)." } } }, "example": { "op": "search", "namespace": "agent-42", "query": "what does the customer prefer for delivery?", "limit": 3 } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "enum": [ "store", "search", "forget" ] }, "id": { "type": [ "string", "null" ], "description": "store: the new memory's id." }, "results": { "type": "array", "items": { "type": "object", "required": [ "id", "content", "score" ], "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "score": { "type": "number", "description": "Semantic similarity 0–1." }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string" } } }, "description": "search: the recalled memories." }, "deleted": { "type": [ "integer", "null" ], "description": "forget: how many were removed." } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "op": "search", "results": [ { "id": "mem_8f3a…", "content": "Customer prefers evening deliveries after 6pm, no signature.", "score": 0.91, "metadata": { "source": "ticket-5561" }, "createdAt": "2026-07-01T18:22:00Z" } ], "usage": { "credits": 2, "balanceRemaining": 215 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/image": { "post": { "operationId": "image", "summary": "Image generation", "description": "A prompt → a production-ready image. Marketing visuals, product scenes, and consistent brand imagery.\n\nCost: 10 credits ($0.10) — charged only on success.", "tags": [ "Image generation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "What to generate." }, "style": { "type": "string", "description": "Style notes, e.g. \"editorial photography, warm light\"." }, "aspectRatio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4" ], "default": "1:1" } } }, "example": { "prompt": "A minimal hero image of a bamboo standing desk in warm morning light", "style": "editorial photography", "aspectRatio": "16:9" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "image", "mimeType" ], "properties": { "image": { "type": "string", "description": "Base64 image bytes." }, "mimeType": { "type": "string", "example": "image/png" }, "revisedPrompt": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "image": "", "mimeType": "image/png", "revisedPrompt": null, "usage": { "credits": 10, "balanceRemaining": 205 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/speak": { "post": { "operationId": "speak", "summary": "Text to speech", "description": "Text → natural speech audio, ready to embed. Voice notes, IVR lines, narration.\n\nCost: 5 credits ($0.05) — charged only on success.", "tags": [ "Text to speech" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 5000 }, "voice": { "type": "string", "description": "Voice name; omit for the default narrator." }, "pace": { "type": "string", "enum": [ "slow", "normal", "fast" ], "default": "normal" } } }, "example": { "text": "Your order has shipped and will arrive Thursday.", "pace": "normal" } } } }, "responses": { "200": { "description": "Success. Result fields plus a usage envelope.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "audio", "mimeType" ], "properties": { "audio": { "type": "string", "description": "Base64 audio bytes." }, "mimeType": { "type": "string", "example": "audio/wav" }, "durationSec": { "type": [ "number", "null" ] } } }, { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } ] }, "example": { "audio": "", "mimeType": "audio/wav", "durationSec": 3.4, "usage": { "credits": 5, "balanceRemaining": 200 } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — top up in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key, e.g. `Authorization: Bearer ksk_live_…`. Mint one in the dashboard." } }, "schemas": { "Usage": { "type": "object", "properties": { "credits": { "type": "integer", "description": "Credits burned by this call." }, "balanceRemaining": { "type": "integer", "description": "Wallet balance after the charge." } }, "required": [ "credits", "balanceRemaining" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "rate_limited", "insufficient_credits", "unprocessable", "inference_unavailable" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }