{"openapi": "3.1.0", "info": {"title": "Conecto", "version": "1", "description": "The business backend for AI agents, paid per call. Failed calls cost nothing."}, "servers": [{"url": "https://api.conecto.chat"}], "security": [{"key": []}], "components": {"securitySchemes": {"key": {"type": "http", "scheme": "bearer", "description": "A conecto_sk_ key from /v1/signup."}}}, "tags": [{"name": "account", "description": "Balance, limits and the call log. Included in every connector."}, {"name": "crm", "description": "Contacts, companies and deals in pipelines, with notes, tasks, tags, custom fields, saved segments, one search, full timelines, duplicate merging, bulk saves, reports and CSV export: the business's customer records."}, {"name": "chat", "description": "The business's website chat widget (and Beside), answered by you: visitor messages reach you at once, you reply, read and close conversations. Conecto runs no AI of its own in it. $0.05 per conversation."}, {"name": "email", "description": "Inboxes on the business's own useconecto.com subdomain: send, receive and read threads, linked to CRM contacts."}, {"name": "phone", "description": "Phone numbers for the business, answered by you: each thing a caller says reaches your webhook and the line speaks your answer, or the line takes a message. Read call transcripts. $0.25 per started minute of answered calls."}, {"name": "calendar", "description": "The business's own Cal.com: meeting types, free times, booking pages, bookings moved or cancelled by anyone, Google/Microsoft sync, and calls that confirm meetings booked in advance."}, {"name": "helpdesk", "description": "Support tickets: support inboxes whose email opens and continues tickets, replies in the same thread, SLA targets and work queues, canned replies, tags and custom fields, merging, satisfaction ratings, auto-close and reports."}, {"name": "helpcenter", "description": "The business's public help center: design it, write and publish articles, see what visitors searched for and could not find."}, {"name": "visibility", "description": "How ChatGPT, Claude, Gemini, Grok, Perplexity, DeepSeek and Google AI Overviews describe the business, next to its competitors, and what to do to show up more often."}, {"name": "imports", "description": "Bring a business's records over from the tools it is leaving: contacts, companies, deals, notes, tasks and tickets."}, {"name": "analytics", "description": "Count a website's visits with one script tag, like Plausible or Umami: visitors, pages, sources, countries, devices and custom events. No cookies, and no IP addresses kept. $3 a month per site with 100,000 events."}, {"name": "code", "description": "Run Python or Node.js in a fresh sandbox with no network: files from the store go in, the files it writes come back. $0.0001 per second of run time, at least $0.005 a run."}, {"name": "admin", "description": "What the account page does: its Home in one read, the people and their teams, join codes for other bots, and colleagues joining with their work address."}, {"name": "documents", "description": "PDFs from Markdown or HTML, Word and office files turned into PDFs, Word templates filled with data, PDFs merged and read."}, {"name": "esign", "description": "Send PDFs for signature like Documenso: each signer signs in the browser, and everyone gets the sealed PDF with a signing certificate."}, {"name": "hiring", "description": "A careers page with jobs people apply to (résumé, cover letter, your questions), and the applicants, moved through each job's stages, rated, noted and emailed. $0.50 per application."}, {"name": "outreach", "description": "Cold email campaigns from the business's own mailboxes: emails the agent writes, sent on a schedule with an unsubscribe line, follow-ups that stop when someone replies, and each person's status in the CRM. $0.01 per person messaged."}, {"name": "prospects", "description": "Businesses that could buy from you and the people to reach there, with their work email checked, found after a short interview about the customers you want. $0.05 per prospect found with a working email."}, {"name": "lookups", "description": "What a company is, from its domain (Conecto's index of public company facts, else its homepage), and whether email addresses can take mail. No person data."}, {"name": "newsletters", "description": "Newsletters people join by confirming their address: issues written in Markdown, sent through the business's own email service from its own domain, with one-click unsubscribe, a public page with the archive, and click counts. Free."}, {"name": "notify", "description": "Messages to the business's own Slack, Microsoft Teams, Discord, Google Chat, Telegram, ntfy, Pushover or webhooks."}, {"name": "projects", "description": "Boards of numbered tasks like Linear: statuses, priorities, assignees, labels, due dates, subtasks, comments and CRM links."}, {"name": "schedules", "description": "Tool calls that repeat on their own: every 15 minutes, hourly, daily, weekly or monthly in the business's time zone, run as the bot that set them, under its budget."}, {"name": "speech", "description": "Transcribe audio and video in about 100 languages, and turn text into natural speech with a choice of voices."}, {"name": "uptime", "description": "Watch pages every 1 to 60 minutes, get told when they go down or come back, and publish a status page."}, {"name": "vault", "description": "The business's secrets (API keys, passwords, logins) kept encrypted for its bots; values never appear in the call log."}, {"name": "web", "description": "Search the web, each result with its title, link and snippet, and read any public page as clean Markdown, with its links."}, {"name": "tables", "description": "Airtable for bots: tables of typed columns, rows filled, queried, sorted, imported from CSV and exported."}, {"name": "links", "description": "QR codes for any link or text, as PNG or SVG files. Short links follow on their own domain."}, {"name": "images", "description": "Resize, crop, convert (WebP, AVIF, JPEG, PNG) and compress images from the file store, with photo metadata removed."}, {"name": "files", "description": "A private file store for the business: upload files or fetch them from a link, hand out download links that expire, pass them to other tools, and file them: titles, tags, types, correspondents, dates and custom fields, found by the words inside, scans read with OCR, email attachments saved. 1 GB free, and 5 GB of downloads a month."}, {"name": "forms", "description": "Forms and surveys on the business's own public pages: contact and sign-up forms, feedback and NPS. Responses can go to the CRM and the owner's inbox; read, summarize and export them. $0.01 per response received."}, {"name": "invoices", "description": "Quotes and invoices in the business's own name: numbered without gaps, sent as PDFs with a page to view, accept or pay, payments recorded, reminders, and what customers owe."}, {"name": "books", "description": "The business's double-entry books: a chart of accounts, journal entries, expenses with receipts, taxes, bank statements imported (CSV, CAMT.053, OFX) and matched, invoices posted on their own, locked periods, and profit and loss, balance sheet, trial balance, ledger and tax reports."}, {"name": "inventory", "description": "What the business keeps in stock and where: items with SKUs and barcodes, locations, stock received, shipped, moved and counted, the moving-average cost and value, a low-stock event, and CSV in and out."}, {"name": "whistleblowing", "description": "The reporting channel every employer with 50 or more staff must run: anyone reports a concern, anonymously if they like, and only the named handlers read it. The bot follows deadlines and numbers, never content."}, {"name": "connect", "description": "The company's other systems, reached through Conecto: their credentials kept encrypted, each limited to the calls it allows, every call in the log."}, {"name": "microsoft365", "description": "The company's own Outlook mail, calendars and OneDrive files, through its own app: the agent acts only as the mailboxes the company names, and Microsoft stays the source of truth."}, {"name": "googleworkspace", "description": "The company's own Gmail, Google Calendar and Drive, through its own service account: the agent acts only as the mailboxes the company names, and Google stays the source of truth."}, {"name": "hubspot", "description": "The company's own HubSpot, through its own private app: the agent finds, reads and changes contacts, companies, deals and tickets there, and HubSpot stays the source of truth."}, {"name": "salesforce", "description": "The company's own Salesforce org, through its own connected app: the agent queries, reads and changes records there, and Salesforce stays the source of truth."}, {"name": "directory", "description": "The company's Microsoft Entra ID or Okta: the agent opens accounts for joiners, keeps titles and teams in step with HR, and suspends leavers, with the owner's approval."}, {"name": "hr", "description": "The business's people and their time off, for small teams: records with managers and documents, leave types with balances, requests you approve, public holidays, who is out, onboarding and offboarding checklists, reports and a morning digest. No payroll."}, {"name": "social", "description": "Post to the business's own social accounts (LinkedIn, Bluesky, Mastodon, Telegram, Discord, Slack, WordPress, Medium and more as networks approve Conecto): connect them, post now or later with media, see what went out and how it did. $0.02 per channel a post goes to; the rest is free."}, {"name": "purchasing", "description": "What the business buys: suppliers, purchase orders emailed as PDFs and received into stock, supplier bills with due dates and payments, posted to the books, what is owed to whom and what was spent."}, {"name": "websites", "description": "The business's website at cncto.co/w/<name>: pages built from sections (hero, features, pricing, FAQ, contact, booking...) and a blog, drawn in its brand kit as fast plain HTML, previewed privately, published and rolled back. $5 a month per published site."}, {"name": "views", "description": "Show a person what you found: numbers, charts, tables and lists on one page that opens from a one-time link. Save a view as the company's dashboard and update it whenever you like."}], "paths": {"/v1/signup": {"post": {"operationId": "signup", "summary": "Sign up and get a key", "security": [], "description": "Creates the account, a key and $1.00 of free credit. With join, a key on the company's account instead, for the team and areas its code names; that reply has joined and scope in place of the credit, the monthly ceiling, the terms and owner_note.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["bot_name", "accept_terms"], "properties": {"bot_name": {"type": "string"}, "accept_terms": {"type": "boolean", "const": true}, "business_name": {"type": "string"}, "owner_email": {"type": "string", "format": "email"}, "country": {"type": "string", "pattern": "^[A-Za-z]{2}$"}, "runtime": {"type": "string"}, "website": {"type": "string", "description": "The business's website."}, "referral": {"type": "string", "maxLength": 40, "description": "A Conecto partner's code, if one sent you; only at signup."}, "join": {"type": "string", "description": "A join code (conecto_join_...) the company gave you."}, "accountable": {"type": "string", "maxLength": 200, "description": "With join: the person who answers for this bot."}}}}}}, "responses": {"201": {"description": "The key (shown once) and the balance.", "content": {"application/json": {"schema": {"type": "object", "properties": {"account_id": {"type": "integer"}, "business_name": {"type": "string"}, "key": {"type": "string"}, "key_note": {"type": "string"}, "balance_usd": {"type": "string"}, "free_credit_usd": {"type": "string"}, "free_credit_note": {"type": ["string", "null"]}, "daily_budget_usd": {"type": "string"}, "monthly_ceiling_usd": {"type": "string"}, "owner_note": {"type": "string", "description": "What the owner email means: whether anyone has something to confirm, and who raises limits."}, "terms": {"type": "object"}, "next": {"type": "object"}}}}}}}}}, "/v1/balance": {"get": {"operationId": "balance", "summary": "Check the balance", "responses": {"200": {"description": "The balance and limits.", "content": {"application/json": {"schema": {"type": "object", "properties": {"balance_usd": {"type": "string"}, "reserved_usd": {"type": "string"}, "daily_budget_usd": {"type": "string"}, "monthly_ceiling_usd": {"type": "string"}, "auto_reload": {"type": "object", "properties": {"status": {"type": "string", "enum": ["off", "pending", "active", "failed"]}, "amount_usd": {"type": "string"}}}, "free_this_month": {"type": "object", "description": "This month's free reads and downloads: used, bought, and when they start again."}, "top_up": {"type": "string", "description": "Only when the balance is empty: how to top up."}, "minimum_usd": {"type": "integer", "description": "Only when the balance is empty: the smallest top-up."}, "fee": {"type": "string", "description": "Only when the balance is empty: the fee on a top-up."}, "first_topup_offer": {"type": ["string", "null"], "description": "Only when the balance is empty: the first top-up's bonus."}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}}, "/v1/topups": {"get": {"operationId": "list_topups", "summary": "List the credit added", "description": "The newest 100 top-ups, bonuses, auto-reloads and free credit. A top-up says until when it can be refunded (the account_refund_topup tool).", "responses": {"200": {"description": "The credit added.", "content": {"application/json": {"schema": {"type": "object", "properties": {"credits": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "integer"}, "kind": {"type": "string", "enum": ["topup", "bonus", "auto_reload", "free_credit"]}, "amount_usd": {"type": "string"}, "at": {"type": "string"}, "note": {"type": ["string", "null"]}, "refundable_until": {"type": ["string", "null"], "description": "Top-ups only."}}}}, "refunds": {"type": "string"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}, "post": {"operationId": "top_up", "summary": "Top up the balance", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["amount_usd"], "properties": {"amount_usd": {"type": "number", "minimum": 5, "maximum": 5000, "description": "Whole cents."}, "po_number": {"type": "string", "maxLength": 40, "description": "A purchase order number, printed on the receipt."}}}}}}, "responses": {"201": {"description": "A Stripe checkout link to pay once.", "content": {"application/json": {"schema": {"type": "object", "properties": {"checkout_url": {"type": "string"}, "amount_usd": {"type": "string"}, "fee_usd": {"type": "string"}, "total_usd": {"type": "string"}, "first_topup_bonus_usd": {"type": "string"}, "credited_usd": {"type": "string"}, "po_number": {"type": "string", "description": "When one was given."}, "how": {"type": "string"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}}, "/v1/auto-reload": {"get": {"operationId": "get_auto_reload", "summary": "Check auto-reload", "responses": {"200": {"description": "Whether auto-reload is on, and its amount.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["off", "pending", "active", "failed"]}, "amount_usd": {"type": "string"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}, "post": {"operationId": "set_auto_reload", "summary": "Turn auto-reload on, or change its amount", "description": "Off: 201 with a Stripe checkout link to pay once; after that the card is charged each time the bots use the amount, plus the top-up fee. On: the new amount, 200. A scoped key can't (403 key_scope).", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"amount_usd": {"type": "number", "minimum": 5, "maximum": 5000, "description": "Whole cents; the amount set before when left out."}}}}}}, "responses": {"200": {"description": "It was on: the new amount.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["off", "pending", "active", "failed"]}, "amount_usd": {"type": "string"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}, "201": {"description": "Pay once through the link to turn it on.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string"}, "checkout_url": {"type": "string"}, "amount_usd": {"type": "string"}, "how": {"type": "string"}}}}}}}}, "delete": {"operationId": "stop_auto_reload", "summary": "Turn auto-reload off", "description": "A scoped key can't (403 key_scope).", "responses": {"200": {"description": "Off.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}}, "/v1/limits": {"get": {"operationId": "get_limits", "summary": "Check the limits", "responses": {"200": {"description": "This key's daily budget and the account's monthly ceiling.", "content": {"application/json": {"schema": {"type": "object", "properties": {"daily_budget_usd": {"type": "string"}, "monthly_ceiling_usd": {"type": "string"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}, "patch": {"operationId": "set_limits", "summary": "Lower the limits", "description": "Lowers this key's daily budget or the account's monthly ceiling, at any time. Raising them is the owner's when the account has an owner email (403 owner_required), and a scoped key changes neither (403 key_scope).", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"daily_budget_usd": {"type": "number", "minimum": 0, "maximum": 1000000}, "monthly_ceiling_usd": {"type": "number", "minimum": 0, "maximum": 1000000}}}}}}, "responses": {"200": {"description": "The limits now.", "content": {"application/json": {"schema": {"type": "object", "properties": {"daily_budget_usd": {"type": "string"}, "monthly_ceiling_usd": {"type": "string"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}}, "/v1/keys": {"get": {"operationId": "list_keys", "summary": "List the keys", "responses": {"200": {"description": "The account's keys that work; current is the one calling.", "content": {"application/json": {"schema": {"type": "object", "properties": {"keys": {"type": "array", "items": {"type": "object", "properties": {"key_id": {"type": "integer"}, "bot_name": {"type": "string"}, "runtime": {"type": "string"}, "last4": {"type": "string"}, "daily_budget_usd": {"type": "string"}, "current": {"type": "boolean"}, "scope": {"type": "object", "properties": {"areas": {"type": ["array", "null"], "items": {"type": "string"}}, "tools": {"type": ["array", "null"], "items": {"type": "string"}}, "deny_tools": {"type": ["array", "null"], "items": {"type": "string"}}, "read_only": {"type": "boolean"}, "drafts_only": {"type": "boolean"}, "expires_at": {"type": ["string", "null"]}, "networks": {"type": ["array", "null"], "items": {"type": "string"}}, "team": {"type": ["string", "null"]}, "accountable": {"type": ["string", "null"]}}, "description": "What the key may do; null is no limit. A person's own assistant has person and teams in place of team."}, "last_used_at": {"type": ["string", "null"]}}}}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}, "post": {"operationId": "make_key", "summary": "Make a key", "description": "A key for another bot or job, within this key's scope and team. It shares the daily budget of the first key in its line; an account has at most 25 keys.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["bot_name"], "properties": {"bot_name": {"type": "string", "minLength": 1, "maxLength": 80}, "runtime": {"type": "string"}, "daily_budget_usd": {"type": "number", "minimum": 0, "maximum": 1000000, "description": "With an owner email, at most this key's."}, "areas": {"type": "array", "maxItems": 200, "items": {"type": "string"}, "description": "The areas it works in."}, "tools": {"type": "array", "maxItems": 200, "items": {"type": "string"}, "description": "The only tools it may run."}, "deny_tools": {"type": "array", "maxItems": 200, "items": {"type": "string"}, "description": "Tools it may not run."}, "read_only": {"type": "boolean"}, "drafts_only": {"type": "boolean", "description": "Every change it makes waits for a person."}, "expires_in_days": {"type": "integer", "minimum": 1, "maximum": 366}, "expires_at": {"type": "string", "format": "date-time", "description": "In place of expires_in_days."}, "networks": {"type": "array", "maxItems": 20, "items": {"type": "string"}, "minItems": 1, "description": "Where it may be used from, like 203.0.113.0/24."}, "team": {"type": "string", "description": "Another team than this key's: only a key of the company-wide team without limits names one, and a new name makes it."}, "accountable": {"type": "string", "maxLength": 200, "description": "The person who answers for it."}}}}}}, "responses": {"201": {"description": "The new key (shown once) and its scope.", "content": {"application/json": {"schema": {"type": "object", "properties": {"key_id": {"type": "integer"}, "key": {"type": "string"}, "key_note": {"type": "string"}, "daily_budget_usd": {"type": "string"}, "scope": {"type": "object", "properties": {"areas": {"type": ["array", "null"], "items": {"type": "string"}}, "tools": {"type": ["array", "null"], "items": {"type": "string"}}, "deny_tools": {"type": ["array", "null"], "items": {"type": "string"}}, "read_only": {"type": "boolean"}, "drafts_only": {"type": "boolean"}, "expires_at": {"type": ["string", "null"]}, "networks": {"type": ["array", "null"], "items": {"type": "string"}}, "team": {"type": ["string", "null"]}, "accountable": {"type": ["string", "null"]}}, "description": "What the key may do; null is no limit. A person's own assistant has person and teams in place of team."}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}}, "/v1/keys/{key_id}": {"delete": {"operationId": "revoke_key", "summary": "Revoke a key", "description": "A key revokes itself and the keys made from it, and the first key of a line any key of that line.", "parameters": [{"name": "key_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Revoked.", "content": {"application/json": {"schema": {"type": "object", "properties": {"revoked": {"type": "integer"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}}, "/v1/calls": {"get": {"operationId": "list_calls", "summary": "List recent calls", "description": "Newest first. A scoped key sees only its own calls.", "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, {"name": "status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["reserved", "running", "succeeded", "failed"]}}], "responses": {"200": {"description": "The calls.", "content": {"application/json": {"schema": {"type": "object", "properties": {"calls": {"type": "array", "items": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "area": {"type": "string"}, "status": {"type": "string", "enum": ["reserved", "running", "succeeded", "failed"]}, "cost_usd": {"type": "string"}, "error": {"type": ["string", "null"]}, "message": {"type": ["string", "null"]}, "latency_ms": {"type": ["integer", "null"]}, "at": {"type": "string"}, "bot": {"type": ["string", "null"]}, "person": {"type": ["string", "null"]}}}}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}}, "/v1/calls/{call_id}": {"get": {"operationId": "get_call", "summary": "Get a call (poll background calls)", "parameters": [{"name": "call_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "The call, its status and cost, with what it was given and answered (until its contents are cleared after 30 days).", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "area": {"type": "string"}, "status": {"type": "string", "enum": ["reserved", "running", "succeeded", "failed"]}, "cost_usd": {"type": "string"}, "error": {"type": ["string", "null"]}, "message": {"type": ["string", "null"]}, "latency_ms": {"type": ["integer", "null"]}, "at": {"type": "string"}, "bot": {"type": ["string", "null"]}, "person": {"type": ["string", "null"]}, "input": {"type": ["object", "null"]}, "output": {"type": ["object", "null"]}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}}}, "/v1/tools/account_balance": {"post": {"operationId": "account_balance", "summary": "Check balance", "description": "The account balance, what running calls are holding, this key's daily budget, the auto-reload state, and how much of this month's free reads and downloads is used. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_get_call": {"post": {"operationId": "account_get_call", "summary": "Get a call", "description": "One call by id: its status (queued, running, succeeded, failed), cost and result. Use it to poll a background call until it finishes. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string", "minLength": 36, "maxLength": 36}}, "required": ["call_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_list_calls": {"post": {"operationId": "account_list_calls", "summary": "List calls", "description": "Recent calls on this account, newest first, optionally only failed or succeeded ones, or one area's. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["reserved", "running", "succeeded", "failed"]}, "area": {"type": "string", "enum": ["analytics", "code", "crm", "calendar", "chat", "account", "admin", "email", "helpdesk", "documents", "esign", "hiring", "outreach", "prospects", "lookups", "newsletters", "notify", "projects", "schedules", "speech", "uptime", "vault", "web", "tables", "links", "images", "files", "forms", "helpcenter", "imports", "invoices", "books", "inventory", "whistleblowing", "connect", "microsoft365", "googleworkspace", "hubspot", "salesforce", "directory", "hr", "social", "purchasing", "phone", "websites", "views", "visibility"]}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_refund_topup": {"post": {"operationId": "account_refund_topup", "summary": "Refund a top-up", "description": "Refund a top-up paid in the last 24 hours that none of has been used yet: its credit, with the first top-up's bonus, leaves the balance, and the card gets the credit back with its tax. The service fee is kept. Without topup_id, the newest top-up (GET /v1/topups lists them with their ids). Free. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"topup_id": {"type": "integer", "minimum": 1}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_set_owner_email": {"post": {"operationId": "account_set_owner_email", "summary": "Name the business's owner", "description": "When the account was made without the owner's email: send that person a link to confirm they own it. Once they confirm, the owner gets the account's warnings and approval requests, and only the owner raises limits. Nothing changes until they open the link. Free. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "minLength": 3, "maxLength": 254}}, "required": ["email"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_owner_link": {"post": {"operationId": "account_owner_link", "summary": "Get a sign-in link for the owner", "description": "A link that signs the business owner into their Conecto page, with no password: the balance, adding credit, auto-reload, limits, what the bots did, people, rentals and keys. page opens it where the owner is needed, like people for a role only the owner gives, or settings for joining by email domain. It works once, within 30 minutes; hand it to the owner. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"page": {"type": "string", "enum": ["home", "tools", "activity", "apps", "billing", "add_credit", "limits", "people", "settings"], "default": "home"}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_dashboard_link": {"post": {"operationId": "account_dashboard_link", "summary": "Get a link to an area at a glance", "description": "A one-time link to a page showing one area as it is when the page opens, for when the person you work for asks to see it themselves: a recruiter looks at the applicants, a bookkeeper at what is due. Do the work and answer with the area's own tools first; a link never replaces that. When an answer would be a long list they would rather look through, offer a link and make it once they say yes. The page is made from the area's own reads as this key, so it shows only what this key may see. It opens once and keeps for an hour; an unopened link ends after 7 days. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"area": {"type": "string", "enum": ["analytics", "code", "crm", "calendar", "chat", "account", "admin", "email", "helpdesk", "documents", "esign", "hiring", "outreach", "prospects", "lookups", "newsletters", "notify", "projects", "schedules", "speech", "uptime", "vault", "web", "tables", "links", "images", "files", "forms", "helpcenter", "imports", "invoices", "books", "inventory", "whistleblowing", "connect", "microsoft365", "googleworkspace", "hubspot", "salesforce", "directory", "hr", "social", "purchasing", "phone", "websites", "views", "visibility"]}}, "required": ["area"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_get_limits": {"post": {"operationId": "account_get_limits", "summary": "Read the limits", "description": "The limits a business can ask Conecto to raise (calls a minute, new email addresses a day, phone numbers and more): each one's standard and current value and the most that can be asked for, and the business's requests with their answers. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_request_limit": {"post": {"operationId": "account_request_limit", "summary": "Ask for a higher limit", "description": "Ask Conecto to raise one of the business's limits: which one (or other, saying which), the number it needs, and why, in 40 to 2,000 characters. Conecto reviews it and approves (maybe with less) or declines; the answer comes as the account.limit_request_answered event and by email to the owner, who is also told now. For an account that has topped up; one request per limit at a time, five in 30 days. Free. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"limit": {"type": "string", "enum": ["calls_per_minute", "key_calls_per_minute", "downloads_per_hour", "new_email_recipients_per_day", "documents_emailed_per_day", "orders_emailed_per_day", "phone_numbers", "confirmation_calls_per_day", "connections", "storage_blocks", "prospects_per_month", "outreach_mailboxes", "other"], "description": "The limit, as account_get_limits names it, or other."}, "amount": {"type": "integer", "minimum": 1, "maximum": 1000000000, "description": "The number the business needs, in the limit's unit (5000 calls a minute)."}, "reason": {"type": "string", "minLength": 40, "maxLength": 2000, "description": "What the business does that needs it, and why the current limit is too low."}, "other": {"type": "string", "maxLength": 200, "description": "With limit other: which limit, like \"rows in one table\"."}}, "required": ["limit", "amount", "reason"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_events": {"post": {"operationId": "account_events", "summary": "Read recent events", "description": "What happened in this account that someone outside the bot did, oldest first: applications, bookings, form responses, signatures, replies, emails received, goals reached on the website; and the custom events bots sent with account_emit_event. Kept 30 days. Poll with after = the last event_id you saw. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"after": {"type": "integer", "minimum": 0, "description": "Only events after this event_id."}, "kinds": {"type": "array", "maxItems": 30, "items": {"type": "string"}, "description": "Event names or areas (\"hiring.*\"); all when left out."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_emit_event": {"post": {"operationId": "account_emit_event", "summary": "Send an event of your own", "description": "Send an event you name, custom.<name> (custom.lead_qualified, custom.order_shipped), to every channel subscribed to it (notify_subscribe with \"custom.*\" or its name: Slack, Teams, a webhook to Zapier, Make, n8n or the business's own systems) and to account_events, where another team's bot can pick it up. data is any JSON object (up to 10 KB); sent_by is added with this bot's name and team. $0.005 for each channel it goes to; free when no channel is subscribed. Costs $0.005 per channel it goes to; nothing if none are found.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"kind": {"type": "string", "minLength": 8, "maxLength": 66, "pattern": "^custom\\.[a-z0-9][a-z0-9_.-]*$", "description": "custom. and a name of lowercase letters, digits, dots, dashes and _."}, "title": {"type": "string", "minLength": 1, "maxLength": 200}, "text": {"type": "string", "maxLength": 4000}, "data": {"type": "object"}, "link": {"type": "string", "maxLength": 1000, "pattern": "^https://"}}, "required": ["kind", "title"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_search": {"post": {"operationId": "account_search", "summary": "Search everything", "description": "One search over what this account holds: what its files say (PDFs, Word, Excel, PowerPoint, text), table rows, help center articles, CRM contacts, companies and deals, emails, tickets, quotes and invoices, book entries, stock items and project tasks. Every word must appear (any case); titles rank first, then the newest. Each result says which tool opens it. Narrow it with areas. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "minLength": 2, "maxLength": 200}, "areas": {"type": "array", "minItems": 1, "items": {"type": "string", "enum": ["files", "tables", "helpcenter", "crm", "email", "helpdesk", "invoices", "books", "inventory", "projects"]}}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}, "required": ["query"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_get_brand": {"post": {"operationId": "account_get_brand", "summary": "See the business's look", "description": "The name, logo, colour and footer line the business's emails and published pages carry. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_set_brand": {"post": {"operationId": "account_set_brand", "summary": "Set the business's look", "description": "The business's name as the sender, its logo (a PNG, JPEG, WebP or GIF from the file store), its colour and a footer line (an address, a legal line), on every email to its customers (bookings, applications, tests, signatures, invoices, newsletters, replies) and on its published pages (forms, booking, careers, newsletters, status, views). Only what you pass changes; an empty string clears it. Mail from Conecto to you keeps Conecto's look. Costs $0.001 per call; nothing if it fails.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"sender_name": {"type": "string", "maxLength": 120}, "logo_file_id": {"type": "string", "minLength": 36, "maxLength": 36}, "remove_logo": {"type": "boolean", "default": false}, "colour": {"type": "string", "maxLength": 7, "description": "Hex, like #1a73e8; empty for none."}, "footer": {"type": "string", "maxLength": 200}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_list_email_templates": {"post": {"operationId": "account_list_email_templates", "summary": "See what the business's emails say", "description": "Every email Conecto sends to the business's customers (bookings, applications, interviews, tests, signatures, invoices and quotes, newsletter sign-ups), with when it goes out and its subject, headline and opening words as they are now, and the {variables} each can use. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_set_email_template": {"post": {"operationId": "account_set_email_template", "summary": "Rewrite one of the business's emails", "description": "Change an email's subject, headline or opening words in the business's own voice, with {variables} from account_list_email_templates (like {name} or {when}). The facts under them (times, places, amounts, links and buttons) stay as they are. Only what you pass changes; an empty string brings back the original words. Plain text; a blank line starts a new paragraph. Costs $0.001 per call; nothing if it fails.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "maxLength": 40, "description": "Like booking_booked or invoice_sent."}, "subject": {"type": "string", "maxLength": 200}, "headline": {"type": "string", "maxLength": 120}, "opening": {"type": "string", "maxLength": 4000}}, "required": ["email"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_export_all": {"post": {"operationId": "account_export_all", "summary": "Export everything", "description": "Everything this account holds, in ZIP files of up to 24 MB saved to its file store: every record of every area as JSON Lines, and the stored files themselves, with a README saying what is where. Credentials are left out. Runs in the background: poll the call with account_get_call; the result has a download link for each part. Free (EU Data Act). One at a time, three a day; the owner is emailed when an export is made. Free. Runs in the background: the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}, "202": {"description": "Started; poll /v1/calls/{call_id}.", "content": {"application/json": {"schema": {"type": "object"}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_audit_log": {"post": {"operationId": "account_audit_log", "summary": "Read the audit log", "description": "The account's admin and security actions, newest first: keys made and revoked, limits and auto-reload, the owner's sign-ins, connectors, exports, vault reads and writes, credentials set and everything deleted. Ordinary work is in the call log (account_list_calls). verify: true also checks the hash chain, which breaks where an entry was changed or removed. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"action": {"type": "string", "maxLength": 60, "description": "Only actions starting with this, like \"key.\" or \"tool.vault_\"."}, "since": {"type": "string", "format": "date-time", "maxLength": 40}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50}, "verify": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_save_team": {"post": {"operationId": "account_save_team", "summary": "Create or change a team", "description": "A department, location or project group of the account, like Support, Finance or the Hamburg shop. Its keys (POST /v1/keys with \"team\") can only work in its areas, only read when read_only is on, and spend against its budget (monthly_budget_usd per budget_period: a month, a fiscal quarter or year, or a project total): a hard budget refuses the call that would pass it, a soft one only warns. At alert_percent you get the event account.budget_alert and the owner an email, once a period. erp_code is the team's cost center in the company's ERP, for statements. drafts_only makes every write of its keys wait for one of its managers (or the owner), for a new bot that should only draft. mailboxes are the Microsoft 365 or Google mailboxes its keys may act as. You may make a team and narrow one; widening its areas, letting it write, ending drafts only, switching a hard budget to soft, and raising or removing a budget are the owner's, on their account page, when the account has an owner email. The company-wide team holds every key no other team does and is never limited to areas. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80}, "new_name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "Renames the team; its keys, spend and budget stay with it."}, "areas": {"type": ["array", "null"], "items": {"type": "string"}, "maxItems": 50, "description": "The areas its keys may work in (account tools always); null for every area."}, "read_only": {"type": "boolean"}, "monthly_budget_usd": {"type": ["number", "null"], "minimum": 0, "maximum": 1000000, "description": "null counts the spend without a cap."}, "budget": {"type": "string", "enum": ["hard", "soft"], "description": "hard refuses calls past the budget; soft only warns."}, "alert_percent": {"type": "integer", "minimum": 1, "maximum": 100}, "erp_code": {"type": ["string", "null"], "maxLength": 40}, "drafts_only": {"type": "boolean", "description": "Every write of its keys waits for a person."}, "mailboxes": {"type": ["array", "null"], "maxItems": 20, "items": {"type": "string", "maxLength": 254}, "description": "The Microsoft 365 or Google mailboxes its keys may act as; null for every mailbox the connection lists."}, "budget_period": {"type": "string", "enum": ["month", "quarter", "year", "project"], "description": "What the budget is for: a month, a quarter or a year of the account's fiscal calendar, or a project total until budget_ends_on."}, "budget_ends_on": {"type": ["string", "null"], "format": "date", "description": "The last day of a project budget, like 2026-12-31."}, "sees_sensitive": {"type": "boolean", "description": "false hides suppliers' bank details and HR notes and contracts from its keys; only the owner turns it on."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_list_teams": {"post": {"operationId": "account_list_teams", "summary": "List teams", "description": "The account's teams, the company-wide one first: each with its areas, whether it only reads, its budget (hard or soft, and its period) and alert line, this period's spend, its ERP code, whether it is paused, its keys, and its people with who manages it. A person's own assistant works within their teams. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_pause_team": {"post": {"operationId": "account_pause_team", "summary": "Pause a team", "description": "Stops every key of a team at once, this one too if it is the team's: their calls are refused until the owner starts the team again on their account page. For a bot that misbehaves or a team that spends too fast. Free. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"team": {"type": "string", "minLength": 1, "maxLength": 80}}, "required": ["team"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_assign_team": {"post": {"operationId": "account_assign_team", "summary": "Give something to a team", "description": "Move a form, a meeting type, a job, an inbox, a phone number, a newsletter, the website chat, a rental, a pipeline, a table or a website to a team. What happens through it is charged to that team from now on (a form's responses, a number's calls, an inbox's tickets), and its rental moves with it. Something a bot makes already belongs to the bot's team. Only a key of the company-wide team without limits moves things between teams. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["form", "meeting_type", "job", "inbox", "phone_number", "newsletter", "chat", "rental", "pipeline", "table", "website"]}, "id": {"type": "string", "maxLength": 254, "description": "Its id, slug, name, address or number; not needed for the chat."}, "team": {"type": "string", "minLength": 1, "maxLength": 80}}, "required": ["kind", "team"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_add_approval_rule": {"post": {"operationId": "account_add_approval_rule", "summary": "Hold a tool for approval", "description": "Make a tool wait for a person: every call of it, those whose argument is over a number (like invoices_create_credit_note when amount is over 500), or those whose argument is one of some values (like connect_call when method is POST, PUT, PATCH or DELETE). A held call answers approval_required with an approval_id and asks the approver; when they approve, call again with the same arguments and the approval (header X-Conecto-Approval, or _meta.approvalId over MCP), once. The approver is an email, a saved channel, or a team (its managers, or everyone in it); each approver gets a link of their own, and the person whose call it is never approves it. With two_people_over, calls whose argument is over it need two people. Bills like Xero's bill approval: purchasing_create_bill with argument total holds bills over an amount, tax included; a rule on purchasing_pay_bill also holds batches with such a payment. Removing a rule is the owner's, on their account page, when the account has an owner email. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"tool": {"type": "string", "minLength": 1, "maxLength": 80}, "argument": {"type": "string", "maxLength": 60, "description": "An argument of the tool (or total, for purchasing_create_bill)."}, "over": {"type": "number", "description": "Calls with argument over this are held."}, "values": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 60}, "description": "Calls with argument equal to one of these (any case) are held."}, "approver_email": {"type": "string", "maxLength": 254}, "approver_channel": {"type": "string", "maxLength": 80, "description": "A saved notify channel."}, "approver_team": {"type": "string", "maxLength": 80, "description": "A team (account_list_teams)."}, "approvers": {"type": "string", "enum": ["managers", "everyone"], "default": "managers", "description": "Who in approver_team approves."}, "two_people_over": {"type": "number", "description": "Calls whose argument is over this need two people; higher than over."}}, "required": ["tool"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_list_approval_rules": {"post": {"operationId": "account_list_approval_rules", "summary": "List approval rules", "description": "The tools that wait for a person's approval, with their thresholds and approvers. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_find_person": {"post": {"operationId": "account_find_person", "summary": "Find a person's data", "description": "Every record this account holds about one person, by their email address or phone number, across every area: CRM, chats, emails, tickets, forms, bookings, calls, applications, invoices, orders, newsletters, HR and the call log, with their chats and CRM history. For a person who asks what the business keeps about them (GDPR Art. 15). Shows each kind with its count and ids; account_export_person gives them a copy, account_erase_person erases what may go. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "maxLength": 254, "description": "The person's email address."}, "phone": {"type": "string", "maxLength": 40, "description": "Their phone number in international format, like +1 503 555 0145."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_export_person": {"post": {"operationId": "account_export_person", "summary": "Export a person's data", "description": "Everything account_find_person finds about one person in one ZIP in the file store: their records as JSON Lines (credentials left out) and the files those records point to, like a CV. Give the person the download link when they ask for a copy of their data (GDPR Art. 15 and 20), once you know it is them. Free; 20 a day. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "maxLength": 254, "description": "The person's email address."}, "phone": {"type": "string", "maxLength": 40, "description": "Their phone number in international format, like +1 503 555 0145."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_erase_person": {"post": {"operationId": "account_erase_person", "summary": "Erase a person's data", "description": "Erases one person across every area when they ask (GDPR Art. 17), once you know it is them (they wrote from that address, or confirmed it). Their CRM contact, chat visitor, past meetings and calls are anonymised, so deals stay without them, and a meeting they were only a guest at drops them; their chats, CRM history, form and routing form answers, job applications with the CV, newsletter subscriptions and events are deleted, and the call log's contents that name them are cleared. Kept, each with its reason in the result: accounting records, employment records, signed documents, the audit log, the account's own settings, upcoming meetings, and emails and tickets (outreach emails and replies too) unless correspondence is true. Their address goes on the suppression lists, so it is never mailed again: outreach campaigns stop for them at once. Can't be undone; the owner is emailed. Free. Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "maxLength": 254, "description": "The person's email address."}, "phone": {"type": "string", "maxLength": 40, "description": "Their phone number in international format, like +1 503 555 0145."}, "correspondence": {"type": "boolean", "default": false, "description": "Also delete their emails and tickets, when no law requires keeping them."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/account_data_locations": {"post": {"operationId": "account_data_locations", "summary": "See where the data is", "description": "Where each area's data is stored and processed: the company that runs each place, the country or region, and what it holds. Every area keeps its records in the database and runs on Conecto's servers; some also use a service named here (email, phone, PDFs, search). For the business's records of processing and its transfer assessments (GDPR Art. 30 and 44). Free.", "tags": ["account"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"areas": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 40}, "description": "Areas to show, like [\"email\", \"phone\"]; all when left out."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_connect": {"post": {"operationId": "m365_connect", "summary": "Connect Microsoft 365", "description": "Connect the company's own Microsoft 365 so the agent works in its Outlook mail, calendars and OneDrive files, which stay the source of truth. The company registers an app in Microsoft Entra ID with the application permissions Mail.ReadWrite, Mail.Send, Calendars.ReadWrite and Files.ReadWrite.All, and its admin consents. Give its tenant_id, client_id and client secret, and the mailboxes the agent may act as (it never acts as anyone else). Each mailbox is checked before anything is kept. On accounts with an owner, cancelling events and replacing files wait for the owner's approval by default. Free. Free.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"tenant_id": {"type": "string", "minLength": 3, "maxLength": 120}, "client_id": {"type": "string", "minLength": 3, "maxLength": 120}, "secret": {"type": "string", "minLength": 8, "maxLength": 2000, "description": "The app's client secret. Never shown again.", "writeOnly": true}, "mailboxes": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "string", "maxLength": 254}, "description": "The addresses the agent may act as, like support@ and sales@."}}, "required": ["tenant_id", "client_id", "secret", "mailboxes"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_disconnect": {"post": {"operationId": "m365_disconnect", "summary": "Disconnect Microsoft 365", "description": "Forget the app's secret and the mailboxes. Nothing in Microsoft 365 changes. Free.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_mail_search": {"post": {"operationId": "m365_mail_search", "summary": "Search Outlook mail", "description": "The newest messages in a mailbox folder (inbox by default), or those matching a search: sender, subject, a preview and whether they are read. Free. Free.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "query": {"type": "string", "maxLength": 200}, "folder": {"type": "string", "enum": ["inbox", "sentitems", "drafts", "archive", "deleteditems", "junkemail"], "default": "inbox"}, "unread_only": {"type": "boolean", "default": false}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_mail_read": {"post": {"operationId": "m365_mail_read", "summary": "Read an Outlook message", "description": "One message in full: sender, recipients, the body as text and its attachments' names. Free. Free.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "message_id": {"type": "string", "minLength": 1, "maxLength": 400}}, "required": ["message_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_mail_send": {"post": {"operationId": "m365_mail_send", "summary": "Send Outlook mail", "description": "Send an email as one of the company's mailboxes, saved in its Sent Items: to, cc, subject and a text body. With reply_to_message_id it replies to that message's sender in the same thread instead. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "to": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 254}}, "cc": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 254}}, "subject": {"type": "string", "maxLength": 300}, "body": {"type": "string", "minLength": 1, "maxLength": 50000}, "reply_to_message_id": {"type": "string", "maxLength": 400}}, "required": ["body"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_calendar_events": {"post": {"operationId": "m365_calendar_events", "summary": "Read an Outlook calendar", "description": "The events in a mailbox's calendar between start and end (at most 62 days), in UTC: subject, time, place, organizer, attendees and the Teams link. Free. Free.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "start": {"type": "string", "maxLength": 40}, "end": {"type": "string", "maxLength": 40}, "timezone": {"type": "string", "maxLength": 60, "description": "For start and end without an offset."}}, "required": ["start", "end"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_calendar_create": {"post": {"operationId": "m365_calendar_create", "summary": "Add an Outlook event", "description": "Put an event in a mailbox's calendar and invite its attendees, with a Teams meeting when asked. Times with an offset, or local to `timezone`. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "subject": {"type": "string", "minLength": 1, "maxLength": 255}, "start": {"type": "string", "maxLength": 40}, "end": {"type": "string", "maxLength": 40}, "timezone": {"type": "string", "maxLength": 60}, "attendees": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 254}}, "location": {"type": "string", "maxLength": 255}, "body": {"type": "string", "maxLength": 10000}, "online_meeting": {"type": "boolean", "default": false}}, "required": ["subject", "start", "end"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_calendar_cancel": {"post": {"operationId": "m365_calendar_cancel", "summary": "Cancel an Outlook event", "description": "Cancel an event the mailbox organizes and tell its attendees, with an optional note. On accounts with an owner it waits for the owner's approval by default. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "event_id": {"type": "string", "minLength": 1, "maxLength": 400}, "comment": {"type": "string", "maxLength": 2000}}, "required": ["event_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_files_search": {"post": {"operationId": "m365_files_search", "summary": "Search OneDrive files", "description": "Files in a mailbox user's OneDrive whose name or words match: name, size, kind, when changed and its link. Free. Free.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "query": {"type": "string", "minLength": 1, "maxLength": 200}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}, "required": ["query"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_files_read": {"post": {"operationId": "m365_files_read", "summary": "Read a OneDrive file", "description": "A file's words, up to 5 MB: text, PDF, Word, Excel and PowerPoint files are read in a separate, capped process. Free. Free.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "file_id": {"type": "string", "minLength": 1, "maxLength": 400}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/m365_files_upload": {"post": {"operationId": "m365_files_upload", "summary": "Write a OneDrive file", "description": "Write a text file (up to 4 MB) to a path in a mailbox user's OneDrive. If the file exists it is kept and the new one renamed, unless if_exists is replace (which waits for the owner's approval by default) or fail. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["microsoft365"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "path": {"type": "string", "minLength": 1, "maxLength": 400}, "content": {"type": "string", "maxLength": 4000000}, "if_exists": {"type": "string", "enum": ["rename", "replace", "fail"], "default": "rename"}}, "required": ["path", "content"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_connect": {"post": {"operationId": "google_connect", "summary": "Connect Google Workspace", "description": "Connect the company's own Google Workspace so the agent works in its Gmail, Google Calendar and Drive, which stay the source of truth. The company makes a service account in Google Cloud, and its Workspace admin gives the account's client ID domain-wide delegation for gmail.modify, calendar and drive. Give the account's JSON key and the mailboxes the agent may act as (it never acts as anyone else). Each mailbox is checked before anything is kept. On accounts with an owner, cancelling events and replacing files wait for the owner's approval by default. Free. Free.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"secret": {"type": "string", "minLength": 50, "maxLength": 10000, "description": "The service account's JSON key. Never shown again.", "writeOnly": true}, "mailboxes": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "string", "maxLength": 254}, "description": "The addresses the agent may act as, like support@ and sales@."}}, "required": ["secret", "mailboxes"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_disconnect": {"post": {"operationId": "google_disconnect", "summary": "Disconnect Google Workspace", "description": "Forget the service account's key and the mailboxes. Nothing in Google Workspace changes. Free.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_mail_search": {"post": {"operationId": "google_mail_search", "summary": "Search Gmail", "description": "The newest messages in a mailbox (the inbox by default), or those matching a Gmail search like \"from:rachel subject:tabor\": sender, subject, a preview and whether they are read. Free. Free.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "query": {"type": "string", "maxLength": 300}, "folder": {"type": "string", "enum": ["inbox", "sent", "drafts", "spam", "trash", "all"], "default": "inbox"}, "unread_only": {"type": "boolean", "default": false}, "limit": {"type": "integer", "minimum": 1, "maximum": 25, "default": 10}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_mail_read": {"post": {"operationId": "google_mail_read", "summary": "Read a Gmail message", "description": "One message in full: sender, recipients, the body as text and its attachments' names. Free. Free.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "message_id": {"type": "string", "minLength": 1, "maxLength": 200}}, "required": ["message_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_mail_send": {"post": {"operationId": "google_mail_send", "summary": "Send Gmail", "description": "Send an email as one of the company's mailboxes: to, cc, subject and a text body. With reply_to_message_id it answers that message in the same thread (to its sender unless `to` says otherwise). $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "to": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 254}}, "cc": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 254}}, "subject": {"type": "string", "maxLength": 300}, "body": {"type": "string", "minLength": 1, "maxLength": 50000}, "reply_to_message_id": {"type": "string", "maxLength": 200}}, "required": ["body"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_calendar_events": {"post": {"operationId": "google_calendar_events", "summary": "Read a Google Calendar", "description": "The events in a mailbox's calendar between start and end (at most 62 days), in UTC: subject, time, place, organizer, attendees and the Meet link. Free. Free.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "start": {"type": "string", "maxLength": 40}, "end": {"type": "string", "maxLength": 40}, "timezone": {"type": "string", "maxLength": 60, "description": "For start and end without an offset."}}, "required": ["start", "end"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_calendar_create": {"post": {"operationId": "google_calendar_create", "summary": "Add a Google Calendar event", "description": "Put an event in a mailbox's calendar and invite its attendees, with a Google Meet link when asked. Times with an offset, or local to `timezone`. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "subject": {"type": "string", "minLength": 1, "maxLength": 255}, "start": {"type": "string", "maxLength": 40}, "end": {"type": "string", "maxLength": 40}, "timezone": {"type": "string", "maxLength": 60}, "attendees": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 254}}, "location": {"type": "string", "maxLength": 255}, "body": {"type": "string", "maxLength": 10000}, "online_meeting": {"type": "boolean", "default": false}}, "required": ["subject", "start", "end"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_calendar_cancel": {"post": {"operationId": "google_calendar_cancel", "summary": "Cancel a Google Calendar event", "description": "Cancel an event in a mailbox's calendar and tell its attendees. On accounts with an owner it waits for the owner's approval by default. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "event_id": {"type": "string", "minLength": 1, "maxLength": 1024}}, "required": ["event_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_drive_search": {"post": {"operationId": "google_drive_search", "summary": "Search Google Drive", "description": "Files in a mailbox user's Drive (shared drives included) whose words match: name, size, kind, when changed and its link. Free. Free.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "query": {"type": "string", "minLength": 1, "maxLength": 200}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}, "required": ["query"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_drive_read": {"post": {"operationId": "google_drive_read", "summary": "Read a Google Drive file", "description": "A file's words, up to 5 MB: Google Docs, Sheets (as CSV) and Slides, text, PDF and Office files; files are read in a separate, capped process. Free. Free.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "file_id": {"type": "string", "minLength": 1, "maxLength": 200}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/google_drive_upload": {"post": {"operationId": "google_drive_upload", "summary": "Write a Google Drive file", "description": "Write a text file (up to 4 MB) into a Drive folder (My Drive when folder_id is left out). If a file with that name exists the new one gets a \" (1)\" name, unless if_exists is replace (which waits for the owner's approval by default) or fail. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["googleworkspace"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox": {"type": "string", "maxLength": 254, "description": "One of the mailboxes the agent may act as; optional when only one is connected."}, "name": {"type": "string", "minLength": 1, "maxLength": 200}, "content": {"type": "string", "maxLength": 4000000}, "folder_id": {"type": "string", "maxLength": 200}, "if_exists": {"type": "string", "enum": ["rename", "replace", "fail"], "default": "rename"}}, "required": ["name", "content"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_add_site": {"post": {"operationId": "analytics_add_site", "summary": "Count a website's visits", "description": "Start counting visits to a website, like Plausible or Umami: add the returned snippet to every page, before </head>. It uses no cookies and keeps no IP addresses. When a visitor becomes a contact through Conecto's chat, a booking, a form or a newsletter signup, the visit that brought them is kept with their contact. Custom events: conecto(\"Signup\", {\"plan\": \"pro\"}) in the page, with revenue as a third argument ({revenue: 49.9, currency: \"USD\"}), or define them without touching the site (analytics_define_events). It also counts on its own clicks on links to other sites, phone and email links, file downloads, form submissions, searches on the site, pages that answer an error, elements with data-conecto-event=\"Name\", and Conecto's own chats, bookings, forms and signups that start on the site; and keeps clicks and scrolling for heatmaps and the pages' Core Web Vitals. analytics_install has the steps for Shopify, WordPress and others. $3 a month with 100,000 events, renewed from the balance; the first month is this call. Costs $3.00 per call; nothing if it fails.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site, e.g. halversoncycle.example (www. and other subdomains count too)."}, "name": {"type": "string", "maxLength": 120}, "time_zone": {"type": "string", "maxLength": 64, "description": "The days of the stats; the business calendar's time zone if left out."}}, "required": ["domain"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_list_sites": {"post": {"operationId": "analytics_list_sites", "summary": "List counted sites", "description": "Every site this account counts, with this month's events and its snippet. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_stats": {"post": {"operationId": "analytics_stats", "summary": "Read a site's stats", "description": "Visitors (counted per day), pageviews, visits, bounce rate, visit length, time on page and scroll depth, against the period before; by day (or by hour for one day); top, entry and exit pages; channels (search, social, AI assistants, email, paid...), sources, referrers and UTM campaigns; countries, devices, browsers, operating systems; custom events; goals with conversion rates and revenue; and Core Web Vitals. A visit keeps the source it came from on every page. filters narrow all of it. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "period": {"type": "string", "enum": ["today", "yesterday", "7d", "30d", "90d", "month", "last_month", "12mo", "custom"], "default": "30d"}, "from": {"type": "string", "maxLength": 10, "description": "With period custom: the first day, 2026-10-01."}, "to": {"type": "string", "maxLength": 10, "description": "With period custom: the last day."}, "filters": {"type": "object", "description": "Narrow the stats: page and entry_page (\"/blog/*\", * for any part), goal (a goal's name), event, channel (Direct, Organic search, Paid search, Organic social, Paid social, AI assistants, Email, Referral, Affiliates, Display, Paid other, Other campaigns), source (\"Google\", \"Direct\"), referrer, campaign, medium, term, content, country (\"DE\"), device (desktop, tablet, mobile), browser, os. Example: {\"channel\": \"Organic search\", \"device\": \"mobile\"}.", "additionalProperties": {"type": "string", "maxLength": 500}}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 10}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_set_goals": {"post": {"operationId": "analytics_set_goals", "summary": "Set a site's goals", "description": "The conversions to count, replacing the site's goals: a page reached ({\"name\": \"Order placed\", \"page\": \"/checkout/done\"}) or a custom event, optionally with props ({\"name\": \"Pro signup\", \"event\": \"Signup\", \"props\": {\"plan\": \"pro\"}}). analytics_stats then shows each goal's visitors, conversions, conversion rate and revenue (from conecto(\"Purchase\", {...}, {revenue: 49.9, currency: \"USD\"})). An empty list removes them. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "goals": {"type": "array", "maxItems": 20, "items": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 60}, "page": {"type": "string", "maxLength": 500, "description": "A page reached, like /thanks or /order/*/done."}, "event": {"type": "string", "maxLength": 60, "description": "A custom event, like Signup, or one analytics_define_events made."}, "props": {"type": "object", "description": "Only events with these props, like {\"plan\": \"pro\"}."}, "notify": {"type": "boolean", "description": "Send analytics.goal_completed the moment a visitor reaches it, with where they came from and what they saw."}}}}}, "required": ["site", "goals"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_define_events": {"post": {"operationId": "analytics_define_events", "summary": "Define events without touching the site", "description": "The events to count from what the script already sees, replacing the site's defined events: a click (on an element by its words, or by its path from analytics_heatmap), a page reached, a page scrolled past a share, time spent on a page, or an event the site sends narrowed by its props (a link out to calendly.com is {\"event\": \"Outbound link\", \"props\": {\"url\": \"https://calendly.com/*\"}}). Nobody edits the site. Page, scroll, time and event rules count backwards over the stored months too; clicks count from now on. A defined event works wherever an event does: analytics_stats, goals, funnels, filters and analytics_breakdown. An empty list removes them. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "events": {"type": "array", "maxItems": 50, "items": {"type": "object", "required": ["name", "kind"], "properties": {"name": {"type": "string", "maxLength": 60}, "kind": {"type": "string", "enum": ["click", "page", "scroll", "time", "event"], "description": "click: someone clicked an element; page: a page was reached; scroll: a page was scrolled past percent; time: someone spent seconds on a page; event: an event the site already sends, narrowed by its props."}, "text": {"type": "string", "maxLength": 60, "description": "click: the element's words, like \"Book a demo\"."}, "contains": {"type": "boolean", "description": "click: the words appear anywhere in the element's label."}, "element": {"type": "string", "maxLength": 300, "description": "click: the element's path as analytics_heatmap shows it."}, "page": {"type": "string", "maxLength": 500, "description": "The page, like /pricing (* for any part); for click and event, only on these pages."}, "percent": {"type": "integer", "minimum": 10, "maximum": 100, "description": "scroll: how far down."}, "seconds": {"type": "integer", "minimum": 5, "maximum": 3600, "description": "time: seconds on the page."}, "event": {"type": "string", "maxLength": 60, "description": "event: the event the site sends, like \"Outbound link\"."}, "props": {"type": "object", "description": "event: its props, * for any part, like {\"url\": \"https://calendly.com/*\"}."}}}}}, "required": ["site", "events"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_track": {"post": {"operationId": "analytics_track", "summary": "Track events from outside the site", "description": "Record what happened away from the site's pages: a Shopify order, a deal won, a call that booked a demo, a renewal. Up to 100 at once, each with props and revenue. An event joins the visit that led to it when you give the visitor's IP address and user agent (a Shopify order carries both; they find the visit and are never kept), or the email or contact of a person whose first visit Conecto kept; otherwise it counts without a source. Then analytics_breakdown shows which channels and campaigns bring the money. Don't track what the site itself already sends, or it counts twice. Free; each event counts toward the site's monthly events. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "events": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string", "maxLength": 60}, "props": {"type": "object", "description": "Up to 10 plain values, like {\"plan\": \"pro\"}."}, "revenue": {"type": ["number", "string"], "description": "The money it brought, like 129.90."}, "currency": {"type": "string", "minLength": 3, "maxLength": 3}, "at": {"type": "string", "maxLength": 40, "description": "When it happened, with its offset; now if left out."}, "visitor": {"type": "object", "description": "The IP address and user agent the order or form came from, as Shopify and most forms record them: to find the visit that led to it. Used once, never kept.", "properties": {"ip": {"type": "string", "maxLength": 45}, "user_agent": {"type": "string", "maxLength": 500}}}, "email": {"type": "string", "maxLength": 254, "description": "A person whose first visit Conecto kept: the event is credited to it."}, "contact_id": {"type": "integer", "description": "The same, by CRM contact."}, "page": {"type": "string", "maxLength": 500, "description": "Where it happened, like /checkout."}}}}}, "required": ["site", "events"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_breakdown": {"post": {"operationId": "analytics_breakdown", "summary": "Break an event or goal down", "description": "One event or goal by a prop (by: \"prop:plan\") or by where its visits came from: channel, source, referrer, campaign, medium, term, content, landing_page, page, country, device, browser or os. Each row has conversions, visitors, the conversion rate (for where visits came from) and revenue, so you see which channels, campaigns and landing pages bring signups and money, including what analytics_track and Conecto's own bookings, chats and forms counted. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "event": {"type": "string", "maxLength": 60}, "goal": {"type": "string", "maxLength": 60}, "by": {"type": "string", "maxLength": 50, "default": "channel"}, "period": {"type": "string", "enum": ["today", "yesterday", "7d", "30d", "90d", "month", "last_month", "12mo", "custom"], "default": "30d"}, "from": {"type": "string", "maxLength": 10, "description": "With period custom: the first day, 2026-10-01."}, "to": {"type": "string", "maxLength": 10, "description": "With period custom: the last day."}, "filters": {"type": "object", "description": "Narrow the stats: page and entry_page (\"/blog/*\", * for any part), goal (a goal's name), event, channel (Direct, Organic search, Paid search, Organic social, Paid social, AI assistants, Email, Referral, Affiliates, Display, Paid other, Other campaigns), source (\"Google\", \"Direct\"), referrer, campaign, medium, term, content, country (\"DE\"), device (desktop, tablet, mobile), browser, os. Example: {\"channel\": \"Organic search\", \"device\": \"mobile\"}.", "additionalProperties": {"type": "string", "maxLength": 500}}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_problems": {"post": {"operationId": "analytics_problems", "summary": "Find what is broken for visitors", "description": "Pages that answered 404 or another error to real visitors, with the page that links there; JavaScript errors (when the site keeps them: analytics_update_site track_errors); and the elements people rage-click or click with nothing happening, by page. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "period": {"type": "string", "enum": ["today", "yesterday", "7d", "30d", "90d", "month", "last_month", "12mo", "custom"], "default": "7d"}, "from": {"type": "string", "maxLength": 10, "description": "With period custom: the first day, 2026-10-01."}, "to": {"type": "string", "maxLength": 10, "description": "With period custom: the last day."}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 10}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_install": {"post": {"operationId": "analytics_install", "summary": "Get install steps", "description": "How to put the counting script on a site, step by step for where it runs: html (any site), shopify (the theme, plus a custom pixel that counts products viewed, carts, checkouts and purchases with revenue), wordpress, webflow or google_tag_manager. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "platform": {"type": "string", "enum": ["html", "shopify", "wordpress", "webflow", "google_tag_manager"], "default": "html"}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_funnel": {"post": {"operationId": "analytics_funnel", "summary": "See where people drop off", "description": "How many visitors did each step in order (pages and events, 2 to 8), the share kept at each step, how many dropped, and the median time between steps. Steps happen in order on the same day; anything may happen between them. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "steps": {"type": "array", "minItems": 2, "maxItems": 8, "items": {"anyOf": [{"type": "string", "maxLength": 500}, {"type": "object", "properties": {"name": {"type": "string", "maxLength": 60}, "page": {"type": "string", "maxLength": 500, "description": "A page reached, like /thanks or /order/*/done."}, "event": {"type": "string", "maxLength": 60, "description": "A custom event, like Signup, or one analytics_define_events made."}, "props": {"type": "object", "description": "Only events with these props, like {\"plan\": \"pro\"}."}, "notify": {"type": "boolean", "description": "Send analytics.goal_completed the moment a visitor reaches it, with where they came from and what they saw."}}}]}, "description": "Each a page (\"/pricing\", * for any part), an event name (\"Signup\"), or {\"page\"|\"event\", \"props\", \"name\"}."}, "period": {"type": "string", "enum": ["today", "yesterday", "7d", "30d", "90d", "month", "last_month", "12mo", "custom"], "default": "30d"}, "from": {"type": "string", "maxLength": 10, "description": "With period custom: the first day, 2026-10-01."}, "to": {"type": "string", "maxLength": 10, "description": "With period custom: the last day."}, "filters": {"type": "object", "description": "Narrow the stats: page and entry_page (\"/blog/*\", * for any part), goal (a goal's name), event, channel (Direct, Organic search, Paid search, Organic social, Paid social, AI assistants, Email, Referral, Affiliates, Display, Paid other, Other campaigns), source (\"Google\", \"Direct\"), referrer, campaign, medium, term, content, country (\"DE\"), device (desktop, tablet, mobile), browser, os. Example: {\"channel\": \"Organic search\", \"device\": \"mobile\"}.", "additionalProperties": {"type": "string", "maxLength": 500}}}, "required": ["site", "steps"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_paths": {"post": {"operationId": "analytics_paths", "summary": "See where people go", "description": "With a page: where visits went next (or left the site) and where they were before it. Without one: the commonest journeys, the first four pages of visits. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "page": {"type": "string", "maxLength": 500, "description": "Like /pricing; * for any part."}, "period": {"type": "string", "enum": ["today", "yesterday", "7d", "30d", "90d", "month", "last_month", "12mo", "custom"], "default": "30d"}, "from": {"type": "string", "maxLength": 10, "description": "With period custom: the first day, 2026-10-01."}, "to": {"type": "string", "maxLength": 10, "description": "With period custom: the last day."}, "filters": {"type": "object", "description": "Narrow the stats: page and entry_page (\"/blog/*\", * for any part), goal (a goal's name), event, channel (Direct, Organic search, Paid search, Organic social, Paid social, AI assistants, Email, Referral, Affiliates, Display, Paid other, Other campaigns), source (\"Google\", \"Direct\"), referrer, campaign, medium, term, content, country (\"DE\"), device (desktop, tablet, mobile), browser, os. Example: {\"channel\": \"Organic search\", \"device\": \"mobile\"}.", "additionalProperties": {"type": "string", "maxLength": 500}}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 10}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_heatmap": {"post": {"operationId": "analytics_heatmap", "summary": "See where people click and scroll", "description": "A page's heatmap: the most clicked elements with their text, rage clicks (3 fast clicks in one spot) and dead clicks (nothing on the page changed), how far down people scroll and time on page. The link opens the business's own page with the heat drawn over it (clicks, rage, dead, scroll; desktop, tablet or phone); it works for 7 days. The site's script records clicks on its own, without cookies or anything that identifies a visitor. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "page": {"type": "string", "maxLength": 500, "description": "The path, like /pricing."}, "device": {"type": "string", "enum": ["desktop", "tablet", "mobile", "all"], "default": "all"}, "period": {"type": "string", "enum": ["today", "yesterday", "7d", "30d", "90d", "month", "last_month", "12mo", "custom"], "default": "30d"}, "from": {"type": "string", "maxLength": 10, "description": "With period custom: the first day, 2026-10-01."}, "to": {"type": "string", "maxLength": 10, "description": "With period custom: the last day."}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 15}}, "required": ["site", "page"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_web_vitals": {"post": {"operationId": "analytics_web_vitals", "summary": "Check how fast pages are for real visitors", "description": "Core Web Vitals measured in visitors' browsers: LCP, INP, CLS, FCP and TTFB at the 75th percentile, rated good, needs_improvement or poor the way Google does, overall and by device, and the pages with the slowest LCP. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "page": {"type": "string", "maxLength": 500}, "device": {"type": "string", "enum": ["desktop", "tablet", "mobile"]}, "period": {"type": "string", "enum": ["today", "yesterday", "7d", "30d", "90d", "month", "last_month", "12mo", "custom"], "default": "30d"}, "from": {"type": "string", "maxLength": 10, "description": "With period custom: the first day, 2026-10-01."}, "to": {"type": "string", "maxLength": 10, "description": "With period custom: the last day."}, "filters": {"type": "object", "description": "Narrow the stats: page and entry_page (\"/blog/*\", * for any part), goal (a goal's name), event, channel (Direct, Organic search, Paid search, Organic social, Paid social, AI assistants, Email, Referral, Affiliates, Display, Paid other, Other campaigns), source (\"Google\", \"Direct\"), referrer, campaign, medium, term, content, country (\"DE\"), device (desktop, tablet, mobile), browser, os. Example: {\"channel\": \"Organic search\", \"device\": \"mobile\"}.", "additionalProperties": {"type": "string", "maxLength": 500}}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 10}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_view_link": {"post": {"operationId": "analytics_view_link", "summary": "Show someone the stats", "description": "A one-time link to a page with the site's stats for a person to look at: visitors and how they changed, a chart by day, channels, pages (each with its heatmap), sources, countries, devices, goals and speed. The first browser that opens it keeps it for an hour; an unopened link expires after 7 days. Conecto keeps no dashboard: make a link whenever someone should see the numbers (view_show draws anything else). Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "period": {"type": "string", "enum": ["today", "yesterday", "7d", "30d", "90d", "month", "last_month", "12mo", "custom"], "default": "30d"}, "from": {"type": "string", "maxLength": 10, "description": "With period custom: the first day, 2026-10-01."}, "to": {"type": "string", "maxLength": 10, "description": "With period custom: the last day."}, "filters": {"type": "object", "description": "Narrow the stats: page and entry_page (\"/blog/*\", * for any part), goal (a goal's name), event, channel (Direct, Organic search, Paid search, Organic social, Paid social, AI assistants, Email, Referral, Affiliates, Display, Paid other, Other campaigns), source (\"Google\", \"Direct\"), referrer, campaign, medium, term, content, country (\"DE\"), device (desktop, tablet, mobile), browser, os. Example: {\"channel\": \"Organic search\", \"device\": \"mobile\"}.", "additionalProperties": {"type": "string", "maxLength": 500}}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_update_site": {"post": {"operationId": "analytics_update_site", "summary": "Change a site's settings", "description": "Its name, the time zone its days follow, a traffic alert (the analytics.traffic_spike event when this many people are on the site within 5 minutes, at most once in 6 hours; 0 turns it off), a weekly summary (the analytics.weekly_summary event every Monday morning), whether JavaScript errors are kept (track_errors, off by default) and whether where a lead first came from is kept with their contact (keep_sources, on by default). Events reach Slack, Teams, webhooks and the rest through notify_subscribe, and bots through account_events. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "name": {"type": "string", "maxLength": 120}, "time_zone": {"type": "string", "maxLength": 64}, "spike_alert_visitors": {"type": "integer", "minimum": 0, "maximum": 1000000}, "weekly_summary": {"type": "boolean"}, "track_errors": {"type": "boolean"}, "keep_sources": {"type": "boolean"}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_realtime": {"post": {"operationId": "analytics_realtime", "summary": "Who is on a site now", "description": "Visitors in the last 5 minutes, and the pages people looked at in the last 30. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_add_events": {"post": {"operationId": "analytics_add_events", "summary": "Count more events", "description": "Raise a site's monthly allowance by blocks of a million events at $5 a month each, renewed from the balance; this call pays the first month of the new blocks. Above the allowance, events are counted but not stored. Costs $5.00 per block of a million events a month; nothing if none are found.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}, "blocks": {"type": "integer", "minimum": 1, "maximum": 20}}, "required": ["site", "blocks"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/analytics_remove_site": {"post": {"operationId": "analytics_remove_site", "summary": "Stop counting a site", "description": "Stop counting a site, end its rent and delete its stats for good. Free.", "tags": ["analytics"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The site's domain (e.g. halversoncycle.example) or its site_id."}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_setup": {"post": {"operationId": "calendar_setup", "summary": "Set up the calendar", "description": "Set the business's calendar, or a person's own (person: like a Cal.com user, with their own booking page, hours, time zone and Google calendar): its name on booking pages, address, time zone, weekly hours, date exceptions (holidays, special hours), and for the business's calendar reminder emails and confirmation calls. Only the fields you pass change. The first call creates the calendar; then add meeting types with calendar_save_meeting_type. Costs $0.001 per call; nothing if it fails.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "maxLength": 254, "description": "Someone on the account (admin_save_person), by email: sets up their own calendar and booking page instead of the business's."}, "name": {"type": "string", "minLength": 1, "maxLength": 120}, "about": {"type": "string", "maxLength": 300, "description": "A line under the name on the booking page."}, "address": {"type": "string", "minLength": 3, "maxLength": 50, "description": "The booking page's address, like a Cal.com username: cncto.co/book/<address>. Lowercase letters, digits and hyphens, e.g. hansen-voss. The old address keeps working and forwards to the new one; no other business can take it."}, "timezone": {"type": "string", "maxLength": 80, "description": "IANA time zone, e.g. Europe/Berlin."}, "hours": {"type": "array", "maxItems": 50, "description": "Weekly hours; several ranges a day are fine.", "items": {"type": "object", "required": ["day", "start", "end"], "additionalProperties": false, "properties": {"day": {"type": "string", "enum": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]}, "start": {"type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$|^24:00$"}, "end": {"type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$|^24:00$"}}}}, "date_exceptions": {"type": "object", "description": "{\"2026-12-24\": []} closes a day; {\"2026-12-31\": [{\"start\": \"09:00\", \"end\": \"13:00\"}]} sets its hours."}, "show_people": {"type": "boolean", "description": "The business's booking page links the pages of its people who have meeting types (default true)."}, "reminder_hours": {"type": "array", "maxItems": 2, "items": {"type": "integer", "enum": [1, 2, 3, 6, 12, 24, 48, 72]}, "description": "Email each attendee this many hours before (default [24]; up to two, e.g. [24, 1]); [] turns it off. $0.002 per reminder sent, paid accounts only. A booking made later than that gets none. For every meeting of the business, its people's too."}, "confirmation_calls_hours": {"type": "integer", "minimum": 0, "maximum": 72, "description": "Call attendees this many hours before (2-72); 0 turns the calls off."}, "connected_calendar_id": {"type": "string", "maxLength": 1024, "description": "After the owner (or the person) connected Google Calendar: which of their calendars to use (ids from calendar_get_setup)."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_get_setup": {"post": {"operationId": "calendar_get_setup", "summary": "Get the calendar setup", "description": "The calendar's settings, booking page, iCal subscribe link, connected Google calendar (with the calendars to choose from) and confirmation calls; for the business's calendar also its meeting types and its people's calendars. person reads someone's own calendar. Free.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "maxLength": 254, "description": "Someone on the account, by email: their own calendar instead of the business's."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_connect": {"post": {"operationId": "calendar_connect", "summary": "Connect Google Calendar", "description": "A link to connect a Google calendar: the owner's for the business's calendar, or with person, that person's own. The page names the business, one click connects, and bookings then avoid busy times and appear in it (Google also emails the attendee an invitation). The link works once, for an hour. Then pick the calendar with calendar_setup connected_calendar_id. Outlook calendars: the microsoft365 tools work in them directly. Free.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"provider": {"type": "string", "enum": ["google"]}, "person": {"type": "string", "maxLength": 254, "description": "Someone on the account, by email: their own calendar instead of the business's."}}, "required": ["provider"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_save_meeting_type": {"post": {"operationId": "calendar_save_meeting_type", "summary": "Save a meeting type", "description": "Create or change a kind of meeting people can book, like a Cal.com event type. It gets its own booking page. Only the fields you pass change. With person it is on that person's own calendar. A business type can be hosted by people like a Cal.com team event, once you choose how (there is no default): round_robin gives each booking to one host free then (the highest priority, then the fewest of this type that month for their weight, then whoever was booked longest ago; fixed hosts join every meeting), collective needs every host free and invites them all. Hosts use their own calendars' hours and Google calendars, unless the type sets hours of its own. Each host keeps their own page, which lists the business types they take; a round robin booked there goes to them. Location kinds: video (a link), phone (we call the attendee), call_us (they call a number), in_person (an address), custom. Costs $0.001 per call; nothing if it fails.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"slug": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,59}$", "description": "Its address on the booking page, e.g. \"intro-call\"."}, "person": {"type": "string", "maxLength": 254, "description": "Put it on this person's own calendar (their email) instead of the business's."}, "title": {"type": "string", "minLength": 1, "maxLength": 120}, "description": {"type": "string", "maxLength": 2000}, "length_minutes": {"type": "integer", "minimum": 5, "maximum": 480}, "location": {"type": "object", "additionalProperties": false, "description": "Where it happens. google_meet gives each booking a Google Meet room of its own once the calendar that takes it is connected to Google (a video link on meet.google.com does the same); video is one fixed link, phone means you call them, call_us your number in value, in_person an address.", "properties": {"kind": {"type": "string", "enum": ["", "video", "google_meet", "phone", "call_us", "in_person", "custom"]}, "value": {"type": "string", "maxLength": 500}}}, "assignment": {"type": "string", "enum": ["", "round_robin", "collective"], "description": "How a business type's hosts take its bookings, required with hosts (no default): round_robin or collective; \"\" takes the hosts off, back to the business's own calendar."}, "hosts": {"type": "array", "maxItems": 50, "description": "The people who take its bookings, replacing the list. Each is on the account; their calendar is made with their name if they have none.", "items": {"type": "object", "required": ["person"], "additionalProperties": false, "properties": {"person": {"type": "string", "maxLength": 254}, "fixed": {"type": "boolean", "description": "In every meeting (round robin)."}, "priority": {"type": "string", "enum": ["lowest", "low", "medium", "high", "highest"], "description": "Round robin: higher goes first (default medium)."}, "weight": {"type": "integer", "minimum": 1, "maximum": 1000, "description": "Round robin: 200 takes twice the share of 100 (default 100)."}}}}, "buffer_before": {"type": "integer", "minimum": 0, "maximum": 240}, "buffer_after": {"type": "integer", "minimum": 0, "maximum": 240}, "notice_minutes": {"type": "integer", "minimum": 0, "maximum": 43200, "description": "Minimum notice before a booking."}, "days_ahead": {"type": "integer", "minimum": 1, "maximum": 365}, "slot_interval": {"type": "integer", "minimum": 5, "maximum": 480, "description": "Minutes between possible start times (default: the length)."}, "max_per_day": {"type": "integer", "minimum": 1, "maximum": 200, "description": "The most of this type a day; for a hosted type, each host's most."}, "hours": {"type": "array", "maxItems": 50, "description": "Its own weekly hours; leave out to use the calendar's (for hosts, each one's own).", "items": {"type": "object", "required": ["day", "start", "end"], "additionalProperties": false, "properties": {"day": {"type": "string", "enum": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]}, "start": {"type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$|^24:00$"}, "end": {"type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$|^24:00$"}}}}, "questions": {"type": "array", "maxItems": 20, "description": "Extra questions on the booking form: {label, type: text|long_text|select|checkbox|number|email|phone, required, options}.", "items": {"type": "object"}}, "ask_phone": {"type": "string", "enum": ["off", "optional", "required"]}, "offer_confirmation_call": {"type": "boolean", "description": "Offer \"call me the day before to confirm\" on the form."}, "phone_assistant_books_this": {"type": "boolean", "description": "What the phone assistant books when a caller asks (a business type)."}, "active": {"type": "boolean"}}, "required": ["slug"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_list_meeting_types": {"post": {"operationId": "calendar_list_meeting_types", "summary": "List meeting types", "description": "The meeting types people can book, with their booking pages: the business's, then each person's own (meeting_type is how the other tools name each one). person lists only theirs. Free.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "maxLength": 254, "description": "Someone on the account, by email: their own calendar instead of the business's."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_find_times": {"post": {"operationId": "calendar_find_times", "summary": "Find free times", "description": "Free start times for a meeting type between two dates (up to 62 days), shown in the time zone you ask for. For a round-robin type, host shows only that host's free times. Book one with calendar_book. Free.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"meeting_type": {"type": "string", "description": "Its slug, or \"<person's address>/<slug>\" for a person's own type."}, "person": {"type": "string", "maxLength": 254, "description": "The meeting type is on this person's own calendar."}, "host": {"type": "string", "maxLength": 254, "description": "A round-robin type: only this host."}, "from": {"type": "string", "format": "date"}, "to": {"type": "string", "format": "date"}, "timezone": {"type": "string", "maxLength": 80, "description": "Show times in this IANA zone (default: the calendar's)."}}, "required": ["meeting_type"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_book": {"post": {"operationId": "calendar_book", "summary": "Book a meeting", "description": "Book a free time (from calendar_find_times) for someone. They get a confirmation email with a calendar invite and a link to reschedule or cancel (if you give their email), and so do their guests (without the link). A round-robin type picks the host by its rules unless you name one. Set confirmation_call_agreed only if the person agreed to a call before the meeting asking whether they can still come. Costs $0.05 per call; nothing if it fails.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"meeting_type": {"type": "string", "description": "Its slug, or \"<person's address>/<slug>\"."}, "person": {"type": "string", "maxLength": 254, "description": "The meeting type is on this person's own calendar."}, "host": {"type": "string", "maxLength": 254, "description": "A round-robin type: give it to this host (they must be free then)."}, "start": {"type": "string", "format": "date-time"}, "name": {"type": "string", "minLength": 1, "maxLength": 120}, "email": {"type": "string", "maxLength": 254}, "phone": {"type": "string", "maxLength": 30}, "guests": {"type": "array", "maxItems": 10, "items": {"type": "string", "maxLength": 254}, "description": "More people to invite, by email."}, "timezone": {"type": "string", "maxLength": 80, "description": "The attendee's IANA time zone."}, "answers": {"type": "object", "description": "Answers to the meeting type's questions, by key."}, "confirmation_call_agreed": {"type": "boolean", "default": false}, "notify": {"type": "boolean", "default": true, "description": "Email the attendee, the guests and the hosts (or the owner)."}}, "required": ["meeting_type", "start", "name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_move": {"post": {"operationId": "calendar_move", "summary": "Move a meeting", "description": "Move a booking to another free time. The attendee and the guests get an updated invite by email. A round-robin meeting keeps its host when they are free then, else goes to the host its rules pick. Costs $0.01 per call; nothing if it fails.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"booking": {"type": "string", "description": "Its reference or booking_id."}, "start": {"type": "string", "format": "date-time"}, "notify": {"type": "boolean", "default": true}}, "required": ["booking", "start"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_cancel": {"post": {"operationId": "calendar_cancel", "summary": "Cancel a meeting", "description": "Cancel a booking. The attendee, the guests and the hosts are told by email (unless notify is false). Costs $0.01 per call; nothing if it fails.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"booking": {"type": "string"}, "reason": {"type": "string", "maxLength": 300}, "notify": {"type": "boolean", "default": true}}, "required": ["booking"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_list_bookings": {"post": {"operationId": "calendar_list_bookings", "summary": "List bookings", "description": "Bookings between two times (default: from now on), soonest first, with each one's hosts, guests and confirmation call. person lists the meetings that person has. Free.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"from": {"type": "string", "format": "date-time"}, "to": {"type": "string", "format": "date-time"}, "status": {"type": "string", "enum": ["scheduled", "cancelled", "any"], "default": "scheduled"}, "meeting_type": {"type": "string"}, "person": {"type": "string", "maxLength": 254, "description": "Someone on the account, by email: their own calendar instead of the business's."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_save_routing_form": {"post": {"operationId": "calendar_save_routing_form", "summary": "Save a routing form", "description": "Create or change a routing form, like Cal.com's: questions a visitor answers before booking, and routes that send them to a meeting type (for a round-robin type, perhaps only some of its hosts), another site, or a message. The first route whose conditions all hold wins; everyone else takes the fallback. It lives at its calendar's address beside the meeting types: cncto.co/book/<calendar>/<slug>. A question keyed name (text) or email (email) fills in the booking form. Only the fields you pass change. Each answer set is kept (calendar_list_routing_responses) and the bot hears of it (calendar.routed). Costs $0.001 per call; nothing if it fails.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"slug": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,59}$", "description": "Its address, e.g. \"get-started\"."}, "person": {"type": "string", "maxLength": 254, "description": "Put it on this person's own calendar."}, "title": {"type": "string", "minLength": 1, "maxLength": 120}, "description": {"type": "string", "maxLength": 2000}, "questions": {"type": "array", "maxItems": 20, "items": {"type": "object"}, "description": "{key, label, type: text|long_text|select|checkbox|number|email|phone, required, options}."}, "routes": {"type": "array", "maxItems": 30, "items": {"type": "object"}, "description": "[{\"when\": [{\"question\": \"<a question's key>\", \"<is|is_not|any_of|none_of|contains|at_least|below>\": <value>}, ...], \"to\": {\"meeting_type\": \"demo\", \"hosts\": [\"ana@example.com\"]} | {\"url\": \"https://...\"} | {\"message\": \"...\"}}], tried in order."}, "fallback": {"type": "object", "description": "Where everyone else goes, as a route's \"to\"."}, "active": {"type": "boolean"}}, "required": ["slug"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_list_routing_forms": {"post": {"operationId": "calendar_list_routing_forms", "summary": "List routing forms", "description": "The routing forms, with their addresses, questions, routes and how many people answered each. Free.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/calendar_list_routing_responses": {"post": {"operationId": "calendar_list_routing_responses", "summary": "List routing form answers", "description": "What people answered on the routing forms, newest first: their answers, where each was sent, and the booking it led to. Free.", "tags": ["calendar"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "description": "A routing form's slug."}, "person": {"type": "string", "maxLength": 254, "description": "Someone on the account, by email: their own calendar instead of the business's."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_setup": {"post": {"operationId": "chat_setup", "summary": "Set up the website chat", "description": "Create or change the business's website chat widget, which you answer: each visitor message reaches you as a chat.message_received event (subscribe a webhook to it, or use chat_wait) and you reply with chat_reply. Or answer_with webhook: your own brain (your server, n8n, Flowise) gets each message as a signed POST and its reply goes to the visitor at once. Or answer_with model: a model on the business's own key answers, with instructions and knowledge you give. Conecto pays for no model in it. Only the fields you pass change. The reply has the HTML snippet to put on the website. $0.05 per conversation, charged on the visitor's first message; messages and replies are free. Costs $0.001 per call; nothing if it fails.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 120, "description": "The business name."}, "website": {"type": "string", "maxLength": 255, "description": "The website it goes on."}, "greeting": {"type": "string", "minLength": 1, "maxLength": 300, "description": "The first line visitors see."}, "agent_name": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The name your replies are signed with, e.g. \"Acme Support\"."}, "color": {"type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Accent colour, e.g. #1a73e8."}, "language": {"type": "string", "pattern": "^[a-z]{2}$", "description": "Widget language, e.g. en, de."}, "experience": {"type": "string", "enum": ["chat", "beside"], "description": "chat: the classic chat widget. beside: Beside, which also tells you the page the visitor is on (its address, title and text) with each message. Same price."}, "starter_questions": {"type": "array", "maxItems": 3, "items": {"type": "string", "minLength": 1, "maxLength": 80}, "description": "Beside: up to 3 questions visitors can tap to start."}, "answer_with": {"type": "string", "enum": ["bot", "webhook", "model"], "description": "bot (the default): you answer through events and chat_reply. webhook: each visitor message is POSTed to webhook_url and its reply goes to the visitor at once. model: a model on the business's own key answers (model_provider, model, model_api_key)."}, "webhook_url": {"type": "string", "maxLength": 500, "description": "Your brain's https endpoint for each visitor message."}, "webhook_token": {"type": "string", "maxLength": 500, "description": "Sent as Authorization: Bearer, for brains that want a key (Flowise, n8n header auth). Empty removes it.", "writeOnly": true}, "rotate_secret": {"type": "boolean", "default": false, "description": "Make a new webhook_secret (the old one stops working)."}, "cant_answer": {"type": "string", "maxLength": 300, "description": "What the chat says when your webhook or model gave no reply; it then asks for the visitor's email. Needed for languages other than en, de, es, fr, it, nl, pt and sv."}, "model_provider": {"type": "string", "enum": ["openai", "anthropic", "openrouter", "mistral", "groq", "azure"], "description": "Whose model answers with answer_with model."}, "model": {"type": "string", "minLength": 1, "maxLength": 160, "description": "The provider's model name, e.g. gpt-5.4-mini or claude-sonnet-5-5; for azure the deployment name. It must support tool calling."}, "model_api_key": {"type": "string", "minLength": 1, "maxLength": 500, "description": "The business's API key for model_provider. Kept encrypted, never shown again; its usage is billed by the provider to the business.", "writeOnly": true}, "model_base_url": {"type": "string", "maxLength": 300, "description": "azure only: the resource's address, like https://acme.openai.azure.com/openai/v1/."}, "instructions": {"type": "string", "maxLength": 4000, "description": "answer_with model: how the model answers (tone, scope, what to offer), in the business's words."}, "knowledge": {"type": "string", "maxLength": 50000, "description": "answer_with model: facts it answers from (prices, delivery, opening hours). Replaces what was given before; empty removes it. The published help center is used as well."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_get_setup": {"post": {"operationId": "chat_get_setup", "summary": "Get the website chat setup", "description": "The website chat widget's settings, its embed snippet, how messages reach you and this month's cost. Free.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_list_conversations": {"post": {"operationId": "chat_list_conversations", "summary": "List chat conversations", "description": "Website chat (and email) conversations, newest activity first, with who it is and the last message. Free.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["open", "pending", "closed", "any"], "default": "any"}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}, "before": {"type": "string", "format": "date-time", "description": "Only conversations active before this time, to page back."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_get_conversation": {"post": {"operationId": "chat_get_conversation", "summary": "Get a chat conversation", "description": "One conversation with all its messages (from the visitor or the business). Free.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"conversation_id": {"type": "integer", "minimum": 1}}, "required": ["conversation_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_create_ticket": {"post": {"operationId": "chat_create_ticket", "summary": "Turn a chat into a ticket", "description": "Open a help desk ticket from a chat that needs follow-up: the chat so far becomes the request, the visitor its requester (their email from the chat, or email), linked to the chat and their CRM contact, so the rest goes by email under the help desk's targets. A chat that already has an open ticket returns that one. $0.01. Costs $0.01 per call; nothing if it fails.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"conversation_id": {"type": "integer", "minimum": 1}, "email": {"type": "string", "maxLength": 254, "description": "When the visitor gave none in the chat."}, "subject": {"type": "string", "maxLength": 200}, "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"], "default": "normal"}, "category": {"type": "string", "maxLength": 80}}, "required": ["conversation_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_reply": {"post": {"operationId": "chat_reply", "summary": "Reply in a chat", "description": "Answer the visitor as the business. A closed conversation reopens. A visitor who left gets the reply by email if they gave one. internal: true adds a private note instead of a reply. blocks adds rich content (cards with a picture, title, price and link; images; buttons). In Beside, point highlights things on the visitor's screen one after another (ids from page.elements in the chat.message_received event), and open_page takes them to another page of the site; one of the two per reply. The visitor sees the reply labelled as an AI agent's unless by_person says a person wrote it. Free.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"conversation_id": {"type": "integer", "minimum": 1}, "text": {"type": "string", "minLength": 1, "maxLength": 5000}, "internal": {"type": "boolean", "default": false}, "by_person": {"type": "boolean", "default": false, "description": "true when a person at the business wrote this reply. Otherwise the visitor sees it labelled as an AI agent's (EU AI Act Art. 50). A person's reply also stops a webhook brain from answering this chat."}, "blocks": {"type": "array", "maxItems": 10, "items": {"type": "object"}, "description": "Like [{\"type\": \"cards\", \"items\": [{\"title\": \"Tabor gravel bike\", \"price\": \"$1,890\", \"image\": \"https://...\", \"url\": \"https://...\"}]}]."}, "point": {"type": "array", "minItems": 1, "maxItems": 5, "items": {"type": "object", "properties": {"id": {"type": "string", "minLength": 1, "maxLength": 8}, "say": {"type": "string", "maxLength": 90}}, "required": ["id"]}}, "open_page": {"type": "object", "properties": {"url": {"type": "string", "maxLength": 600}, "label": {"type": "string", "maxLength": 40}}, "required": ["url"]}}, "required": ["conversation_id", "text"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_close": {"post": {"operationId": "chat_close", "summary": "Close or reopen a chat", "description": "Close a conversation once it is handled, or reopen it. Costs $0.001 per call; nothing if it fails.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"conversation_id": {"type": "integer", "minimum": 1}, "status": {"type": "string", "enum": ["closed", "open"]}}, "required": ["conversation_id", "status"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_wait": {"post": {"operationId": "chat_wait", "summary": "Wait for visitor messages", "description": "Listen to the website chat without a server: returns as soon as a visitor writes (or after timeout_seconds with no messages). Pass next_after from the previous call as after, and call again after call_again_in_seconds to keep listening (it is 60 when nobody is on the website, so the call answers at once); the first call also lists conversations still waiting for an answer. While you listen, the widget shows the business as online. A server should subscribe a webhook to chat.message_received instead. Free.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"after": {"type": "integer", "minimum": 0, "description": "next_after from the last call."}, "timeout_seconds": {"type": "integer", "minimum": 0, "maximum": 25, "default": 25}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/chat_typing": {"post": {"operationId": "chat_typing", "summary": "Show that you are typing", "description": "Shows \"typing\" to the visitor for about 8 seconds; call it again while you work on a longer answer. Free.", "tags": ["chat"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"conversation_id": {"type": "integer", "minimum": 1}}, "required": ["conversation_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_find_contacts": {"post": {"operationId": "crm_find_contacts", "summary": "Find contacts", "description": "Search the CRM by name, email, company or phone, or by filters on any field, tag or custom field, or by a saved segment. Returns a page of contacts (most recently seen first unless `sort` says otherwise), the total, and next_offset for the next page. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "maxLength": 200}, "lifecycle_stage": {"type": "string", "enum": ["lead", "trial", "onboarding", "customer", "at_risk", "churned", "advocate"]}, "include_archived": {"type": "boolean", "default": false}, "filters": {"type": "array", "maxItems": 20, "description": "Conditions that must all match, e.g. [{\"field\": \"lifecycle_stage\", \"op\": \"eq\", \"value\": \"customer\"}, {\"field\": \"renewal_date\", \"op\": \"lte\", \"value\": \"today+30\"}]. field: a standard field, \"tag\", or a custom field key (crm_list_fields lists them all). op: eq, ne, contains, starts_with, in (value is a list), gt, gte, lt, lte, is_empty, is_set. Dates take YYYY-MM-DD or today, today+N, today-N.", "items": {"type": "object", "required": ["field", "op"], "additionalProperties": false, "properties": {"field": {"type": "string", "maxLength": 60, "minLength": 1}, "op": {"type": "string", "enum": ["contains", "eq", "gt", "gte", "in", "is_empty", "is_set", "lt", "lte", "ne", "starts_with"]}, "value": {"description": "Text, a number, true/false, a date, or a list for \"in\"."}}}}, "tag": {"type": "string", "maxLength": 60, "description": "Only records with this tag."}, "segment": {"type": "string", "maxLength": 80, "description": "A saved segment (crm_save_segment), by name or id."}, "sort": {"type": "string", "maxLength": 61, "description": "Field to sort by, \"-\" first for descending, e.g. \"-amount\" or \"renewal_date\"."}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_get_contact": {"post": {"operationId": "crm_get_contact", "summary": "Get a contact", "description": "One contact with its tags, custom fields, recent activity, open tasks and deals, by id or email, and came_from: the website visit that led to their first chat, booking, form or signup (channel, source, campaign, landing page), when the site is counted. crm_timeline has everything that happened with them. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "email": {"type": "string", "maxLength": 254}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_get_customer": {"post": {"operationId": "crm_get_customer", "summary": "Everything open with a customer", "description": "One read before you answer someone: the contact (or company) and what is open with them across Conecto: open deals, help desk tickets, unpaid invoices and open quotes (with the balance due per currency), documents waiting for their signature, their next meetings, the last email, chat and call, their newsletters, and where they first came from on the website. By contact_id, email or company_id (then its contacts' records too). Each list shows up to 5; each area's own tools have the rest. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "email": {"type": "string", "maxLength": 254}, "company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_save_contact": {"post": {"operationId": "crm_save_contact", "summary": "Save a contact", "description": "Create a contact, or update the one with this email if it already exists. Only the fields you send change; tags are added, custom fields merged. Without an email a new contact is always created. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "maxLength": 254, "format": "email"}, "name": {"type": "string", "maxLength": 255}, "title": {"type": "string", "maxLength": 255}, "company": {"type": "string", "maxLength": 255, "description": "Company name; also links or creates the company record."}, "phone": {"type": "string", "maxLength": 60}, "location": {"type": "string", "maxLength": 255}, "timezone": {"type": "string", "maxLength": 60}, "language": {"type": "string", "maxLength": 60}, "lifecycle_stage": {"type": "string", "enum": ["lead", "trial", "onboarding", "customer", "at_risk", "churned", "advocate"]}, "notes": {"type": "string", "maxLength": 20000}, "custom_fields": {"type": "object", "maxProperties": 60, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 1000}, "description": "Custom fields as {\"key\": value}, merged into the existing ones; null clears one. Keys defined with crm_define_field are checked against their type."}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 60, "minLength": 1}, "description": "Tags to add, e.g. [\"vip\"]; a new tag is made on first use. crm_tag_records removes tags."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_save_contacts": {"post": {"operationId": "crm_save_contacts", "summary": "Save many contacts", "description": "Create or update up to 100 contacts in one call, each exactly like crm_save_contact (matched by email; without an email a new contact is made). Each one succeeds or fails on its own; the reply lists which, and you pay only for the ones saved. Costs $0.01 per record saved; nothing if none are found.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contacts": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "properties": {"email": {"type": "string", "maxLength": 254, "format": "email"}, "name": {"type": "string", "maxLength": 255}, "title": {"type": "string", "maxLength": 255}, "company": {"type": "string", "maxLength": 255, "description": "Company name; also links or creates the company record."}, "phone": {"type": "string", "maxLength": 60}, "location": {"type": "string", "maxLength": 255}, "timezone": {"type": "string", "maxLength": 60}, "language": {"type": "string", "maxLength": 60}, "lifecycle_stage": {"type": "string", "enum": ["lead", "trial", "onboarding", "customer", "at_risk", "churned", "advocate"]}, "notes": {"type": "string", "maxLength": 20000}, "custom_fields": {"type": "object", "maxProperties": 60, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 1000}, "description": "Custom fields as {\"key\": value}, merged into the existing ones; null clears one. Keys defined with crm_define_field are checked against their type."}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 60, "minLength": 1}, "description": "Tags to add, e.g. [\"vip\"]; a new tag is made on first use. crm_tag_records removes tags."}}}}}, "required": ["contacts"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_update_contact": {"post": {"operationId": "crm_update_contact", "summary": "Update a contact", "description": "Change fields on an existing contact by id. Only the fields you send change; tags are added, custom fields merged. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "email": {"type": "string", "maxLength": 254, "format": "email"}, "name": {"type": "string", "maxLength": 255}, "title": {"type": "string", "maxLength": 255}, "company": {"type": "string", "maxLength": 255, "description": "Company name; also links or creates the company record."}, "phone": {"type": "string", "maxLength": 60}, "location": {"type": "string", "maxLength": 255}, "timezone": {"type": "string", "maxLength": 60}, "language": {"type": "string", "maxLength": 60}, "lifecycle_stage": {"type": "string", "enum": ["lead", "trial", "onboarding", "customer", "at_risk", "churned", "advocate"]}, "notes": {"type": "string", "maxLength": 20000}, "custom_fields": {"type": "object", "maxProperties": 60, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 1000}, "description": "Custom fields as {\"key\": value}, merged into the existing ones; null clears one. Keys defined with crm_define_field are checked against their type."}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 60, "minLength": 1}, "description": "Tags to add, e.g. [\"vip\"]; a new tag is made on first use. crm_tag_records removes tags."}}, "required": ["contact_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_archive_contact": {"post": {"operationId": "crm_archive_contact", "summary": "Archive a contact", "description": "Hide a contact from searches and lists. Its history is kept; crm_update_contact cannot un-archive, crm_restore_contact does. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}, "required": ["contact_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_restore_contact": {"post": {"operationId": "crm_restore_contact", "summary": "Restore a contact", "description": "Bring an archived contact back. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}, "required": ["contact_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_add_note": {"post": {"operationId": "crm_add_note", "summary": "Add a note", "description": "Add a note to a contact (by contact id or email), a deal or a company: what was said, decided or learned. A note on a deal also shows on its company's and contact's timelines. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "email": {"type": "string", "maxLength": 254}, "deal_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "title": {"type": "string", "maxLength": 200}, "body": {"type": "string", "maxLength": 20000}}, "required": ["body"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_create_task": {"post": {"operationId": "crm_create_task", "summary": "Create a task", "description": "A follow-up on a contact, with an optional due time (ISO 8601) and priority. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "email": {"type": "string", "maxLength": 254}, "title": {"type": "string", "maxLength": 200, "minLength": 1}, "details": {"type": "string", "maxLength": 5000}, "due_at": {"type": "string", "maxLength": 40, "description": "ISO 8601, e.g. 2026-10-20T09:00:00Z"}, "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"]}}, "required": ["title"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_list_tasks": {"post": {"operationId": "crm_list_tasks", "summary": "List tasks", "description": "Tasks by status (default open), optionally for one contact or due before a time, soonest first, each with the contact it is about (id, name, email). Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["open", "done", "cancelled"], "default": "open"}, "contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "due_before": {"type": "string", "maxLength": 40}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_complete_task": {"post": {"operationId": "crm_complete_task", "summary": "Complete a task", "description": "Mark a task done (or cancelled). Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"task_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "status": {"type": "string", "enum": ["done", "cancelled"], "default": "done"}}, "required": ["task_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_save_company": {"post": {"operationId": "crm_save_company", "summary": "Save a company", "description": "Create a company, or update the one with this name (case-insensitive). With company_id, update that company instead, and a name renames it. Only the fields you send change; tags are added, custom fields merged. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "name": {"type": "string", "maxLength": 255, "minLength": 1, "description": "Required unless company_id is given; with it, the company's new name."}, "domain": {"type": "string", "maxLength": 255}, "website": {"type": "string", "maxLength": 500}, "industry": {"type": "string", "maxLength": 120}, "employee_count": {"type": "integer", "minimum": 0}, "lifecycle_stage": {"type": "string", "enum": ["prospect", "onboarding", "customer", "churned"]}, "notes": {"type": "string", "maxLength": 20000}, "custom_fields": {"type": "object", "maxProperties": 60, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 1000}, "description": "Custom fields as {\"key\": value}, merged into the existing ones; null clears one. Keys defined with crm_define_field are checked against their type."}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 60, "minLength": 1}, "description": "Tags to add, e.g. [\"vip\"]; a new tag is made on first use. crm_tag_records removes tags."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_archive_company": {"post": {"operationId": "crm_archive_company", "summary": "Archive a company", "description": "Hide a company from crm_find_companies, crm_search, duplicates and exports. Its people, deals and notes stay as they are, and crm_get_company still reads it (archived: true). Saving it again, even by name, does not bring it back; crm_restore_company does. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}, "required": ["company_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_restore_company": {"post": {"operationId": "crm_restore_company", "summary": "Restore a company", "description": "Bring an archived company back into the lists, searches, duplicates and exports. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}, "required": ["company_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_save_companies": {"post": {"operationId": "crm_save_companies", "summary": "Save many companies", "description": "Create or update up to 100 companies in one call, each exactly like crm_save_company (matched by name). Each one succeeds or fails on its own; the reply lists which, and you pay only for the ones saved. Costs $0.01 per record saved; nothing if none are found.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"companies": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "required": ["name"], "additionalProperties": false, "properties": {"name": {"type": "string", "maxLength": 255, "minLength": 1}, "domain": {"type": "string", "maxLength": 255}, "website": {"type": "string", "maxLength": 500}, "industry": {"type": "string", "maxLength": 120}, "employee_count": {"type": "integer", "minimum": 0}, "lifecycle_stage": {"type": "string", "enum": ["prospect", "onboarding", "customer", "churned"]}, "notes": {"type": "string", "maxLength": 20000}, "custom_fields": {"type": "object", "maxProperties": 60, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 1000}, "description": "Custom fields as {\"key\": value}, merged into the existing ones; null clears one. Keys defined with crm_define_field are checked against their type."}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 60, "minLength": 1}, "description": "Tags to add, e.g. [\"vip\"]; a new tag is made on first use. crm_tag_records removes tags."}}}}}, "required": ["companies"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_find_companies": {"post": {"operationId": "crm_find_companies", "summary": "Find companies", "description": "Search companies by name or domain, or by filters on any field, tag or custom field, or by a saved segment. Archived companies are left out unless include_archived is true. Returns a page, the total, and next_offset for the next page. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "maxLength": 200}, "lifecycle_stage": {"type": "string", "enum": ["prospect", "onboarding", "customer", "churned"]}, "include_archived": {"type": "boolean", "default": false}, "filters": {"type": "array", "maxItems": 20, "description": "Conditions that must all match, e.g. [{\"field\": \"lifecycle_stage\", \"op\": \"eq\", \"value\": \"customer\"}, {\"field\": \"renewal_date\", \"op\": \"lte\", \"value\": \"today+30\"}]. field: a standard field, \"tag\", or a custom field key (crm_list_fields lists them all). op: eq, ne, contains, starts_with, in (value is a list), gt, gte, lt, lte, is_empty, is_set. Dates take YYYY-MM-DD or today, today+N, today-N.", "items": {"type": "object", "required": ["field", "op"], "additionalProperties": false, "properties": {"field": {"type": "string", "maxLength": 60, "minLength": 1}, "op": {"type": "string", "enum": ["contains", "eq", "gt", "gte", "in", "is_empty", "is_set", "lt", "lte", "ne", "starts_with"]}, "value": {"description": "Text, a number, true/false, a date, or a list for \"in\"."}}}}, "tag": {"type": "string", "maxLength": 60, "description": "Only records with this tag."}, "segment": {"type": "string", "maxLength": 80, "description": "A saved segment (crm_save_segment), by name or id."}, "sort": {"type": "string", "maxLength": 61, "description": "Field to sort by, \"-\" first for descending, e.g. \"-amount\" or \"renewal_date\"."}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_get_company": {"post": {"operationId": "crm_get_company", "summary": "Get a company", "description": "One company, by id or name, with its tags, custom fields, people, deals (open ones first) and notes, each note with who wrote it (by and via, as crm_timeline gives them). An archived company is read too (archived: true). Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "name": {"type": "string", "maxLength": 255}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_save_deal": {"post": {"operationId": "crm_save_deal", "summary": "Save a deal", "description": "Create a deal (no deal_id) or update one (with deal_id): pipeline and stage, amount, expected close date, next step, the company and contact it belongs to, tags and custom fields. A new deal starts at the first stage of its pipeline unless you give one. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"deal_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "title": {"type": "string", "maxLength": 200, "minLength": 1}, "pipeline": {"type": "string", "maxLength": 80, "description": "Pipeline name or id (crm_list_pipelines). Default: the deal's own, else the first pipeline."}, "stage": {"type": "string", "maxLength": 60, "description": "Stage name or id in that pipeline, e.g. \"Proposal\". A new deal without one starts at the first stage. crm_move_deal moves deals too."}, "amount": {"type": "number", "minimum": 0}, "currency": {"type": "string", "maxLength": 3, "minLength": 3}, "close_date": {"type": "string", "maxLength": 10, "description": "YYYY-MM-DD: when it is expected to close"}, "next_step": {"type": "string", "maxLength": 500}, "description": {"type": "string", "maxLength": 20000}, "company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "company_name": {"type": "string", "maxLength": 255}, "contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "contact_email": {"type": "string", "maxLength": 254}, "lost_reason": {"type": "string", "maxLength": 500}, "custom_fields": {"type": "object", "maxProperties": 60, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 1000}, "description": "Custom fields as {\"key\": value}, merged into the existing ones; null clears one. Keys defined with crm_define_field are checked against their type."}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 60, "minLength": 1}, "description": "Tags to add, e.g. [\"vip\"]; a new tag is made on first use. crm_tag_records removes tags."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_find_deals": {"post": {"operationId": "crm_find_deals", "summary": "Find deals", "description": "Deals by pipeline, stage, status (open, won, lost), company or contact, or by filters on any field, tag or custom field, or by a saved segment; most recently changed first unless `sort` says otherwise. Deals that have not moved in 14 days: filters [{\"field\": \"status\", \"op\": \"eq\", \"value\": \"open\"}, {\"field\": \"stage_entered_at\", \"op\": \"lt\", \"value\": \"today-14\"}]. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"pipeline": {"type": "string", "maxLength": 80}, "stage": {"type": "string", "maxLength": 60}, "status": {"type": "string", "enum": ["open", "won", "lost"]}, "company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "query": {"type": "string", "maxLength": 200}, "filters": {"type": "array", "maxItems": 20, "description": "Conditions that must all match, e.g. [{\"field\": \"lifecycle_stage\", \"op\": \"eq\", \"value\": \"customer\"}, {\"field\": \"renewal_date\", \"op\": \"lte\", \"value\": \"today+30\"}]. field: a standard field, \"tag\", or a custom field key (crm_list_fields lists them all). op: eq, ne, contains, starts_with, in (value is a list), gt, gte, lt, lte, is_empty, is_set. Dates take YYYY-MM-DD or today, today+N, today-N.", "items": {"type": "object", "required": ["field", "op"], "additionalProperties": false, "properties": {"field": {"type": "string", "maxLength": 60, "minLength": 1}, "op": {"type": "string", "enum": ["contains", "eq", "gt", "gte", "in", "is_empty", "is_set", "lt", "lte", "ne", "starts_with"]}, "value": {"description": "Text, a number, true/false, a date, or a list for \"in\"."}}}}, "tag": {"type": "string", "maxLength": 60, "description": "Only records with this tag."}, "segment": {"type": "string", "maxLength": 80, "description": "A saved segment (crm_save_segment), by name or id."}, "sort": {"type": "string", "maxLength": 61, "description": "Field to sort by, \"-\" first for descending, e.g. \"-amount\" or \"renewal_date\"."}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_get_deal": {"post": {"operationId": "crm_get_deal", "summary": "Get a deal", "description": "One deal with its pipeline and stage, its stage history (each stage and the days it stayed there), its notes with who wrote each (by and via, as crm_timeline gives them), and its contact and company. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"deal_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}, "required": ["deal_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_list_pipelines": {"post": {"operationId": "crm_list_pipelines", "summary": "List pipelines", "description": "The deal pipelines in order, each with its stages in order: id, name, probability (the chance a deal there is won, 0-100), outcome (open, won or lost), and how many deals sit there with their value by currency. Every account starts with \"Sales\": New, Qualified, Meeting, Proposal, Negotiation, Won, Lost. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_save_pipeline": {"post": {"operationId": "crm_save_pipeline", "summary": "Save a pipeline", "description": "Create a deal pipeline, or change one (by pipeline_id, or the pipeline with this name): its name, its position among the pipelines, and its stages in order. A stage that still holds deals cannot be dropped; move them first with crm_move_deal. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"pipeline_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "name": {"type": "string", "maxLength": 80, "minLength": 1}, "position": {"type": "integer", "minimum": 0, "maximum": 100}, "stages": {"type": "array", "minItems": 1, "maxItems": 30, "description": "All the stages, in order. Keep a stage (and its deals) by giving its id or its current name. Won and Lost are added when no stage has those outcomes; open stages without a probability get one spread evenly.", "items": {"type": "object", "required": ["name"], "additionalProperties": false, "properties": {"id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "name": {"type": "string", "maxLength": 60, "minLength": 1}, "probability": {"type": "integer", "minimum": 0, "maximum": 100}, "outcome": {"type": "string", "enum": ["open", "won", "lost"], "default": "open"}}}}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_delete_pipeline": {"post": {"operationId": "crm_delete_pipeline", "summary": "Delete a pipeline", "description": "Delete an empty pipeline (by id or name). A pipeline that holds deals cannot be deleted: move them to another pipeline first with crm_move_deal. The last pipeline cannot be deleted. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"pipeline": {"type": "string", "maxLength": 80, "minLength": 1}}, "required": ["pipeline"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_move_deal": {"post": {"operationId": "crm_move_deal", "summary": "Move a deal", "description": "Move a deal to a stage (by name or id), optionally of another pipeline. A won or lost stage closes the deal (give lost_reason when it is lost); an open stage reopens it. Each move is kept in the deal's history: crm_get_deal shows how many days it stayed in each stage. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"deal_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "stage": {"type": "string", "maxLength": 60, "minLength": 1}, "pipeline": {"type": "string", "maxLength": 80}, "lost_reason": {"type": "string", "maxLength": 500}}, "required": ["deal_id", "stage"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_pipeline_report": {"post": {"operationId": "crm_pipeline_report", "summary": "Pipeline report", "description": "How a pipeline is doing: open deals by stage with their value and weighted value (value x probability), deals won and lost in a period (this month by default) with the win rate, average deal won, average days to close and lost reasons, a forecast of open deals by expected close month, and how many open deals have not moved for stale_days. Values are per currency. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"pipeline": {"type": "string", "maxLength": 80, "description": "Name or id; default: the first pipeline."}, "since": {"type": "string", "maxLength": 10, "description": "First day of the period: YYYY-MM-DD or today-30. Default: the 1st of this month."}, "until": {"type": "string", "maxLength": 10, "description": "Last day of the period (included). Default: today."}, "stale_days": {"type": "integer", "minimum": 1, "maximum": 365, "default": 30}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_define_field": {"post": {"operationId": "crm_define_field", "summary": "Define a custom field", "description": "Add a field of your own to contacts, companies or deals, such as a \"plan\" picked from a list or a \"renewal_date\", or change its label, description or options. From then on values sent in custom_fields are checked against its type (text, number, boolean, date as YYYY-MM-DD, select from options, url, email, phone), and you can filter and sort on it. A field that holds values keeps its type; delete it and define it again to change the type. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company", "deal"]}, "key": {"type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$", "description": "snake_case, e.g. \"renewal_date\""}, "type": {"type": "string", "enum": ["text", "number", "boolean", "date", "select", "url", "email", "phone"]}, "label": {"type": "string", "maxLength": 80}, "options": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 100, "minLength": 1}, "description": "select only: the allowed values"}, "description": {"type": "string", "maxLength": 300, "description": "What the field means, for whoever reads it next."}}, "required": ["object", "key", "type"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_list_fields": {"post": {"operationId": "crm_list_fields", "summary": "List fields", "description": "The fields you can read, filter and sort on for contacts, companies and deals: the standard ones and the custom fields defined with crm_define_field (type, options, description, and how many records hold a value). Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company", "deal"]}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_delete_field": {"post": {"operationId": "crm_delete_field", "summary": "Delete a custom field", "description": "Delete a custom field and its value on every record. This cannot be undone. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company", "deal"]}, "key": {"type": "string", "maxLength": 40, "minLength": 1}}, "required": ["object", "key"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_tag_records": {"post": {"operationId": "crm_tag_records", "summary": "Tag records", "description": "Add and remove tags on up to 100 contacts, companies or deals at once, such as everyone who came to a webinar. A new tag is made on first use; tags match in any case. Find tagged records with the tag argument of the find tools. Costs $0.001 per record tagged; nothing if none are found.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company", "deal"]}, "ids": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}, "add": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 60, "minLength": 1}}, "remove": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 60, "minLength": 1}}}, "required": ["object", "ids"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_list_tags": {"post": {"operationId": "crm_list_tags", "summary": "List tags", "description": "Every tag with how many contacts, companies and deals carry it. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_delete_tag": {"post": {"operationId": "crm_delete_tag", "summary": "Delete a tag", "description": "Delete a tag and take it off every contact, company and deal. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 60, "minLength": 1}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_save_segment": {"post": {"operationId": "crm_save_segment", "summary": "Save a segment", "description": "Save filters under a name, such as \"customers renewing within 30 days\" (a new name creates a segment, an existing one replaces its filters). Use it with the segment argument of crm_find_contacts, crm_find_companies, crm_find_deals and crm_export. Relative dates (today+30) are worked out each time. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company", "deal"]}, "name": {"type": "string", "maxLength": 80, "minLength": 1}, "filters": {"type": "array", "maxItems": 20, "description": "Conditions that must all match, e.g. [{\"field\": \"lifecycle_stage\", \"op\": \"eq\", \"value\": \"customer\"}, {\"field\": \"renewal_date\", \"op\": \"lte\", \"value\": \"today+30\"}]. field: a standard field, \"tag\", or a custom field key (crm_list_fields lists them all). op: eq, ne, contains, starts_with, in (value is a list), gt, gte, lt, lte, is_empty, is_set. Dates take YYYY-MM-DD or today, today+N, today-N.", "items": {"type": "object", "required": ["field", "op"], "additionalProperties": false, "properties": {"field": {"type": "string", "maxLength": 60, "minLength": 1}, "op": {"type": "string", "enum": ["contains", "eq", "gt", "gte", "in", "is_empty", "is_set", "lt", "lte", "ne", "starts_with"]}, "value": {"description": "Text, a number, true/false, a date, or a list for \"in\"."}}}, "minItems": 1}, "sort": {"type": "string", "maxLength": 61, "description": "Default sort, e.g. \"-amount\"."}}, "required": ["object", "name", "filters"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_list_segments": {"post": {"operationId": "crm_list_segments", "summary": "List segments", "description": "The saved segments, each with its filters and how many records match right now. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company", "deal"]}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_delete_segment": {"post": {"operationId": "crm_delete_segment", "summary": "Delete a segment", "description": "Delete a saved segment; the records stay as they are. Costs $0.001 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company", "deal"]}, "segment": {"type": "string", "maxLength": 80, "minLength": 1, "description": "Name or id"}}, "required": ["object", "segment"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_search": {"post": {"operationId": "crm_search", "summary": "Search the CRM", "description": "Find contacts, companies and deals in one call from whatever you have: a name, an email, a phone number (any format), a domain, a company name or a deal title. Use it to turn what someone told you into record ids. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "maxLength": 200, "minLength": 2}, "limit": {"type": "integer", "minimum": 1, "maximum": 25, "default": 5}}, "required": ["query"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_timeline": {"post": {"operationId": "crm_timeline", "summary": "Read a timeline", "description": "Everything that happened with a contact, a company (all its people) or a deal, or in the whole CRM when you name none of them, newest first: notes, tasks, emails from your inboxes, website chats, phone calls (with their summary), tickets, meetings, deal stage moves and deal notes, each with its contact_id where it has one. Each says who made it: `by` is the name of the key whose bot did (like \"Ben, through Claude\"), a person, a form or an import, or null; `via` is \"dashboard\" when a person made it on a dashboard link the key made, \"ai_app\" when the key's AI app did. Read it before you write to someone. For the next page pass next_before as `before`. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"contact_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "email": {"type": "string", "maxLength": 254}, "company_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "deal_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "types": {"type": "array", "items": {"type": "string", "enum": ["note", "activity", "task", "email", "chat", "call", "ticket", "meeting", "deal_stage"]}, "maxItems": 9, "description": "Only these kinds of entries."}, "before": {"type": "string", "maxLength": 40, "description": "ISO 8601: only entries before this time."}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_export": {"post": {"operationId": "crm_export", "summary": "Export as CSV", "description": "Contacts, companies or deals as CSV text (one row each; tags and custom fields as columns), with the same filters, tag and segment as the find tools: for a spreadsheet or for the owner. Archived contacts and companies are left out. Up to 500 rows a call; continue with next_offset. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company", "deal"]}, "filters": {"type": "array", "maxItems": 20, "description": "Conditions that must all match, e.g. [{\"field\": \"lifecycle_stage\", \"op\": \"eq\", \"value\": \"customer\"}, {\"field\": \"renewal_date\", \"op\": \"lte\", \"value\": \"today+30\"}]. field: a standard field, \"tag\", or a custom field key (crm_list_fields lists them all). op: eq, ne, contains, starts_with, in (value is a list), gt, gte, lt, lte, is_empty, is_set. Dates take YYYY-MM-DD or today, today+N, today-N.", "items": {"type": "object", "required": ["field", "op"], "additionalProperties": false, "properties": {"field": {"type": "string", "maxLength": 60, "minLength": 1}, "op": {"type": "string", "enum": ["contains", "eq", "gt", "gte", "in", "is_empty", "is_set", "lt", "lte", "ne", "starts_with"]}, "value": {"description": "Text, a number, true/false, a date, or a list for \"in\"."}}}}, "tag": {"type": "string", "maxLength": 60, "description": "Only records with this tag."}, "segment": {"type": "string", "maxLength": 80, "description": "A saved segment (crm_save_segment), by name or id."}, "sort": {"type": "string", "maxLength": 61, "description": "Field to sort by, \"-\" first for descending, e.g. \"-amount\" or \"renewal_date\"."}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 500}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": ["object"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_find_duplicates": {"post": {"operationId": "crm_find_duplicates", "summary": "Find duplicates", "description": "Contacts or companies that are probably the same: contacts with the same email in any case, the same phone number in any format, or the same name at the same company; companies with the same domain, or the same name once \"Inc\", \"Ltd\", \"GmbH\" and the like are dropped. Archived ones are left out. Merge each group with crm_merge_contacts or crm_merge_companies. Free.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contact", "company"], "default": "contact"}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_merge_contacts": {"post": {"operationId": "crm_merge_contacts", "summary": "Merge contacts", "description": "Merge duplicate contacts into the one you keep. Its empty fields are filled from the others, tags and custom fields are combined (the kept contact wins where both have a value), and every note, task, email, chat, call, ticket and deal moves to it. The merged contacts are archived; their emails still find the kept contact. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"keep_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "merge_ids": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}}, "required": ["keep_id", "merge_ids"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/crm_merge_companies": {"post": {"operationId": "crm_merge_companies", "summary": "Merge companies", "description": "Merge duplicate companies into the one you keep. Its empty fields are filled from the others, tags and custom fields are combined (the kept company wins where both have a value), and their people, deals and notes move to it. The merged companies are deleted. Costs $0.01 per call; nothing if it fails.", "tags": ["crm"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"keep_id": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}, "merge_ids": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "integer", "minimum": 1, "maximum": 9007199254740992}}}, "required": ["keep_id", "merge_ids"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/documents_create_pdf": {"post": {"operationId": "documents_create_pdf", "summary": "Make a PDF", "description": "A PDF from Markdown or HTML, saved in the file store with a download link. Markdown gets a clean document style (headings, tables, lists); HTML is printed the way Chrome prints it, without running JavaScript. Images must be public https links or data: URLs. Give exactly one of markdown or html. Costs $0.02 per call; nothing if it fails.", "tags": ["documents"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 200, "description": "Name for the new file, e.g. \"Quote 1042.pdf\"."}, "markdown": {"type": "string", "maxLength": 500000}, "html": {"type": "string", "maxLength": 1000000}, "css": {"type": "string", "maxLength": 50000, "description": "Extra CSS, e.g. a font size or a logo."}, "paper": {"type": "string", "enum": ["a4", "letter", "legal"], "default": "a4"}, "landscape": {"type": "boolean", "default": false}, "margin_mm": {"type": "integer", "minimum": 0, "maximum": 50, "default": 18}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/documents_convert_to_pdf": {"post": {"operationId": "documents_convert_to_pdf", "summary": "Convert a file to PDF", "description": "Turn a file in the store into a PDF: Word, Excel, PowerPoint, OpenDocument, RTF, CSV or text files, and Markdown or HTML. The PDF is a new file; the original stays. Costs $0.02 per call; nothing if it fails.", "tags": ["documents"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file in the store (files_upload or files_list give its file_id)."}, "name": {"type": "string", "minLength": 1, "maxLength": 200, "description": "Name for the new file, e.g. \"Quote 1042.pdf\"."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/documents_template_fields": {"post": {"operationId": "documents_template_fields", "summary": "List a template's fields", "description": "The placeholders in a Word (.docx) template, e.g. {{ customer_name }} or a {% for item in items %} loop, so you know what data documents_fill_template needs. Free.", "tags": ["documents"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file in the store (files_upload or files_list give its file_id)."}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/documents_fill_template": {"post": {"operationId": "documents_fill_template", "summary": "Fill a Word template", "description": "A new Word file from a .docx template in the store, its {{ placeholders }} filled from data. Templates use Jinja: {{ name }}, {% if paid %}...{% endif %}, and {%tr for row in rows %} to repeat a table row. Turn the result into a PDF with documents_convert_to_pdf. Costs $0.02 per call; nothing if it fails.", "tags": ["documents"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file in the store (files_upload or files_list give its file_id)."}, "data": {"type": "object", "description": "The values, e.g. {\"customer\": \"Acme\", \"items\": [{\"name\": \"Combi steamer\", \"price\": \"€9,800\"}]}."}, "name": {"type": "string", "minLength": 1, "maxLength": 200, "description": "Name for the new file, e.g. \"Quote 1042.pdf\"."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24}}, "required": ["file_id", "data"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/documents_merge_pdfs": {"post": {"operationId": "documents_merge_pdfs", "summary": "Merge PDFs", "description": "One PDF from several in the store, in the order given. Costs $0.01 per call; nothing if it fails.", "tags": ["documents"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_ids": {"type": "array", "items": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file in the store (files_upload or files_list give its file_id)."}, "minItems": 2, "maxItems": 50}, "name": {"type": "string", "minLength": 1, "maxLength": 200, "description": "Name for the new file, e.g. \"Quote 1042.pdf\"."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24}}, "required": ["file_ids", "name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/documents_read_pdf": {"post": {"operationId": "documents_read_pdf", "summary": "Read a PDF", "description": "The text of a PDF in the store, page by page (up to 50 pages a call; ask for later pages with first_page). Scanned pages without a text layer come back empty: files_ocr reads them ($0.005 a page). Free.", "tags": ["documents"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file in the store (files_upload or files_list give its file_id)."}, "first_page": {"type": "integer", "minimum": 1, "default": 1}, "last_page": {"type": "integer", "minimum": 1}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/documents_page_images": {"post": {"operationId": "documents_page_images", "summary": "See the pages of a scan", "description": "The pages of a scanned PDF or a photo of a document (a receipt, a letter, a signed form) as images for you to read yourself, with any text the PDF already has. Up to 10 pages a call; ask for later pages with first_page. files_ocr turns a scan's printed words into text instead ($0.005 a page); for PDFs with text, documents_read_pdf is free. Costs $0.005 per call; nothing if it fails.", "tags": ["documents"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file in the store (files_upload or files_list give its file_id)."}, "first_page": {"type": "integer", "minimum": 1, "default": 1}, "last_page": {"type": "integer", "minimum": 1}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_create_inbox": {"post": {"operationId": "email_create_inbox", "summary": "Create an inbox", "description": "A new email address for the business on its own subdomain, e.g. support@acme.useconecto.com. It can send and receive at once. With open_tickets=true it is a support inbox: every new email to it opens a help desk ticket (see ticket_connect_inbox). With save_attachments=true, attachments of mail it receives go to the file store (email-in, e.g. invoices@ for supplier bills). Rented at $1.00 a month, renewed from the balance; the first month is this call. Costs $1.00 per call; nothing if it fails.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"local_part": {"type": "string", "minLength": 1, "maxLength": 40, "description": "The part before the @, e.g. \"support\" or \"sales\"."}, "display_name": {"type": "string", "maxLength": 120, "description": "Shown as the sender name."}, "open_tickets": {"type": "boolean", "default": false, "description": "New mail opens a help desk ticket; ticket replies go out from here."}, "save_attachments": {"type": "boolean", "description": "Email-in: save each attachment of mail received here to the file store, linked to its email (files.added tells you, with its text). The store's space counts; when it is full an attachment is skipped and the email says so. Anyone can write to an inbox, so it saves at most save_files_per_day files and save_mb_per_day MB in 24 hours (100 and 250 by default); past that the email still arrives with its attachments listed as not saved.", "default": false}}, "required": ["local_part"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_update_inbox": {"post": {"operationId": "email_update_inbox", "summary": "Change an inbox", "description": "Change an inbox's sender name, switch email-in on or off (save_attachments saves each attachment of mail received from now on to the file store, linked to its email), or raise or lower what email-in saves in 24 hours (save_files_per_day, save_mb_per_day). $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"inbox": {"type": "string", "maxLength": 254}, "display_name": {"type": "string", "maxLength": 120}, "save_attachments": {"type": "boolean", "description": "Email-in: save each attachment of mail received here to the file store, linked to its email (files.added tells you, with its text). The store's space counts; when it is full an attachment is skipped and the email says so. Anyone can write to an inbox, so it saves at most save_files_per_day files and save_mb_per_day MB in 24 hours (100 and 250 by default); past that the email still arrives with its attachments listed as not saved."}, "save_files_per_day": {"type": "integer", "minimum": 1, "maximum": 1000, "description": "Email-in: the most attachments saved in 24 hours. Default 100."}, "save_mb_per_day": {"type": "integer", "minimum": 1, "maximum": 2500, "description": "Email-in: the most MB of attachments saved in 24 hours. Default 250."}}, "required": ["inbox"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_list_inboxes": {"post": {"operationId": "email_list_inboxes", "summary": "List inboxes", "description": "This account's inboxes, whether each opens help desk tickets or saves attachments to the file store, and when each renews. Free.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_release_inbox": {"post": {"operationId": "email_release_inbox", "summary": "Release an inbox", "description": "Stop renting an inbox. Mail sent to it afterwards bounces; its stored messages stay readable. Free.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"inbox": {"type": "string", "maxLength": 254}}, "required": ["inbox"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_send": {"post": {"operationId": "email_send", "summary": "Send an email", "description": "Send from one of this account's inboxes. Give reply_to_message_id to answer a received message in the same thread. attachments: up to 10 files of the file store, 25 MB together. Up to 20 recipients. For support, operations and replies, not cold outreach: at most 20 new addresses a day, never first to an address found with Conecto's lookups; free credit can't email outsiders. An email to someone who never wrote first is checked before it goes: one that looks like cold outreach isn't sent, and the third within 7 days pauses the account's email. Unless by_person, a last line says the business's AI assistant wrote it. Big files are cheaper as a download link (files_get) in the text. Costs $0.001 per recipient, plus $0.001 per started MB of attachments for each recipient ($0.001 to one person without attachments; at most $0.52 a call); nothing if it fails.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"inbox": {"type": "string", "maxLength": 254}, "to": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "string", "maxLength": 254}}, "cc": {"type": "array", "maxItems": 19, "items": {"type": "string", "maxLength": 254}}, "subject": {"type": "string", "maxLength": 500}, "text": {"type": "string", "maxLength": 100000}, "html": {"type": "string", "maxLength": 300000}, "reply_to_message_id": {"type": "string", "minLength": 36, "maxLength": 36}, "attachments": {"type": "array", "maxItems": 10, "items": {"type": "string", "minLength": 36, "maxLength": 36}, "description": "File ids from the file store (files_list), up to 10 files and 25 MB together."}, "by_person": {"type": "boolean", "default": false, "description": "true when a person at the business wrote it. Otherwise a last line says the business's AI assistant wrote it (EU AI Act Art. 50)."}}, "required": ["inbox", "to", "text"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_save_attachments": {"post": {"operationId": "email_save_attachments", "summary": "Save an email's attachments", "description": "Save the attachments of one received email into the file store, each linked to the email, then read them like any file (files_read_text, documents_read_pdf, files_ocr). Ones saved before are kept, not saved again. Inline pictures (a signature's logo) and mail marked as spam are not saved. $0.001 per file saved; the original email is kept 30 days. Costs $0.001 per file saved; nothing if none are found.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"message_id": {"type": "string", "minLength": 36, "maxLength": 36}}, "required": ["message_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_list_messages": {"post": {"operationId": "email_list_messages", "summary": "List messages", "description": "Messages in this account's inboxes, newest first: received, sent or both, optionally for one inbox, one sender or since a time. Free. Free.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"inbox": {"type": "string", "maxLength": 254}, "direction": {"type": "string", "enum": ["in", "out"]}, "from": {"type": "string", "maxLength": 254}, "state": {"type": "string", "enum": ["open", "waiting", "handled", "archived"], "description": "Only messages whose thread is in this state (email_update_thread)."}, "label": {"type": "string", "maxLength": 40, "description": "Only threads with this label."}, "since": {"type": "string", "maxLength": 40, "description": "ISO 8601"}, "query": {"type": "string", "maxLength": 200}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_get_message": {"post": {"operationId": "email_get_message", "summary": "Read a message", "description": "One message in full: text, HTML and attachment names. Free. Free.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"message_id": {"type": "string", "minLength": 36, "maxLength": 36}}, "required": ["message_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_get_thread": {"post": {"operationId": "email_get_thread", "summary": "Read a thread", "description": "Every message in the same conversation, oldest first. Free. Free.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"message_id": {"type": "string", "minLength": 36, "maxLength": 36}}, "required": ["message_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_update_thread": {"post": {"operationId": "email_update_thread", "summary": "Mark where a thread stands", "description": "Mark an email thread open (needs a reply), waiting (on the other side), handled or archived, and set its labels, so you never reread or answer twice what you already dealt with: email_list_messages filters by state and label. A new message from outside opens a thread again. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["email"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"message_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "Any message of the thread."}, "state": {"type": "string", "enum": ["open", "waiting", "handled", "archived"]}, "labels": {"type": "array", "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 40}, "description": "Replaces the thread's labels."}}, "required": ["message_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_send": {"post": {"operationId": "esign_send", "summary": "Send for signature", "description": "Send a PDF from the file store to up to 10 people to sign. Each gets an email with their own link, signs in the browser by drawing or typing, and everyone gets the signed PDF with a signing certificate. Without fields, a signature page with a signature and date line per signer is added at the end. With fields, place them yourself: page, x, y, width and height in percent of the page from its top-left corner (a signature field of about 30 x 5 fits a line). Every signer needs a signature field. Signers are emailed at once (parallel) or one after another (sequential). Emailing people outside the business needs an account that has topped up once. You hear how it goes as events (account_events, or a channel from notify_subscribe): esign.signed after each signature that leaves others to sign, naming who is left, esign.completed when everyone has signed, and esign.declined if someone declines. Costs $0.50 per call; nothing if it fails.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A PDF in the file store."}, "title": {"type": "string", "minLength": 1, "maxLength": 200, "description": "What signers see, e.g. \"Service agreement\"."}, "signers": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "object", "additionalProperties": false, "required": ["name", "email"], "properties": {"name": {"type": "string", "maxLength": 120}, "email": {"type": "string", "maxLength": 254}}}}, "fields": {"type": "array", "maxItems": 300, "items": {"type": "object", "additionalProperties": false, "required": ["signer", "kind", "page", "x", "y", "width", "height"], "properties": {"signer": {"type": "integer", "minimum": 1, "description": "The signer's number in the signers list, from 1."}, "kind": {"type": "string", "enum": ["signature", "initials", "name", "date", "text", "checkbox"]}, "page": {"type": "integer", "minimum": 1}, "x": {"type": "number", "description": "Left edge, in percent of the page width from the left."}, "y": {"type": "number", "description": "Top edge, in percent of the page height from the top."}, "width": {"type": "number", "description": "In percent of the page width."}, "height": {"type": "number", "description": "In percent of the page height."}, "required": {"type": "boolean", "description": "Default true (false for checkboxes)."}, "label": {"type": "string", "maxLength": 120, "description": "Shown to the signer, e.g. \"Company name\"."}}}}, "message": {"type": "string", "maxLength": 2000, "description": "A note to the signers, shown in the email and on the signing page."}, "order": {"type": "string", "enum": ["parallel", "sequential"], "default": "parallel"}, "expires_in_days": {"type": "integer", "minimum": 1, "maximum": 90, "default": 30}}, "required": ["file_id", "title", "signers"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_get": {"post": {"operationId": "esign_get", "summary": "Get a signature request", "description": "Where a signature request stands: each signer's status (waiting, to sign, opened, signed, declined), and once everyone has signed, the signed PDF with its download link. Free.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"request_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The request_id esign_send returned."}}, "required": ["request_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_list": {"post": {"operationId": "esign_list", "summary": "List signature requests", "description": "Signature requests, newest first, optionally only those with one status. Free.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["sent", "completed", "declined", "cancelled", "expired"]}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_signing_link": {"post": {"operationId": "esign_signing_link", "summary": "Get a signer's link", "description": "The signing link of one signer, to hand over yourself (in a chat, say). Anyone with the link can sign as that person, so give it only to them. Free.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"request_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The request_id esign_send returned."}, "email": {"type": "string", "maxLength": 254}}, "required": ["request_id", "email"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_remind": {"post": {"operationId": "esign_remind", "summary": "Remind signers", "description": "Email everyone who still has to sign a reminder with their link. At most once a day per request. Costs $0.02 per call; nothing if it fails.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"request_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The request_id esign_send returned."}}, "required": ["request_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_cancel": {"post": {"operationId": "esign_cancel", "summary": "Cancel a signature request", "description": "Stop a request before everyone has signed. Signers who were asked get a short email saying nothing is needed any more; their links stop working. Free.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"request_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The request_id esign_send returned."}, "reason": {"type": "string", "maxLength": 300}}, "required": ["request_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_save_template": {"post": {"operationId": "esign_save_template", "summary": "Save a document as a template", "description": "Save a PDF from the file store once, with its fields placed per signer role (page, x, y, width and height in percent of the page, as in esign_send), so contracts, NDAs and waivers go out later without placing a field again. roles names who signs, in order; every role needs a signature field. Saving a name again replaces it. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 2, "maxLength": 60, "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$", "description": "The template's name, like service-agreement."}, "file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A PDF in the file store."}, "title": {"type": "string", "minLength": 1, "maxLength": 200, "description": "What signers see, e.g. \"Service agreement\"."}, "roles": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "string", "minLength": 1, "maxLength": 60}, "description": "Who signs, in order, e.g. [\"Customer\", \"Hansen & Voss\"]."}, "fields": {"type": "array", "minItems": 1, "maxItems": 300, "items": {"type": "object", "additionalProperties": false, "required": ["role", "kind", "page", "x", "y", "width", "height"], "properties": {"kind": {"type": "string", "enum": ["signature", "initials", "name", "date", "text", "checkbox"]}, "page": {"type": "integer", "minimum": 1}, "x": {"type": "number", "description": "Left edge, in percent of the page width from the left."}, "y": {"type": "number", "description": "Top edge, in percent of the page height from the top."}, "width": {"type": "number", "description": "In percent of the page width."}, "height": {"type": "number", "description": "In percent of the page height."}, "required": {"type": "boolean", "description": "Default true (false for checkboxes)."}, "label": {"type": "string", "maxLength": 120, "description": "Shown to the signer, e.g. \"Company name\"."}, "role": {"type": "integer", "minimum": 1, "description": "Whose field: the role's number in roles, from 1."}}}}, "message": {"type": "string", "maxLength": 2000, "description": "The note to signers each time."}, "order": {"type": "string", "enum": ["parallel", "sequential"], "default": "parallel"}, "expires_in_days": {"type": "integer", "minimum": 1, "maximum": 90, "default": 30}}, "required": ["name", "file_id", "title", "roles", "fields"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_list_templates": {"post": {"operationId": "esign_list_templates", "summary": "List templates", "description": "The saved templates: their names, titles, roles and fields. Free.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_send_template": {"post": {"operationId": "esign_send_template", "summary": "Send a template for signature", "description": "Send a saved template to new signers, one per role in the template's order: signers for one request, or sets for up to 50 at once (one request each, e.g. the same NDA to every new contractor). Each works like esign_send: emails, links, the signed PDF with its certificate. Emailing people outside the business needs an account that has topped up once. $0.50 per request sent. Costs $0.50 per request sent; nothing if none are found.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"template": {"type": "string", "minLength": 2, "maxLength": 60, "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$", "description": "The template's name, like service-agreement."}, "signers": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "object", "additionalProperties": false, "required": ["name", "email"], "properties": {"name": {"type": "string", "maxLength": 120}, "email": {"type": "string", "maxLength": 254}}}}, "sets": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "object", "additionalProperties": false, "required": ["name", "email"], "properties": {"name": {"type": "string", "maxLength": 120}, "email": {"type": "string", "maxLength": 254}}}}, "description": "Several requests at once: each set is one request's signers."}, "title": {"type": "string", "maxLength": 200, "description": "Instead of the template's title."}, "message": {"type": "string", "maxLength": 2000, "description": "Instead of the template's note."}, "expires_in_days": {"type": "integer", "minimum": 1, "maximum": 90}}, "required": ["template"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/esign_delete_template": {"post": {"operationId": "esign_delete_template", "summary": "Delete a template", "description": "Delete a saved template. Requests already sent from it are not touched. Free.", "tags": ["esign"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"template": {"type": "string", "minLength": 2, "maxLength": 60, "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$", "description": "The template's name, like service-agreement."}}, "required": ["template"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_upload": {"post": {"operationId": "files_upload", "summary": "Upload a file", "description": "Store a file in the account's private file store and get a download link for it. Give exactly one of: content_base64 (the bytes, or a data: URL), text (for text files: Markdown, CSV, JSON...), or url (a public https link we fetch). Inline content is limited to 1.5 MB; for bigger files (up to 25 MB) use files_upload_link. 1 GB of storage is free. duplicate_of names a stored file with the same bytes; the upload is kept anyway. Costs $0.001 per call; nothing if it fails.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 200, "description": "File name, e.g. \"quote.pdf\"."}, "content_base64": {"type": "string", "maxLength": 2100000}, "text": {"type": "string", "maxLength": 1500000}, "url": {"type": "string", "maxLength": 2000, "description": "A public https:// link to the file."}, "content_type": {"type": "string", "maxLength": 120, "description": "e.g. \"application/pdf\". Guessed from the name when left out."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the download link works, in hours (up to 168, one week)."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_upload_link": {"post": {"operationId": "files_upload_link", "summary": "Get an upload link", "description": "A one-time link to upload one file of up to 25 MB as the raw request body, e.g. `curl -T report.pdf \"<upload_url>\"` (PUT). Works for an hour. Free to ask for; the upload itself costs $0.001 when it arrives and replies with the file and its download link. Hand it to a person to send you a document: files.added tells you when it arrives, with its text once read. Free.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 200}, "content_type": {"type": "string", "maxLength": 120}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_list": {"post": {"operationId": "files_list", "summary": "Find files", "description": "The account's files, each with its title, tags, type, correspondent, document date, fields, text status and a fresh download link; newest first unless sort says otherwise (added, document_date, title). Filters: name_contains (name or title), words (in the file's text, every one; scans once read), tags (all of them, or any with tags_match \"any\"), untagged, document_type, correspondent, the document date from-to, fields ([{field, value | min | max | empty}]: text and links contain the value, numbers, money and dates match it or fall in min-max), has_text (true: Conecto has its words; false: not, e.g. scans not read yet), source (email for email-in). Free.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name_contains": {"type": "string", "maxLength": 100}, "words": {"type": "string", "maxLength": 200, "description": "Words in the file's text."}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 60}}, "tags_match": {"type": "string", "enum": ["all", "any"], "default": "all"}, "untagged": {"type": "boolean", "default": false}, "document_type": {"type": "string", "maxLength": 60}, "correspondent": {"type": "string", "maxLength": 200}, "date_from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Document date on or after, YYYY-MM-DD."}, "date_to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Document date on or before, YYYY-MM-DD."}, "fields": {"type": "array", "maxItems": 10, "items": {"type": "object", "additionalProperties": false, "required": ["field"], "properties": {"field": {"type": "string", "minLength": 1, "maxLength": 60}, "value": {"type": ["string", "number", "boolean"], "maxLength": 2000}, "min": {"type": ["string", "number", "boolean"], "maxLength": 2000}, "max": {"type": ["string", "number", "boolean"], "maxLength": 2000}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$"}, "empty": {"type": "boolean", "description": "true: files without a value; false: with one."}}}}, "has_text": {"type": "boolean"}, "source": {"type": "string", "enum": ["upload", "url", "link", "tool", "email", "phone", "export"]}, "sort": {"type": "string", "enum": ["added", "document_date", "title"], "default": "added"}, "order": {"type": "string", "enum": ["asc", "desc"]}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}, "offset": {"type": "integer", "minimum": 0, "default": 0}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the download link works, in hours (up to 168, one week)."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_get": {"post": {"operationId": "files_get", "summary": "Get a file", "description": "One file's details (title, tags, type, correspondent, document date, notes, fields, where it came from, whether Conecto has read its words) and a fresh download link. With include_text, a text file (Markdown, CSV, JSON...) of up to 200 KB also comes back as it is; files_read_text returns the words of any file, scans included once read. Free.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The file_id files_upload returned."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the download link works, in hours (up to 168, one week)."}, "include_text": {"type": "boolean", "default": false}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_delete": {"post": {"operationId": "files_delete", "summary": "Delete a file", "description": "Delete a file for good. Every download link to it stops working. Free.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The file_id files_upload returned."}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_add_storage": {"post": {"operationId": "files_add_storage", "summary": "Add 10 GB of storage", "description": "Rent 10 GB more file storage at $1 a month, renewed from the balance; the first month is this call. The first 1 GB is free. Costs $1.00 per call; nothing if it fails.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_remove_storage": {"post": {"operationId": "files_remove_storage", "summary": "Remove 10 GB of storage", "description": "Stop renting one 10 GB block. Refused while the files would no longer fit; delete files first. Free.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_edit": {"post": {"operationId": "files_edit", "summary": "Say what files are", "description": "Set what one file is, or up to 100 at once, all or none: title, notes, document_date (the date on the document), correspondent (who it is from or to; made the first time a file names it), document_type, tags (replace them all; [] clears), add_tags, remove_tags, and fields ({\"Total\": \"EUR 119.00\", \"Due\": \"2026-11-01\"}; null clears one). null clears title, notes, the date, the correspondent or the type. Types, tags and fields must be defined first (files_define). Conecto never files anything on its own: you decide what each file is. $0.005 per file changed. Costs $0.005 per file changed; nothing if none are found.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_ids": {"type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The file_id files_upload returned."}}, "title": {"type": ["string", "null"], "maxLength": 300}, "notes": {"type": ["string", "null"], "maxLength": 20000}, "document_date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null."}, "correspondent": {"type": ["string", "null"], "maxLength": 200}, "document_type": {"type": ["string", "null"], "maxLength": 60}, "tags": {"type": "array", "maxItems": 50, "items": {"type": "string", "minLength": 1, "maxLength": 60}}, "add_tags": {"type": "array", "maxItems": 50, "items": {"type": "string", "minLength": 1, "maxLength": 60}}, "remove_tags": {"type": "array", "maxItems": 50, "items": {"type": "string", "minLength": 1, "maxLength": 60}}, "fields": {"type": "object", "maxProperties": 50, "propertyNames": {"minLength": 1, "maxLength": 60}, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 2000}}}, "required": ["file_ids"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_define": {"post": {"operationId": "files_define", "summary": "Define a tag, type, field or correspondent", "description": "Add, rename or delete one of the account's own ways to file things: a tag, a document_type (Invoice, Contract, Receipt), a custom field (field_type: text, number, money, date, boolean (yes/no) or url; a money field has a default currency) or a correspondent (link it to a CRM company_id or contact_id). Matched by name, any case. Deleting takes it off every file (a field's values go with it). $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["tag", "document_type", "field", "correspondent"]}, "name": {"type": "string", "minLength": 1, "maxLength": 200}, "new_name": {"type": "string", "maxLength": 200}, "field_type": {"type": "string", "enum": ["text", "number", "money", "date", "boolean", "url"]}, "currency": {"type": ["string", "null"], "pattern": "^[A-Za-z]{3}$", "description": "A money field's currency for values given without one."}, "company_id": {"type": ["integer", "null"], "minimum": 1}, "contact_id": {"type": ["integer", "null"], "minimum": 1}, "delete": {"type": "boolean", "default": false}}, "required": ["kind", "name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_definitions": {"post": {"operationId": "files_definitions", "summary": "List tags, types, fields and correspondents", "description": "Everything the account defined to file things, each with how many files use it: tags, document types, custom fields (with their type), correspondents (with their CRM links), and how scans are read (auto-OCR, languages). Free.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_read_text": {"post": {"operationId": "files_read_text", "summary": "Read a file's words", "description": "The words in a file as Conecto read them: text files, PDFs with a text layer, Word, Excel, PowerPoint, OpenDocument and HTML files, and scans once read with OCR (files_ocr). Up to max_chars from offset; next_offset gives the rest. status: read, reading (ask again in a minute), scan (an image or a PDF without text: files_ocr reads it), unpaid (auto-OCR could not be paid), none (no words to read) or failed. Free.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The file_id files_upload returned."}, "offset": {"type": "integer", "minimum": 0, "default": 0}, "max_chars": {"type": "integer", "minimum": 1, "maximum": 200000, "default": 50000}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_ocr": {"post": {"operationId": "files_ocr", "summary": "Read a scan with OCR", "description": "Read the words in a scan with OCR (Tesseract): an image (PNG, JPEG, TIFF, WebP) or the pages of a PDF that have no text of their own, up to 100 pages (pages with text keep it). The text is kept: files_read_text and account_search find it afterwards, free. languages: up to 3 (default: the account's, see files_ocr_settings). max_pages is the most this call may read; it holds $0.005 for each until the reading is done, then charges the pages read. OCR reads what is printed; making sense of it is your work. Costs $0.005 per page read; nothing if none are found. Runs in the background: the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The file_id files_upload returned."}, "languages": {"type": "array", "maxItems": 3, "uniqueItems": true, "items": {"type": "string", "enum": ["eng", "deu", "fra", "spa", "ita", "nld", "por", "swe"]}, "description": "Up to 3 of eng, deu, fra, spa, ita, nld, por, swe."}, "max_pages": {"type": "integer", "minimum": 1, "maximum": 100, "default": 100}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}, "202": {"description": "Started; poll /v1/calls/{call_id}.", "content": {"application/json": {"schema": {"type": "object"}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/files_ocr_settings": {"post": {"operationId": "files_ocr_settings", "summary": "Set how scans are read", "description": "auto_ocr: read every new scan (an image, or a PDF without text) with OCR as it arrives, $0.005 a page, charged from the balance; a scan the balance can't cover stays unread and says why. Off by default: scans are then read when you ask (files_ocr). languages: the ones OCR reads in, up to 3 ([] goes back to the account's language: its website's, else its country's, else English). $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["files"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"auto_ocr": {"type": "boolean"}, "languages": {"type": "array", "maxItems": 3, "uniqueItems": true, "items": {"type": "string", "enum": ["eng", "deu", "fra", "spa", "ita", "nld", "por", "swe"]}, "description": "Up to 3 of eng, deu, fra, spa, ita, nld, por, swe."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_create": {"post": {"operationId": "forms_create", "summary": "Create a form", "description": "Create a form or survey with its own public page at https://cncto.co/f/<slug>, which anyone can open and answer; share that link. Field types: short_text, long_text, email, phone (default_country), url, number (min, max, integer), choice and multi_choice (options; multi_choice also min_selections, max_selections), rating (scale 3 to 10, default 5; low_label, high_label), nps (0 to 10; low_label, high_label), date (include_time for a time too, range for a first and a last day, earliest and latest as \"2026-11-01\" or \"today\", \"today+7\", \"today-30\"; answers read 2026-11-03, 2026-11-03T09:30, 2026-11-03/2026-11-07), yes_no, consent (a checkbox; its label may hold one link written [text](https://...)), statement (text only, no answer). Every field takes type, label, help, required, an id (generated from the label when left out; answers are keyed by it) and show_if {\"field\": \"<an earlier field's id>\", \"equals\": <answer>} to show it only when that answer was given. Each response received costs $0.01, up to 10,000 a month per account. Costs $0.01 per call; nothing if it fails.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "minLength": 1, "maxLength": 200}, "fields": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "required": ["type"], "properties": {"id": {"type": "string", "pattern": "^[a-z0-9_]{1,40}$", "description": "Stable id; answers are keyed by it. Generated from the label when left out. Pass it back when you change the form, or a renamed field becomes a new one."}, "type": {"type": "string", "enum": ["short_text", "long_text", "email", "phone", "url", "number", "choice", "multi_choice", "rating", "nps", "date", "yes_no", "consent", "statement"]}, "label": {"type": "string", "maxLength": 1000, "description": "The question. A statement's label is the text it shows. A consent label may hold one link: \"I agree to the [terms](https://acme.com/terms)\"."}, "help": {"type": "string", "maxLength": 2000, "description": "Smaller text under the question."}, "include_time": {"type": "boolean", "description": "date: a time too (answers like 2026-11-03T09:30)."}, "range": {"type": "boolean", "description": "date: a first and a last day (2026-11-03/2026-11-07)."}, "earliest": {"type": ["string", "null"], "maxLength": 20, "description": "date: the first day that can be picked: \"2026-11-01\", \"today\", \"today+1\"."}, "latest": {"type": ["string", "null"], "maxLength": 20, "description": "date: the last day that can be picked: \"2026-12-31\", \"today+60\", \"today\"."}, "required": {"type": "boolean", "default": false}, "placeholder": {"type": "string", "maxLength": 200, "description": "short_text, long_text, email, phone, url and number only."}, "default_country": {"type": ["string", "null"], "minLength": 2, "maxLength": 2, "description": "phone: the country of numbers typed without a +, like \"US\"."}, "min": {"type": ["number", "null"], "description": "number: the smallest answer."}, "max": {"type": ["number", "null"], "description": "number: the largest answer."}, "integer": {"type": "boolean", "description": "number: whole numbers only."}, "options": {"type": "array", "minItems": 1, "maxItems": 100, "description": "choice and multi_choice: [\"Basic\", \"Pro\"], or [{\"id\": \"basic\", \"label\": \"Basic\"}] to keep ids stable when you rename an option.", "items": {"type": ["string", "object"]}}, "min_selections": {"type": ["integer", "null"], "minimum": 1, "description": "multi_choice: the fewest options."}, "max_selections": {"type": ["integer", "null"], "minimum": 1, "description": "multi_choice: the most options."}, "scale": {"type": "integer", "minimum": 3, "maximum": 10, "description": "rating: 3 to 10 (default 5)."}, "low_label": {"type": "string", "maxLength": 60, "description": "rating and nps: words under the lowest score."}, "high_label": {"type": "string", "maxLength": 60, "description": "rating and nps: words under the top score."}, "show_if": {"type": ["object", "null"], "required": ["field", "equals"], "additionalProperties": false, "description": "Show this field only when an earlier field has this answer (for multi_choice: when that option is among the choices). A hidden field is never required.", "properties": {"field": {"type": "string", "description": "An earlier field's id."}, "equals": {"description": "The answer that shows the field: an option id (choice, multi_choice), true or false (yes_no, consent), a number (number, rating, nps), a date (date) or text (short_text, email)."}}}}}, "description": "The questions in order. When changing a form, this replaces the whole list."}, "description": {"type": "string", "maxLength": 2000, "description": "Shown under the title."}, "submit_label": {"type": "string", "minLength": 1, "maxLength": 40, "description": "The button's words (default \"Submit\")."}, "thank_you_title": {"type": "string", "minLength": 1, "maxLength": 120, "description": "Shown after sending (default \"Thank you\")."}, "thank_you_message": {"type": "string", "maxLength": 1000}, "redirect_url": {"type": ["string", "null"], "maxLength": 2000, "description": "An https:// page to send people to after they submit. Empty or null: none."}, "close_at": {"type": ["string", "null"], "maxLength": 40, "description": "Stop taking responses at this time (ISO 8601, like 2026-12-31T23:59:00Z; UTC when no offset is given). Empty or null: never."}, "max_responses": {"type": ["integer", "null"], "minimum": 0, "maximum": 1000000, "description": "Stop after this many responses. 0 or null: no limit."}, "notify_email": {"type": ["string", "null"], "maxLength": 254, "description": "Email this address about new responses: at most one email a minute per form, later responses grouped into the next one. Free credit can only notify the owner's email. Empty or null: off."}, "confirm_to_respondent": {"type": "boolean", "description": "Email each respondent their answers in the brand kit (form_confirmation wording), to the address they typed in the first email field. $0.002 each; paid accounts only; at most three a day to one address."}, "on_response": {"type": "array", "maxItems": 3, "description": "What each response also does on its own, while you are away ($0.01 per action done): {\"action\": \"open_ticket\", \"priority\": \"normal\"} opens a help desk ticket for the respondent; {\"action\": \"create_deal\", \"pipeline\": \"Sales\", \"stage\": \"New\", \"amount_field\": \"budget\"} creates a deal with them as contact; {\"action\": \"add_row\", \"table\": \"Leads\", \"columns\": {\"Email\": \"email\", \"Budget\": \"budget\"}} adds a row, each column from a field id. [] or null: none.", "items": {"type": "object", "required": ["action"], "properties": {"action": {"type": "string", "enum": ["open_ticket", "create_deal", "add_row"]}, "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"]}, "pipeline": {"type": "string", "maxLength": 80}, "stage": {"type": "string", "maxLength": 80}, "amount_field": {"type": "string", "maxLength": 40}, "table": {"type": "string", "maxLength": 80}, "columns": {"type": "object"}}}}, "save_to_crm": {"type": "boolean", "description": "Save the person behind each response as a CRM contact. The first email field is the email; a short_text field with id name or full_name (or first_name and last_name) is the name; the first phone field the phone. An existing contact only gets empty fields filled."}, "hidden_fields": {"type": "array", "maxItems": 10, "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$"}, "description": "Link values kept with each response: [\"ref\", \"utm_source\"] keeps them from https://cncto.co/f/<slug>?ref=abc&utm_source=newsletter."}}, "required": ["title", "fields"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_update": {"post": {"operationId": "forms_update", "summary": "Change a form", "description": "Change a form's fields or settings; only what you pass changes. fields replaces the whole list: pass each existing field's id (forms_get shows them) so its answers stay attached, even when you rename it. Answers to fields or options you remove stay readable in responses, exports and summaries. A field that already has answers keeps its type (short_text and long_text may switch). Empty or null clears redirect_url, close_at and notify_email; max_responses 0 or null removes the limit. Costs $0.01 per call; nothing if it fails.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The form's form_id or slug (forms_list shows both)."}, "title": {"type": "string", "minLength": 1, "maxLength": 200}, "fields": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "required": ["type"], "properties": {"id": {"type": "string", "pattern": "^[a-z0-9_]{1,40}$", "description": "Stable id; answers are keyed by it. Generated from the label when left out. Pass it back when you change the form, or a renamed field becomes a new one."}, "type": {"type": "string", "enum": ["short_text", "long_text", "email", "phone", "url", "number", "choice", "multi_choice", "rating", "nps", "date", "yes_no", "consent", "statement"]}, "label": {"type": "string", "maxLength": 1000, "description": "The question. A statement's label is the text it shows. A consent label may hold one link: \"I agree to the [terms](https://acme.com/terms)\"."}, "help": {"type": "string", "maxLength": 2000, "description": "Smaller text under the question."}, "include_time": {"type": "boolean", "description": "date: a time too (answers like 2026-11-03T09:30)."}, "range": {"type": "boolean", "description": "date: a first and a last day (2026-11-03/2026-11-07)."}, "earliest": {"type": ["string", "null"], "maxLength": 20, "description": "date: the first day that can be picked: \"2026-11-01\", \"today\", \"today+1\"."}, "latest": {"type": ["string", "null"], "maxLength": 20, "description": "date: the last day that can be picked: \"2026-12-31\", \"today+60\", \"today\"."}, "required": {"type": "boolean", "default": false}, "placeholder": {"type": "string", "maxLength": 200, "description": "short_text, long_text, email, phone, url and number only."}, "default_country": {"type": ["string", "null"], "minLength": 2, "maxLength": 2, "description": "phone: the country of numbers typed without a +, like \"US\"."}, "min": {"type": ["number", "null"], "description": "number: the smallest answer."}, "max": {"type": ["number", "null"], "description": "number: the largest answer."}, "integer": {"type": "boolean", "description": "number: whole numbers only."}, "options": {"type": "array", "minItems": 1, "maxItems": 100, "description": "choice and multi_choice: [\"Basic\", \"Pro\"], or [{\"id\": \"basic\", \"label\": \"Basic\"}] to keep ids stable when you rename an option.", "items": {"type": ["string", "object"]}}, "min_selections": {"type": ["integer", "null"], "minimum": 1, "description": "multi_choice: the fewest options."}, "max_selections": {"type": ["integer", "null"], "minimum": 1, "description": "multi_choice: the most options."}, "scale": {"type": "integer", "minimum": 3, "maximum": 10, "description": "rating: 3 to 10 (default 5)."}, "low_label": {"type": "string", "maxLength": 60, "description": "rating and nps: words under the lowest score."}, "high_label": {"type": "string", "maxLength": 60, "description": "rating and nps: words under the top score."}, "show_if": {"type": ["object", "null"], "required": ["field", "equals"], "additionalProperties": false, "description": "Show this field only when an earlier field has this answer (for multi_choice: when that option is among the choices). A hidden field is never required.", "properties": {"field": {"type": "string", "description": "An earlier field's id."}, "equals": {"description": "The answer that shows the field: an option id (choice, multi_choice), true or false (yes_no, consent), a number (number, rating, nps), a date (date) or text (short_text, email)."}}}}}, "description": "The questions in order. When changing a form, this replaces the whole list."}, "description": {"type": "string", "maxLength": 2000, "description": "Shown under the title."}, "submit_label": {"type": "string", "minLength": 1, "maxLength": 40, "description": "The button's words (default \"Submit\")."}, "thank_you_title": {"type": "string", "minLength": 1, "maxLength": 120, "description": "Shown after sending (default \"Thank you\")."}, "thank_you_message": {"type": "string", "maxLength": 1000}, "redirect_url": {"type": ["string", "null"], "maxLength": 2000, "description": "An https:// page to send people to after they submit. Empty or null: none."}, "close_at": {"type": ["string", "null"], "maxLength": 40, "description": "Stop taking responses at this time (ISO 8601, like 2026-12-31T23:59:00Z; UTC when no offset is given). Empty or null: never."}, "max_responses": {"type": ["integer", "null"], "minimum": 0, "maximum": 1000000, "description": "Stop after this many responses. 0 or null: no limit."}, "notify_email": {"type": ["string", "null"], "maxLength": 254, "description": "Email this address about new responses: at most one email a minute per form, later responses grouped into the next one. Free credit can only notify the owner's email. Empty or null: off."}, "confirm_to_respondent": {"type": "boolean", "description": "Email each respondent their answers in the brand kit (form_confirmation wording), to the address they typed in the first email field. $0.002 each; paid accounts only; at most three a day to one address."}, "on_response": {"type": "array", "maxItems": 3, "description": "What each response also does on its own, while you are away ($0.01 per action done): {\"action\": \"open_ticket\", \"priority\": \"normal\"} opens a help desk ticket for the respondent; {\"action\": \"create_deal\", \"pipeline\": \"Sales\", \"stage\": \"New\", \"amount_field\": \"budget\"} creates a deal with them as contact; {\"action\": \"add_row\", \"table\": \"Leads\", \"columns\": {\"Email\": \"email\", \"Budget\": \"budget\"}} adds a row, each column from a field id. [] or null: none.", "items": {"type": "object", "required": ["action"], "properties": {"action": {"type": "string", "enum": ["open_ticket", "create_deal", "add_row"]}, "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"]}, "pipeline": {"type": "string", "maxLength": 80}, "stage": {"type": "string", "maxLength": 80}, "amount_field": {"type": "string", "maxLength": 40}, "table": {"type": "string", "maxLength": 80}, "columns": {"type": "object"}}}}, "save_to_crm": {"type": "boolean", "description": "Save the person behind each response as a CRM contact. The first email field is the email; a short_text field with id name or full_name (or first_name and last_name) is the name; the first phone field the phone. An existing contact only gets empty fields filled."}, "hidden_fields": {"type": "array", "maxItems": 10, "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$"}, "description": "Link values kept with each response: [\"ref\", \"utm_source\"] keeps them from https://cncto.co/f/<slug>?ref=abc&utm_source=newsletter."}}, "required": ["form"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_get": {"post": {"operationId": "forms_get", "summary": "Get a form", "description": "One form with its fields, settings, public link, whether it is taking responses (and why not), its response count, and this account's monthly allowance of received responses. Free.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The form's form_id or slug (forms_list shows both)."}}, "required": ["form"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_list": {"post": {"operationId": "forms_list", "summary": "List forms", "description": "The account's forms, newest first, with their public links, whether each is taking responses, and their response counts. Free.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["open", "closed", "any"], "default": "any"}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_close": {"post": {"operationId": "forms_close", "summary": "Close a form", "description": "Stop a form taking responses; its page then says it is closed. forms_open reopens it. Costs $0.001 per call; nothing if it fails.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The form's form_id or slug (forms_list shows both)."}}, "required": ["form"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_open": {"post": {"operationId": "forms_open", "summary": "Reopen a form", "description": "Let a closed form take responses again. A closing date that has passed is cleared; a form that reached max_responses stays full until you raise it with forms_update. Costs $0.001 per call; nothing if it fails.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The form's form_id or slug (forms_list shows both)."}}, "required": ["form"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_delete": {"post": {"operationId": "forms_delete", "summary": "Delete a form", "description": "Delete a form and all its responses for good; its link stops working. Exported files stay in the file store. Costs $0.001 per call; nothing if it fails.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The form's form_id or slug (forms_list shows both)."}}, "required": ["form"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_delete_response": {"post": {"operationId": "forms_delete_response", "summary": "Delete a response", "description": "Delete one response for good, for a person who asks to be forgotten or for spam. Exported CSV files keep their copy until you delete them too. Free.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"response_id": {"type": "string", "minLength": 32, "maxLength": 36}}, "required": ["response_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_list_responses": {"post": {"operationId": "forms_list_responses", "summary": "List responses", "description": "A form's responses, newest first: for each answer the question, the stored value and a readable answer, plus the link values (hidden_fields) and the CRM contact. When next_cursor is not null, call again with it for older responses. Free.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The form's form_id or slug (forms_list shows both)."}, "since": {"type": "string", "maxLength": 40, "description": "Only responses from this time on: ISO 8601 (2026-10-01T00:00:00Z) or a date (2026-10-01, UTC)."}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}, "cursor": {"type": "string", "maxLength": 500, "description": "The next_cursor of the previous page."}}, "required": ["form"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_get_response": {"post": {"operationId": "forms_get_response", "summary": "Get a response", "description": "One response by its response_id, with every answer readable. Free.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"response_id": {"type": "string", "minLength": 32, "maxLength": 36}}, "required": ["response_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_export_responses": {"post": {"operationId": "forms_export_responses", "summary": "Export responses to CSV", "description": "A CSV file of a form's responses in the file store, with a download link: one row per response, oldest first, one column per field in form order, then the link values. Opens in Excel, Numbers and Google Sheets. With since, only responses from then on. Free when there is nothing to export. Costs $0.001 per call; nothing if it fails.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The form's form_id or slug (forms_list shows both)."}, "since": {"type": "string", "maxLength": 40, "description": "Only responses from this time on: ISO 8601 (2026-10-01T00:00:00Z) or a date (2026-10-01, UTC)."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the download link works, in hours (up to 168, one week)."}}, "required": ["form"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/forms_summary": {"post": {"operationId": "forms_summary", "summary": "Summarize responses", "description": "A form's results at a glance: the response count and, per question, choice counts and percentages, rating averages and distributions, the NPS score (percent promoters minus percent detractors), yes and no shares, number minimum, maximum and average, and the 5 latest text answers. With since, only responses from then on. Free.", "tags": ["forms"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"form": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The form's form_id or slug (forms_list shows both)."}, "since": {"type": "string", "maxLength": 40, "description": "Only responses from this time on: ISO 8601 (2026-10-01T00:00:00Z) or a date (2026-10-01, UTC)."}}, "required": ["form"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_overview": {"post": {"operationId": "help_center_overview", "summary": "Help center overview", "description": "Where the help center lives and what is in it: its address, whether it is public, the plan (free shows a \"Powered by Conecto\" badge), whether the draft has unpublished changes, every collection with its article count, the most recently changed articles, and each page’s sections. Start here. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_design_guide": {"post": {"operationId": "help_center_design_guide", "summary": "Design guide", "description": "The whole design language, as data: every theme group and field (type, options, limits, default), every section type with its fields, the page rules, the templates, fonts, collection icons and languages, the CSS classes and variables your own CSS can use and how it is confined, and the blocks an article can contain. Read it once before designing. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_get_design": {"post": {"operationId": "help_center_get_design", "summary": "Get the design", "description": "The full design document: the draft (what you are editing) or what is published, with the draft revision. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"which": {"type": "string", "enum": ["draft", "published"], "default": "draft"}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_update_design": {"post": {"operationId": "help_center_update_design", "summary": "Update the design", "description": "Change the DRAFT design: theme fields (groups merge field by field), whole pages (each page’s full ordered list of sections), your CSS (replaces the previous stylesheet), the help center’s words, or its language. Invalid values are left as they were and named in `warnings`. Nothing is live until help_center_publish. Costs $0.001 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"theme": {"type": "object", "description": "e.g. {\"colors\": {\"accent\": \"#ff5500\"}, \"fonts\": {\"heading\": \"Fraunces\"}}"}, "pages": {"type": "object", "description": "Page -> full list of sections ({id?, type, props, style}). Keep a section’s id to keep it. For one change, help_center_edit_sections is simpler.", "properties": {"home": {"type": "array", "items": {"type": "object"}}, "collection": {"type": "array", "items": {"type": "object"}}, "article": {"type": "array", "items": {"type": "object"}}, "search": {"type": "array", "items": {"type": "object"}}}, "additionalProperties": false}, "css": {"type": "string", "maxLength": 100000}, "labels": {"type": "object", "additionalProperties": {"type": "string"}}, "language": {"type": "string", "enum": ["en", "pt", "es", "fr", "de", "it", "nl", "sv", "no", "da", "uk", "ru", "zh"]}, "rev": {"type": "integer", "description": "The draft revision you last read (from any tool that returns `rev`). If the draft changed since, nothing is saved and you get the current revision to re-read."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_edit_sections": {"post": {"operationId": "help_center_edit_sections", "summary": "Edit page sections", "description": "Add, update, move, duplicate or remove sections on one page of the DRAFT, in order. add: {op:\"add\", type, props?, style?, at?}; update: {op:\"update\", id, props?, style?} (merged into what is there); move: {op:\"move\", id, to}; duplicate / remove: {op, id}. Returns the id of anything added and the page’s new order. Costs $0.001 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"page": {"type": "string", "enum": ["home", "collection", "article", "search"]}, "ops": {"type": "array", "minItems": 1, "maxItems": 30, "items": {"type": "object", "properties": {"op": {"type": "string", "enum": ["add", "update", "move", "duplicate", "remove"]}, "type": {"type": "string"}, "id": {"type": "string"}, "props": {"type": "object"}, "style": {"type": "object"}, "at": {"type": "integer"}, "to": {"type": "integer"}}, "required": ["op"]}}, "rev": {"type": "integer", "description": "The draft revision you last read (from any tool that returns `rev`). If the draft changed since, nothing is saved and you get the current revision to re-read."}}, "required": ["page", "ops"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_apply_template": {"post": {"operationId": "help_center_apply_template", "summary": "Apply a template", "description": "Start the DRAFT over from a built-in template (see the design guide for each one’s look). The owner’s brand (name, logo, accent, website, footer), language, wording, CSS and hero text carry over. Costs $0.001 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"template": {"type": "string", "enum": ["classic", "minimal", "editorial", "docs", "bold", "friendly"]}, "rev": {"type": "integer", "description": "The draft revision you last read (from any tool that returns `rev`). If the draft changed since, nothing is saved and you get the current revision to re-read."}}, "required": ["template"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_preview": {"post": {"operationId": "help_center_preview", "summary": "Preview the draft", "description": "A private link to any page of the DRAFT (works before the help center is public, never indexed), and the page’s HTML if you ask for it, so you can check your work. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"page": {"type": "string", "enum": ["home", "collection", "article", "search"], "default": "home"}, "collection": {"type": "integer", "description": "For page \"collection\"."}, "article": {"type": ["integer", "string"], "description": "Article id or slug, for page \"article\"."}, "query": {"type": "string", "description": "For page \"search\"."}, "html": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_publish": {"post": {"operationId": "help_center_publish", "summary": "Publish the design", "description": "Make the DRAFT design what visitors see. The previous published design is kept as a version the owner can restore. Ask the owner before publishing unless they asked you to. Costs $0.01 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_list_collections": {"post": {"operationId": "help_center_list_collections", "summary": "List collections", "description": "Every collection with its id, icon, description and article count. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_save_collection": {"post": {"operationId": "help_center_save_collection", "summary": "Create or change a collection", "description": "Create a collection (no id) or change one (id): name, a one-line description, an icon from the design guide’s list, and its order among collections. Its address stays the same when it is renamed. Costs $0.01 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string", "maxLength": 120}, "description": {"type": "string", "maxLength": 300}, "icon": {"type": "string"}, "order": {"type": "integer", "minimum": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_delete_collection": {"post": {"operationId": "help_center_delete_collection", "summary": "Delete a collection", "description": "Delete a collection. Its articles stay and move to \"General\". Costs $0.001 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "integer"}}, "required": ["id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_list_articles": {"post": {"operationId": "help_center_list_articles", "summary": "List or search articles", "description": "Articles, newest change first, optionally matching words, in one collection, or only published / only drafts. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "maxLength": 120}, "collection": {"type": "integer"}, "status": {"type": "string", "enum": ["all", "published", "draft"], "default": "all"}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_get_article": {"post": {"operationId": "help_center_get_article", "summary": "Read an article", "description": "One article with its HTML content, by id or slug. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "integer"}, "slug": {"type": "string"}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_save_article": {"post": {"operationId": "help_center_save_article", "summary": "Write an article", "description": "Create an article (no id) or change one (id). Write the body as `markdown` (see the design guide) or `content` HTML. Every change is kept as a revision the owner can restore. Unpublished until published: true. Costs $0.01 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "integer"}, "title": {"type": "string", "maxLength": 255}, "description": {"type": "string", "maxLength": 300, "description": "The line under the title, also used in search results."}, "markdown": {"type": "string"}, "content": {"type": "string"}, "collection": {"type": ["integer", "null"]}, "published": {"type": "boolean"}, "featured": {"type": "boolean"}, "seo_title": {"type": "string", "maxLength": 120}, "seo_description": {"type": "string", "maxLength": 300}, "cover": {"type": ["string", "null"], "description": "An uploaded image path from help_center_upload_image."}, "options": {"type": "object", "properties": {"toc": {"type": "boolean"}, "feedback": {"type": "boolean"}}, "additionalProperties": false}, "slug": {"type": "string"}, "order": {"type": "integer", "minimum": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_delete_article": {"post": {"operationId": "help_center_delete_article", "summary": "Delete an article", "description": "Delete an article for good, with its revisions. Costs $0.001 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "integer"}}, "required": ["id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_upload_image": {"post": {"operationId": "help_center_upload_image", "summary": "Upload an image", "description": "Store an image (logo, header or hero background, article cover, picture for an article) and get the path to use in the design or an article. Give a public https `url`, or the file as base64 `data`. PNG, JPEG, GIF, WebP or SVG, up to 5 MB. Costs $0.01 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"url": {"type": "string", "maxLength": 2000}, "data": {"type": "string"}, "filename": {"type": "string", "maxLength": 120}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_gaps": {"post": {"operationId": "help_center_gaps", "summary": "What visitors could not find", "description": "Questions the help center does not answer yet: searches that found nothing and questions people asked in chat that ended with a handoff to the team. Write articles for the top ones. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"days": {"type": "integer", "minimum": 1, "maximum": 90, "default": 30}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_suggestions": {"post": {"operationId": "help_center_suggestions", "summary": "Suggested articles", "description": "What the help center proposes to write or change, from the team’s own answers (paid plans): new articles and edits waiting for a decision, with why and how sure it is. Read one in full with its id. Free.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "integer", "description": "Read one suggestion in full."}, "status": {"type": "string", "enum": ["pending", "published", "dismissed", "all"], "default": "pending"}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_review_suggestion": {"post": {"operationId": "help_center_review_suggestion", "summary": "Decide on a suggestion", "description": "Publish a suggested article or edit (optionally with your own title, description or Markdown), save it as an unpublished draft, or dismiss it. A dismissed topic is not proposed again for 90 days. Costs $0.001 per call; nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "integer"}, "action": {"type": "string", "enum": ["publish", "draft", "dismiss"]}, "title": {"type": "string", "maxLength": 255}, "description": {"type": "string", "maxLength": 300}, "markdown": {"type": "string"}}, "required": ["id", "action"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/help_center_set_public": {"post": {"operationId": "help_center_set_public", "summary": "Make the help center public", "description": "Open the published help center to everyone (or close it again). Opening it starts its rent, $5 a month from the balance; closing it stops the rent. Publishing the design is a separate step: help_center_publish. Costs $5 a month while the help center is public, $0.001 to close it ($5.00 a month while public; at most $5.00 a call); nothing if it fails.", "tags": ["helpcenter"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"public": {"type": "boolean"}}, "required": ["public"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_create": {"post": {"operationId": "ticket_create", "summary": "Open a ticket", "description": "Open a support ticket for a customer request (email to a support inbox opens one by itself; see ticket_connect_inbox). The requester is not emailed unless email_requester is true: then they get the usual acknowledgement, from the account's support inbox when it has one, so their answer comes back to this ticket. Costs $0.01 per call; nothing if it fails.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "maxLength": 254}, "name": {"type": "string", "maxLength": 255}, "message": {"type": "string", "minLength": 1, "maxLength": 20000}, "subject": {"type": "string", "maxLength": 200, "description": "Defaults to the first line of message."}, "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"]}, "category": {"type": "string", "maxLength": 80}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 40}, "description": "Short labels like \"refund\" or \"vip\" (kept lower-case, spaces become dashes)."}, "fields": {"type": "object", "maxProperties": 20, "propertyNames": {"pattern": "^[a-z][a-z0-9_]{0,39}$"}, "additionalProperties": {"type": ["string", "null"], "maxLength": 500}, "description": "Custom fields like {\"order_id\": \"1042\"}, merged into the ticket's fields; null removes one."}, "company_id": {"type": "integer", "minimum": 1, "description": "The CRM company this request is about."}, "email_requester": {"type": "boolean", "default": false}}, "required": ["email", "message"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_list": {"post": {"operationId": "ticket_list", "summary": "List tickets", "description": "Tickets, newest activity first, by status (default: open and pending), priority, requester, tag, custom field, CRM contact or company, words in the subject or request, or activity since a time. A view gives a work queue instead: waiting_on_us (open, no reply since the customer last wrote; longest waiting first), waiting_on_customer (pending), overdue (an SLA target missed; most overdue first), at_risk (an SLA target due within within_minutes), unassigned, or mine (assigned to the calling bot). Free. Free.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"view": {"type": "string", "enum": ["unassigned", "mine", "waiting_on_us", "waiting_on_customer", "overdue", "at_risk"]}, "status": {"type": "string", "enum": ["open", "pending", "resolved", "all"]}, "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"]}, "requester": {"type": "string", "maxLength": 254}, "query": {"type": "string", "maxLength": 200}, "tag": {"type": "string", "maxLength": 40}, "fields": {"type": "object", "maxProperties": 5, "propertyNames": {"pattern": "^[a-z][a-z0-9_]{0,39}$"}, "additionalProperties": {"type": "string", "maxLength": 500}, "description": "Only tickets with these custom field values, e.g. {\"order_id\": \"1042\"}."}, "contact_id": {"type": "integer", "minimum": 1}, "company_id": {"type": "integer", "minimum": 1}, "since": {"type": "string", "maxLength": 40, "description": "ISO 8601: activity at or after this time."}, "within_minutes": {"type": "integer", "minimum": 1, "maximum": 10080, "default": 60}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_get": {"post": {"operationId": "ticket_get", "summary": "Read a ticket", "description": "One ticket with its request, every reply, customer message and note (customer emails with their message id: email_get_message has attachments and the full text), tags, custom fields, SLA state and rating. Free. Free.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"number": {"type": "integer", "minimum": 1, "description": "The ticket number, e.g. 42 for ticket #42."}}, "required": ["number"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_reply": {"post": {"operationId": "ticket_reply", "summary": "Reply to a ticket", "description": "Email the requester a reply (internal=false) or add a private note only the team sees (internal=true). A reply goes out from the ticket's support inbox in the same email thread, so the customer's answer comes back to this ticket (inbox picks another support inbox); without one it is Conecto's standard ticket email. template sends a saved reply and applies its status and tags; body, if also given, goes above it. attachments: files of the file store, sent with a reply from a support inbox. status sets the status afterwards (pending = waiting on the customer, resolved = done); without it a reply reopens a resolved ticket. Costs $0.05 per call; nothing if it fails.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"number": {"type": "integer", "minimum": 1, "description": "The ticket number, e.g. 42 for ticket #42."}, "body": {"type": "string", "maxLength": 8000}, "internal": {"type": "boolean", "default": false}, "template": {"type": "string", "maxLength": 80}, "by_person": {"type": "boolean", "default": false, "description": "true when a person at the business wrote it. Otherwise a last line says the business's AI assistant wrote it (EU AI Act Art. 50)."}, "status": {"type": "string", "enum": ["open", "pending", "resolved"]}, "inbox": {"type": "string", "maxLength": 254}, "attachments": {"type": "array", "maxItems": 10, "items": {"type": "string", "minLength": 36, "maxLength": 36}, "description": "File ids from the file store (files_list), up to 10 files and 25 MB together. Replies from a support inbox only."}}, "required": ["number"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_update": {"post": {"operationId": "ticket_update", "summary": "Update a ticket", "description": "Change a ticket: status (open, pending = waiting on the customer, resolved), priority (its SLA targets follow), category, subject, tags, custom fields, the bot it is assigned to (\"me\", another bot's name, or \"\" for nobody) and the CRM contact or company it is about (0 unlinks). Resolving emails the requester a satisfaction survey when the settings ask for one; ask_rating true or false decides for this call (true also works on a ticket already resolved). Costs $0.01 per call; nothing if it fails.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"number": {"type": "integer", "minimum": 1, "description": "The ticket number, e.g. 42 for ticket #42."}, "status": {"type": "string", "enum": ["open", "pending", "resolved"]}, "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"]}, "category": {"type": "string", "maxLength": 80}, "subject": {"type": "string", "minLength": 1, "maxLength": 200}, "add_tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 40}, "description": "Short labels like \"refund\" or \"vip\" (kept lower-case, spaces become dashes)."}, "remove_tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 40}, "description": "Short labels like \"refund\" or \"vip\" (kept lower-case, spaces become dashes)."}, "fields": {"type": "object", "maxProperties": 20, "propertyNames": {"pattern": "^[a-z][a-z0-9_]{0,39}$"}, "additionalProperties": {"type": ["string", "null"], "maxLength": 500}, "description": "Custom fields like {\"order_id\": \"1042\"}, merged into the ticket's fields; null removes one."}, "assign_to": {"type": "string", "maxLength": 80}, "contact_id": {"type": "integer", "minimum": 0}, "company_id": {"type": "integer", "minimum": 0}, "ask_rating": {"type": "boolean"}}, "required": ["number"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_merge": {"post": {"operationId": "ticket_merge", "summary": "Merge tickets", "description": "Merge a duplicate ticket (number) into another (into): its messages, notes, email threads, tags and fields move over, so mail in the duplicate's thread lands on `into` from now on, and `into` reopens if the duplicate was still open. The duplicate is resolved and points at `into`. Replies on `into` go to its own requester only. Costs $0.01 per call; nothing if it fails.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"number": {"type": "integer", "minimum": 1, "description": "The ticket number, e.g. 42 for ticket #42."}, "into": {"type": "integer", "minimum": 1, "description": "The ticket number, e.g. 42 for ticket #42."}}, "required": ["number", "into"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_connect_inbox": {"post": {"operationId": "ticket_connect_inbox", "summary": "Connect a support inbox", "description": "Make one of the account's email inboxes a support inbox (open_tickets true): every new email to it opens a ticket, a reply in the same thread is added to that ticket (and reopens it), and ticket replies go out from its address in the same thread. Out-of-office replies, bounces, list mail and spam never open tickets. open_tickets false stops new tickets; answers to existing ones still arrive. Create the inbox first with email_create_inbox (email connector). Costs $0.001 per call; nothing if it fails.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"inbox": {"type": "string", "maxLength": 254}, "open_tickets": {"type": "boolean", "default": true}}, "required": ["inbox"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_save_template": {"post": {"operationId": "ticket_save_template", "summary": "Save a canned reply", "description": "Save a canned reply (a macro) under a name, replacing the one with that name. body may use {requester_name}, {requester_email}, {ticket_number}, {ticket_subject} and {business_name}. status and tags, if given, are applied each time it is sent with ticket_reply (e.g. status \"resolved\"). Costs $0.001 per call; nothing if it fails.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80}, "body": {"type": "string", "minLength": 1, "maxLength": 8000}, "status": {"type": "string", "enum": ["open", "pending", "resolved"]}, "tags": {"type": "array", "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 40}, "description": "Short labels like \"refund\" or \"vip\" (kept lower-case, spaces become dashes)."}}, "required": ["name", "body"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_list_templates": {"post": {"operationId": "ticket_list_templates", "summary": "List canned replies", "description": "Every saved reply with its text, status and tags. Free. Free.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_delete_template": {"post": {"operationId": "ticket_delete_template", "summary": "Delete a canned reply", "description": "Delete a saved reply by name. Costs $0.001 per call; nothing if it fails.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_get_settings": {"post": {"operationId": "ticket_get_settings", "summary": "Read help desk settings", "description": "The SLA targets, auto-close, the satisfaction survey setting and the support inboxes. Free. Free.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_update_settings": {"post": {"operationId": "ticket_update_settings", "summary": "Change help desk settings", "description": "Set the help desk's SLA targets, auto-close and satisfaction survey; what you leave out stays as it is. sla: first-response and resolution targets in minutes for each priority, replacing the current ones (a priority left out has none), e.g. {\"urgent\": {\"first_response_minutes\": 60, \"resolution_minutes\": 480}, \"normal\": {\"first_response_minutes\": 480, \"resolution_minutes\": 2880}}. The clock runs around the clock from when a ticket is opened and stops while it waits on the customer (pending); new targets apply to open tickets at once. auto_close_days: resolve tickets that waited on the customer this many days (0 = never). ask_rating_on_resolve: email the requester a one-click Good/Bad survey when a ticket is resolved. Costs $0.001 per call; nothing if it fails.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"sla": {"type": "object", "additionalProperties": false, "properties": {"low": {"type": "object", "additionalProperties": false, "properties": {"first_response_minutes": {"type": ["integer", "null"], "minimum": 1, "maximum": 43200}, "resolution_minutes": {"type": ["integer", "null"], "minimum": 1, "maximum": 525600}}}, "normal": {"type": "object", "additionalProperties": false, "properties": {"first_response_minutes": {"type": ["integer", "null"], "minimum": 1, "maximum": 43200}, "resolution_minutes": {"type": ["integer", "null"], "minimum": 1, "maximum": 525600}}}, "high": {"type": "object", "additionalProperties": false, "properties": {"first_response_minutes": {"type": ["integer", "null"], "minimum": 1, "maximum": 43200}, "resolution_minutes": {"type": ["integer", "null"], "minimum": 1, "maximum": 525600}}}, "urgent": {"type": "object", "additionalProperties": false, "properties": {"first_response_minutes": {"type": ["integer", "null"], "minimum": 1, "maximum": 43200}, "resolution_minutes": {"type": ["integer", "null"], "minimum": 1, "maximum": 525600}}}}}, "auto_close_days": {"type": "integer", "minimum": 0, "maximum": 365}, "ask_rating_on_resolve": {"type": "boolean"}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/ticket_report": {"post": {"operationId": "ticket_report", "summary": "Help desk report", "description": "How support went over the last `days` (default 30): tickets opened and resolved, the backlog now (open, pending, overdue, unassigned), first-response and resolution times in minutes (median and 90th percentile), SLA targets met and breached, satisfaction ratings, and tickets by channel, priority and tag. Free. Free.", "tags": ["helpdesk"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"days": {"type": "integer", "minimum": 1, "maximum": 365, "default": 30}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_setup_careers": {"post": {"operationId": "hiring_setup_careers", "summary": "Set up the careers page", "description": "The careers page at cncto.co/j/<name> that lists the open jobs: its name, a short intro, the website, the address candidates' replies go to, and who hears about each application. Only what you pass changes. Costs $0.001 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 120}, "intro": {"type": "string", "maxLength": 2000}, "website": {"type": "string", "maxLength": 500}, "reply_to": {"type": "string", "maxLength": 254}, "notify_email": {"type": "string", "maxLength": 254}, "ai_review": {"type": "boolean", "description": "Tell candidates on every application form that AI may help review applications, as the EU's AI Act asks. Required before screening with hiring_screen_queue."}, "ai_notice": {"type": "string", "maxLength": 600, "description": "Your own words for that notice; \"\" for ours (a person decides, and how to ask a person to look again)."}, "application_limit": {"type": ["object", "null"], "additionalProperties": false, "required": ["count", "days"], "properties": {"count": {"type": "integer", "minimum": 1, "maximum": 50}, "days": {"type": "integer", "minimum": 1, "maximum": 730}}, "description": "At most count applications from one person in days, across every role, like {\"count\": 2, \"days\": 180}; the form says so. null: no limit."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_design_careers": {"post": {"operationId": "hiring_design_careers", "summary": "Design the job pages", "description": "The look of the careers page and every job page with its application form, on top of the brand kit (account_set_brand: name, logo, colour): accent (buttons, links, chosen answers), background and text colours, font (conecto, system, serif or rounded), radius for corners (0 to 24 px), a cover image above the roles (cover_file_id from the file store; \"\" takes it away), the careers page headline, and css: your own stylesheet. The CSS is confined to the pages: every rule applies inside them, @import and the like are removed and listed in warnings, and \"Hiring by Conecto\" at the foot stays as it is. Only what you pass changes; \"\" clears one, reset: true clears them all. Costs $0.001 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"accent": {"type": "string", "maxLength": 7, "description": "A hex colour like #0f5132; \"\" for the default."}, "background": {"type": "string", "maxLength": 7, "description": "A hex colour like #0f5132; \"\" for the default."}, "text": {"type": "string", "maxLength": 7, "description": "A hex colour like #0f5132; \"\" for the default."}, "font": {"type": "string", "enum": ["", "conecto", "system", "serif", "rounded"]}, "radius": {"type": ["integer", "null"], "minimum": 0, "maximum": 24, "description": "Pixels; null for the default."}, "cover_file_id": {"type": "string", "maxLength": 36, "description": "A PNG, JPEG, WebP or GIF from the file store, kept as a JPEG of at most 2400 by 1200 pixels."}, "headline": {"type": "string", "maxLength": 120, "description": "Default \"Careers at <name>\"."}, "css": {"type": "string", "maxLength": 200000, "description": "Rules for the pages' own classes (.jb-hero, .jb-role, .jb-job and the form's .fm-*); body and :root mean the page itself."}, "reset": {"type": "boolean"}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_create_job": {"post": {"operationId": "hiring_create_job", "summary": "Post a job", "description": "A job with its own page and application form on the careers page (cncto.co/j/<name>/<job>): name, email, phone, links, a résumé (PDF or Word), a cover letter and your questions. A draft unless open is true. Each application costs $0.50; posting is $0.01. Costs $0.01 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "minLength": 2, "maxLength": 160, "description": "e.g. \"Bike mechanic\"."}, "description": {"type": "string", "minLength": 20, "maxLength": 20000, "description": "Markdown: the role, what they will do, what you look for, what you offer."}, "department": {"type": "string", "maxLength": 80}, "location": {"type": "string", "maxLength": 160, "description": "e.g. \"Portland, OR\"."}, "workplace": {"type": "string", "enum": ["on_site", "hybrid", "remote"]}, "employment_type": {"type": "string", "enum": ["full_time", "part_time", "contract", "internship", "temporary"]}, "salary": {"type": "object", "description": "{\"min\": 52000, \"max\": 60000, \"currency\": \"USD\", \"period\": \"year\"} (period: hour, month or year)."}, "questions": {"type": "array", "maxItems": 10, "items": {"type": "object"}, "description": "Extra questions on the application form: [{\"label\", \"type\", \"required\", \"help\"}]. type: short_text, long_text, yes_no, choice, multi_choice (both with \"options\": [\"...\", \"...\"]), number, date or url. A yes_no question can set \"required_answer\": true or false; any other answer flags the applicant (never an automatic no). A date question can take include_time (a time too), range (a first and a last day), and earliest and latest (\"2026-11-01\", or \"today\", \"today+7\", \"today-30\")."}, "criteria": {"type": "array", "maxItems": 10, "items": {"type": "object"}, "description": "What a screening checks: [{\"text\": \"Three years in customer support\", \"required\": true, \"weight\": 3}]. weight, 1 to 5, is how much it counts in the match score; a required one a screening does not find is named. Give a criterion's id (from hiring_list_jobs) when rewording it, so past screenings stay attached. Used by hiring_screen_queue and hiring_record_screening."}, "stages": {"type": "array", "maxItems": 8, "items": {"type": "string", "maxLength": 60}, "description": "The steps between Applied and Hired/Rejected; default Screen, Interview, Offer."}, "filter": {"type": ["object", "null"], "additionalProperties": false, "properties": {"min_match": {"type": "integer", "minimum": 0, "maximum": 100}, "required": {"type": "boolean"}, "max_risk": {"type": "string", "enum": ["none", "minor", "high"]}}, "description": "Who the hiring team hears about: {\"min_match\": 70, \"required\": true, \"max_risk\": \"minor\"} (the lowest match score, every required criterion shown, the most risk the checks may find). With a filter, the team is told about a candidate once your screening (hiring_record_screening) passes it, in your words: by email to the careers page's notify address and as the event hiring.candidate_passed; not about every application as it arrives. null: no filter."}, "open": {"type": "boolean", "default": false, "description": "Take applications now."}}, "required": ["title", "description"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_update_job": {"post": {"operationId": "hiring_update_job", "summary": "Change a job", "description": "Change a job's details, or open and close it (a closed job stays readable but takes no applications). Give only what changes. Costs $0.01 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"job": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The job (its slug from hiring_list_jobs)."}, "title": {"type": "string", "minLength": 2, "maxLength": 160, "description": "e.g. \"Bike mechanic\"."}, "description": {"type": "string", "minLength": 20, "maxLength": 20000, "description": "Markdown: the role, what they will do, what you look for, what you offer."}, "department": {"type": "string", "maxLength": 80}, "location": {"type": "string", "maxLength": 160, "description": "e.g. \"Portland, OR\"."}, "workplace": {"type": "string", "enum": ["on_site", "hybrid", "remote"]}, "employment_type": {"type": "string", "enum": ["full_time", "part_time", "contract", "internship", "temporary"]}, "salary": {"type": "object", "description": "{\"min\": 52000, \"max\": 60000, \"currency\": \"USD\", \"period\": \"year\"} (period: hour, month or year)."}, "questions": {"type": "array", "maxItems": 10, "items": {"type": "object"}, "description": "Extra questions on the application form: [{\"label\", \"type\", \"required\", \"help\"}]. type: short_text, long_text, yes_no, choice, multi_choice (both with \"options\": [\"...\", \"...\"]), number, date or url. A yes_no question can set \"required_answer\": true or false; any other answer flags the applicant (never an automatic no). A date question can take include_time (a time too), range (a first and a last day), and earliest and latest (\"2026-11-01\", or \"today\", \"today+7\", \"today-30\")."}, "criteria": {"type": "array", "maxItems": 10, "items": {"type": "object"}, "description": "What a screening checks: [{\"text\": \"Three years in customer support\", \"required\": true, \"weight\": 3}]. weight, 1 to 5, is how much it counts in the match score; a required one a screening does not find is named. Give a criterion's id (from hiring_list_jobs) when rewording it, so past screenings stay attached. Used by hiring_screen_queue and hiring_record_screening."}, "stages": {"type": "array", "maxItems": 8, "items": {"type": "string", "maxLength": 60}, "description": "The steps between Applied and Hired/Rejected; default Screen, Interview, Offer."}, "filter": {"type": ["object", "null"], "additionalProperties": false, "properties": {"min_match": {"type": "integer", "minimum": 0, "maximum": 100}, "required": {"type": "boolean"}, "max_risk": {"type": "string", "enum": ["none", "minor", "high"]}}, "description": "Who the hiring team hears about: {\"min_match\": 70, \"required\": true, \"max_risk\": \"minor\"} (the lowest match score, every required criterion shown, the most risk the checks may find). With a filter, the team is told about a candidate once your screening (hiring_record_screening) passes it, in your words: by email to the careers page's notify address and as the event hiring.candidate_passed; not about every application as it arrives. null: no filter."}, "status": {"type": "string", "enum": ["draft", "open", "closed"]}}, "required": ["job"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_list_jobs": {"post": {"operationId": "hiring_list_jobs", "summary": "List jobs", "description": "This account's jobs with their status, page and applicants per stage. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["draft", "open", "closed"]}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_list_applicants": {"post": {"operationId": "hiring_list_applicants", "summary": "List applicants", "description": "Applicants, newest first or by match score: for one job or all, at one stage, matching a name or email, by risk, or the ones kept as spam. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"job": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The job (its slug from hiring_list_jobs)."}, "stage": {"type": "string", "maxLength": 60}, "query": {"type": "string", "maxLength": 200}, "screened": {"type": "boolean", "description": "true: only screened ones; false: only those not yet."}, "match": {"type": "string", "enum": ["strong", "partial", "weak"]}, "risk": {"type": "string", "enum": ["high", "minor", "none"], "description": "Only applications whose checks found high risk, minor signals, or none."}, "spam": {"type": "boolean", "default": false, "description": "true: only applications kept as spam (from the blocklist, or marked)."}, "min_match": {"type": "integer", "minimum": 0, "maximum": 100, "description": "Only screened applications whose match score is at least this."}, "sort": {"type": "string", "enum": ["newest", "match"], "default": "newest", "description": "match: the highest match score first, the unscreened last."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_get_applicant": {"post": {"operationId": "hiring_get_applicant", "summary": "Read an application", "description": "One application in full: links, cover letter, answers, the screening with its match score, the checks on who sent it, notes, history, and the résumé with a download link. signals come from what the application objectively carries (its network, email and phone, and what other applications share), never from AI, grouped as high risk, minor and authenticity markers; they inform and decide nothing. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}}, "required": ["applicant_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_get_blocklist": {"post": {"operationId": "hiring_get_blocklist", "summary": "Read the spam blocklist", "description": "The networks and email domains whose applications are kept as spam. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_update_blocklist": {"post": {"operationId": "hiring_update_blocklist", "summary": "Change the spam blocklist", "description": "Block or unblock networks and email domains, like Greenhouse's spam blocklist. Applications from them are kept as spam: no $0.50 fee, no emails, out of hiring_list_applicants unless spam is true, and the sender sees the usual thank-you. Applications already in stay where they are. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"add": {"type": "object", "additionalProperties": false, "properties": {"ips": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 50}, "description": "Addresses or ranges: \"203.0.113.7\", \"198.51.100.0/24\", \"2001:db8::/48\"."}, "email_domains": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 253}, "description": "e.g. \"spam-jobs.biz\" (its subdomains too). Free providers like gmail.com are refused: block the network instead."}}}, "remove": {"type": "object", "additionalProperties": false, "properties": {"ips": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 50}, "description": "Addresses or ranges: \"203.0.113.7\", \"198.51.100.0/24\", \"2001:db8::/48\"."}, "email_domains": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 253}, "description": "e.g. \"spam-jobs.biz\" (its subdomains too). Free providers like gmail.com are refused: block the network instead."}}}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_mark_spam": {"post": {"operationId": "hiring_mark_spam", "summary": "Mark an application as spam", "description": "Move one application to spam (out of hiring_list_applicants unless spam is true), or back with spam false. block: true also blocks the network it came from and its email domain (never a free provider's, like gmail.com). One kept as spam on arrival opens like any application when marked not spam: the $0.50 fee is charged then. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "spam": {"type": "boolean", "default": true}, "block": {"type": "boolean", "default": false, "description": "Also block its network and email domain (with spam true)."}}, "required": ["applicant_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_move_applicant": {"post": {"operationId": "hiring_move_applicant", "summary": "Move an applicant", "description": "Move an applicant to another stage of their job (e.g. Interview, Hired or Rejected), with an optional note. Candidates are not told; email them with hiring_email_applicant. Costs $0.01 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "stage": {"type": "string", "minLength": 1, "maxLength": 60}, "note": {"type": "string", "maxLength": 5000}}, "required": ["applicant_id", "stage"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_hire_applicant": {"post": {"operationId": "hiring_hire_applicant", "summary": "Hire an applicant", "description": "The hire in one call instead of five: the applicant moves to Hired, joins HR as a person (their name, the job's title, department and location unless given, start_date, work_email if they have one yet, their own email kept as personal_email), their résumé goes on their HR record, and the onboarding checklist named in checklist starts. Refused if they are already in HR. $0.25. Costs $0.25 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "start_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "work_email": {"type": "string", "maxLength": 254}, "title": {"type": "string", "maxLength": 120}, "department": {"type": "string", "maxLength": 120}, "location": {"type": "string", "maxLength": 120}, "manager": {"type": ["integer", "string"], "description": "Their manager's person_id or work email."}, "employment_type": {"type": "string", "enum": ["full_time", "part_time", "contractor", "intern"]}, "checklist": {"type": "string", "maxLength": 80, "description": "An onboarding checklist to start."}}, "required": ["applicant_id", "start_date"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_note": {"post": {"operationId": "hiring_note", "summary": "Note or rate an applicant", "description": "Add a note to an applicant, and/or rate them 1 to 5. Costs $0.01 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "note": {"type": "string", "minLength": 1, "maxLength": 5000}, "rating": {"type": "integer", "minimum": 1, "maximum": 5}}, "required": ["applicant_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_email_applicant": {"post": {"operationId": "hiring_email_applicant", "summary": "Email an applicant", "description": "Email an applicant in the business's name (replies go to the careers page's reply_to): an interview invitation with a booking link, a next step, or a kind no. Costs $0.02 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "subject": {"type": "string", "minLength": 1, "maxLength": 200}, "text": {"type": "string", "minLength": 1, "maxLength": 10000}, "by_person": {"type": "boolean", "default": false, "description": "true when a person at the business wrote it. Otherwise a last line says the business's AI assistant wrote it (EU AI Act Art. 50)."}}, "required": ["applicant_id", "subject", "text"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_screen_queue": {"post": {"operationId": "hiring_screen_queue", "summary": "Applications to screen", "description": "The next applications nobody has screened yet, oldest first, with what a review needs: the job, its criteria and filter, the answers and flags, the cover letter and the résumé as text. Blind by default: name, email, phone and links are left out and replaced in the text, so the review rests on what they did. Review each one yourself and save it with hiring_record_screening; Conecto never rejects anyone. To screen each application as it arrives, send hiring.application_received to your webhook with notify_subscribe, or read account_events. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"job": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The job (its slug from hiring_list_jobs)."}, "limit": {"type": "integer", "minimum": 1, "maximum": 10, "default": 5}, "blind": {"type": "boolean", "default": true}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_record_screening": {"post": {"operationId": "hiring_record_screening", "summary": "Save a screening", "description": "Save your review of one application: strong, partial or weak match, a short summary, and for each of the job's criteria whether the application shows it, with the words that show it. Its match score is the weighted share of the criteria it shows (unclear counts as not shown). When the job has a filter and the application passes it, the hiring team hears about it once, with your summary: by email and as the event hiring.candidate_passed. It moves nobody: decide with hiring_move_applicant. Costs $0.01 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "match": {"type": "string", "enum": ["strong", "partial", "weak"]}, "summary": {"type": "string", "minLength": 1, "maxLength": 2000}, "criteria": {"type": "array", "maxItems": 10, "items": {"type": "object"}, "description": "[{\"id\": \"c1\", \"met\": true|false|null, \"evidence\": \"Led a team of four at ...\"}]"}}, "required": ["applicant_id", "match", "summary"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_invite_to_interview": {"post": {"operationId": "hiring_invite_to_interview", "summary": "Invite to an interview", "description": "Email an applicant a link to book an interview on one of your calendar's meeting types (calendar area), in the business's name. When they book, it shows in their history. Optionally move them to a stage such as Interview. Costs $0.05 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "meeting_type": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The meeting type's slug from calendar_list_meeting_types."}, "message": {"type": "string", "maxLength": 5000, "description": "Your own words; a short invitation when left out."}, "move_to": {"type": "string", "maxLength": 60}}, "required": ["applicant_id", "meeting_type"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_save_assessment": {"post": {"operationId": "hiring_save_assessment", "summary": "Write a skills test", "description": "Write a skills test for candidates, or change one (give its slug): questions with one or more right options are scored on their own; short answers too when you list the accepted ones; written answers wait for hiring_mark_assessment. Optional time limit and shuffling. Write tests about the job's real work; personality and IQ-style questions are not what this is for. Questions stay fixed once someone has started the test; save a new test instead. Costs $0.01 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"assessment": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The test (its slug from hiring_list_assessments)."}, "title": {"type": "string", "minLength": 2, "maxLength": 160}, "intro": {"type": "string", "maxLength": 5000, "description": "Markdown shown before they start."}, "questions": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "object"}, "description": "[{\"type\": \"choice\", \"prompt\": \"...\", \"options\": [\"A\", \"B\", \"C\"], \"correct\": \"B\", \"points\": 1}, {\"type\": \"multi_choice\", ..., \"correct\": [\"A\", \"C\"]}, {\"type\": \"short_text\", \"prompt\": \"...\", \"accept\": [\"42\"]}, {\"type\": \"long_text\", \"prompt\": \"...\", \"points\": 5}]"}, "time_limit_minutes": {"type": "integer", "minimum": 0, "maximum": 180, "description": "0: none."}, "shuffle": {"type": "boolean", "description": "Shuffle questions and options for each candidate."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_list_assessments": {"post": {"operationId": "hiring_list_assessments", "summary": "List skills tests", "description": "This account's tests: title, questions, time limit, how many were sent and completed. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"full": {"type": "boolean", "default": false, "description": "Include the questions and answer keys."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_delete_assessment": {"post": {"operationId": "hiring_delete_assessment", "summary": "Delete a skills test", "description": "Delete a test, with every candidate's answers to it. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"assessment": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The test (its slug from hiring_list_assessments)."}}, "required": ["assessment"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_send_assessment": {"post": {"operationId": "hiring_send_assessment", "summary": "Send a skills test", "description": "Email an applicant their own link to a test, in the business's name. The link works for `days` until they start; then the time limit runs. $0.25 when they complete it. Costs $0.02 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "assessment": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The test (its slug from hiring_list_assessments)."}, "message": {"type": "string", "maxLength": 5000, "description": "Your own words; a short note when left out."}, "days": {"type": "integer", "minimum": 1, "maximum": 30, "default": 7}}, "required": ["applicant_id", "assessment"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_assessment_results": {"post": {"operationId": "hiring_assessment_results", "summary": "Read test results", "description": "An applicant's tests: status, score, each answer with the expected one, written answers still to mark, minutes taken, and how often they left the page while it ran. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}}, "required": ["applicant_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_mark_assessment": {"post": {"operationId": "hiring_mark_assessment", "summary": "Mark written answers", "description": "Give points to the written answers of a completed test (0 up to each question's points). Costs $0.01 per call; nothing if it fails.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}, "assessment": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The test (its slug from hiring_list_assessments)."}, "marks": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "object"}, "description": "[{\"question\": \"q4\", \"points\": 3}]"}}, "required": ["applicant_id", "assessment", "marks"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_delete_applicant": {"post": {"operationId": "hiring_delete_applicant", "summary": "Delete an applicant", "description": "Delete an applicant and their résumé for good, for example when they ask to be forgotten. Applicants are deleted on their own 12 months after their last change. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"applicant_id": {"type": "integer", "minimum": 1}}, "required": ["applicant_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hiring_dashboard_link": {"post": {"operationId": "hiring_dashboard_link", "summary": "Get a link to the hiring overview", "description": "A one-time link to hiring at a glance: every applicant's stage and next step, the tests and interviews waiting, and the open jobs (sealed applications show no name). Only when the person you work for asks to see it themselves: screen, move, test and invite with hiring's own tools first and answer from them, and offer a link when they would rather look through the pipeline, making it once they say yes. The page is made when it opens, from hiring's own reads as this key, so it shows only what this key may see: the same page as account_dashboard_link with area hiring. Its Settings let the person change the application limit, made as this key through hiring_setup_careers (this key's scope, approval rules and price apply). It opens once and keeps for an hour; an unopened link ends after 7 days. Free. Free.", "tags": ["hiring"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/image_info": {"post": {"operationId": "image_info", "summary": "Read an image's details", "description": "Width, height, format and whether it has transparency. Free.", "tags": ["images"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "An image in the file store."}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/image_transform": {"post": {"operationId": "image_transform", "summary": "Resize or convert an image", "description": "A new image from one in the file store: resized (fit inside the box, or cover it and crop the overflow from the center), converted to WebP, AVIF, JPEG or PNG, and compressed. Photos come out turned the right way up with their metadata (GPS included) removed. Costs $0.005 per call; nothing if it fails.", "tags": ["images"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "An image in the file store."}, "width": {"type": "integer", "minimum": 1, "maximum": 8000}, "height": {"type": "integer", "minimum": 1, "maximum": 8000}, "fit": {"type": "string", "enum": ["inside", "cover"], "default": "inside"}, "format": {"type": "string", "enum": ["webp", "avif", "jpeg", "png"], "default": "webp"}, "quality": {"type": "integer", "minimum": 30, "maximum": 100, "default": 82}, "name": {"type": "string", "maxLength": 200}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/import_csv": {"post": {"operationId": "import_csv", "summary": "Import contacts or companies from a CSV", "description": "Import contacts or companies from a CSV file: send its text as csv, or an https link to it as url (a public Google Sheets CSV link works). Columns are matched by their header names in any case or spelling: email, name, first name, last name, phone or mobile, company or organization, domain, website, title or job title, notes, address, city or country (joined into location), lifecycle stage, timezone, language; for companies: name, domain, website, industry, employees, lifecycle stage, notes. The result lists the columns it mapped and the ones it ignored. Contacts match existing ones by email, companies by domain and then by name, so importing the same file again updates instead of duplicating. Up to 5,000 rows a call: a longer file returns next_cursor to continue. Unchanged records are free, and 1,000 imported records cost $1. max_records x $0.001 is reserved while it runs and only what was imported is charged; lower max_records if your balance is smaller. Costs $0.001 per record imported (created or updated); nothing if none are found.", "tags": ["imports"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["contacts", "companies"], "default": "contacts", "description": "What each row is."}, "csv": {"type": "string", "minLength": 1, "maxLength": 2000000, "description": "The CSV text, column names in the first row (up to about 2 MB; use url for more)."}, "url": {"type": "string", "minLength": 8, "maxLength": 2048, "description": "An https link to the CSV file, instead of csv. At most 20 MB."}, "max_records": {"type": "integer", "minimum": 1, "maximum": 5000, "default": 5000, "description": "The most rows to read in this call (5,000 at most)."}, "next_cursor": {"type": "string", "maxLength": 2000, "description": "The next_cursor a previous run of this import returned, to continue where it stopped."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/import_from_hubspot": {"post": {"operationId": "import_from_hubspot", "summary": "Import from HubSpot", "description": "Import a HubSpot account: companies, contacts (linked to their company), deals (stage, amount, currency, close date, and the company and contact they belong to) and notes (on their contact's timeline, else added to their deal or company). Needs a private app access token. Make one in HubSpot under Development > Legacy apps > Create a private app, with the read scopes crm.objects.companies.read, crm.objects.contacts.read and crm.objects.deals.read; the token is on its Auth tab. Wrong credentials are refused before anything is reserved or charged; the token is kept only encrypted while the import runs, then erased. Contacts match existing ones by email, companies by domain, then name. Runs in the background for up to 15 minutes and imports up to max_records records; when more remain, the result has next_cursor: call again with the same arguments plus next_cursor to continue. Running it again never duplicates anything: changed records are updated, unchanged ones skipped. Unchanged records are free, and 1,000 imported records cost $1. max_records x $0.001 is reserved while it runs and only what was imported is charged; lower max_records if your balance is smaller. Costs $0.001 per record imported (created or updated); nothing if none are found. Runs in the background: the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>.", "tags": ["imports"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"access_token": {"type": "string", "minLength": 10, "maxLength": 500, "description": "The HubSpot private app access token (starts with pat-).", "writeOnly": true}, "max_records": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 10000, "description": "The most records this run may create or update (and reserve $0.001 each for)."}, "next_cursor": {"type": "string", "maxLength": 2000, "description": "The next_cursor a previous run of this import returned, to continue where it stopped."}, "default_currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "default": "USD", "description": "The currency of deal amounts that name none (HubSpot leaves it blank when the account has a single currency)."}}, "required": ["access_token"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}, "202": {"description": "Started; poll /v1/calls/{call_id}.", "content": {"application/json": {"schema": {"type": "object"}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/import_from_pipedrive": {"post": {"operationId": "import_from_pipedrive", "summary": "Import from Pipedrive", "description": "Import a Pipedrive account: organizations (as companies), persons (as contacts, linked to their organization), deals (won, lost or the open stage, value, currency, expected close date, organization and person), notes (on their person's timeline, else added to their deal or organization) and activities (as tasks on their person, open or done, with their due time). Needs the API token of a Pipedrive user who can see the records. The API token is in Pipedrive under Settings > Personal preferences > API. company_domain (the acme in acme.pipedrive.com) is optional. Wrong credentials are refused before anything is reserved or charged; the token is kept only encrypted while the import runs, then erased. Contacts match existing ones by email, companies by domain, then name. Runs in the background for up to 15 minutes and imports up to max_records records; when more remain, the result has next_cursor: call again with the same arguments plus next_cursor to continue. Running it again never duplicates anything: changed records are updated, unchanged ones skipped. Unchanged records are free, and 1,000 imported records cost $1. max_records x $0.001 is reserved while it runs and only what was imported is charged; lower max_records if your balance is smaller. Costs $0.001 per record imported (created or updated); nothing if none are found. Runs in the background: the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>.", "tags": ["imports"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"api_token": {"type": "string", "minLength": 10, "maxLength": 200, "description": "The Pipedrive API token.", "writeOnly": true}, "company_domain": {"type": "string", "maxLength": 120, "description": "Optional: the \"acme\" in acme.pipedrive.com."}, "max_records": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 10000, "description": "The most records this run may create or update (and reserve $0.001 each for)."}, "next_cursor": {"type": "string", "maxLength": 2000, "description": "The next_cursor a previous run of this import returned, to continue where it stopped."}}, "required": ["api_token"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}, "202": {"description": "Started; poll /v1/calls/{call_id}.", "content": {"application/json": {"schema": {"type": "object"}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/import_from_zendesk": {"post": {"operationId": "import_from_zendesk", "summary": "Import from Zendesk", "description": "Import a Zendesk Support account's tickets, with their public replies as the conversation, and each requester as a contact (matched to existing contacts by email). Status new/open becomes open, pending/on-hold pending, solved/closed resolved; priority, subject and dates are kept. Nobody is emailed. Needs the subdomain (acme for acme.zendesk.com), and an agent's or admin's email with an API token from Zendesk Admin Center > Apps and integrations > APIs > API tokens. With an admin's email every ticket comes over, archived ones included; with an agent's, Zendesk leaves out archived tickets. Wrong credentials are refused before anything is reserved or charged; the token is kept only encrypted while the import runs, then erased. A ticket and its requester count as records; replies come with their ticket. Runs in the background for up to 15 minutes and imports up to max_records records; when more remain, the result has next_cursor: call again with the same arguments plus next_cursor to continue. Running it again never duplicates anything: changed records are updated, unchanged ones skipped. Unchanged records are free, and 1,000 imported records cost $1. max_records x $0.001 is reserved while it runs and only what was imported is charged; lower max_records if your balance is smaller. Costs $0.001 per record imported (created or updated); nothing if none are found. Runs in the background: the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>.", "tags": ["imports"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"subdomain": {"type": "string", "minLength": 1, "maxLength": 120, "description": "The \"acme\" in acme.zendesk.com."}, "email": {"type": "string", "minLength": 3, "maxLength": 254, "description": "The email of the agent or admin the API token is used as."}, "api_token": {"type": "string", "minLength": 10, "maxLength": 200, "description": "A Zendesk API token.", "writeOnly": true}, "max_records": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 10000, "description": "The most records this run may create or update (and reserve $0.001 each for)."}, "next_cursor": {"type": "string", "maxLength": 2000, "description": "The next_cursor a previous run of this import returned, to continue where it stopped."}}, "required": ["subdomain", "email", "api_token"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}, "202": {"description": "Started; poll /v1/calls/{call_id}.", "content": {"application/json": {"schema": {"type": "object"}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/import_status": {"post": {"operationId": "import_status", "summary": "Import status", "description": "What the imports brought in so far, per source (csv, hubspot, pipedrive:<company>, zendesk:<subdomain>): how many companies, contacts, deals, notes, tasks, tickets and ticket replies; and the last 10 import runs with their status, cost and, for one that stopped before the end, the next_cursor to continue with. Free.", "tags": ["imports"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_connect_stripe": {"post": {"operationId": "invoices_connect_stripe", "summary": "Connect Stripe for invoices", "description": "Connect the business's own Stripe account with a restricted key (a person makes it in Stripe: Developers, API keys, Create restricted key), so invoices can carry a Pay button (invoices_set_profile pay_online). A restricted key with write access to Checkout Sessions and Webhook Endpoints. Conecto registers a webhook on that account to learn when an invoice is paid. The money goes straight to the business; Conecto never holds it. The key is kept encrypted and never shown again. Costs $0.001 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"stripe_key": {"type": "string", "maxLength": 300, "minLength": 20, "writeOnly": true}}, "required": ["stripe_key"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_set_profile": {"post": {"operationId": "invoices_set_profile", "summary": "Set the business details", "description": "Set the business details printed on quotes and invoices: legal name, country, address, tax ID, email, phone, logo, default currency, payment terms, tax rate, number prefixes and next numbers, payment instructions, an optional payment link and legal notes. Only the fields given change. Sending needs legal_name and country; in the EU, the UK and Switzerland an invoice also needs the address and tax ID, checked when it is sent. Costs $0.001 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"legal_name": {"type": "string", "maxLength": 200, "description": "The business name on documents; also the email sender name."}, "address": {"type": "string", "maxLength": 1000, "description": "Postal address, one line per row."}, "tax_id": {"type": "string", "maxLength": 60, "description": "VAT, GST or tax number, printed with the address."}, "email": {"type": "string", "maxLength": 254, "description": "Where customers write about invoices: printed, and the Reply-To of emails."}, "phone": {"type": "string", "maxLength": 40}, "logo_file_id": {"type": "string", "maxLength": 36, "description": "An image in the file store (PNG, JPEG, GIF, WebP or SVG, up to 1 MB). \"\" removes the logo."}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "Default currency of new documents, ISO 4217."}, "payment_terms_days": {"type": "integer", "minimum": 0, "maximum": 365, "description": "Days from issue to due date. Default 14."}, "quote_valid_days": {"type": "integer", "minimum": 1, "maximum": 365, "description": "How long quotes stay open. Default 30."}, "invoice_prefix": {"type": "string", "maxLength": 20, "pattern": "^[A-Za-z0-9 ._/#-]*$", "description": "Default \"INV-\": invoices are INV-0001, INV-0002..."}, "quote_prefix": {"type": "string", "maxLength": 20, "pattern": "^[A-Za-z0-9 ._/#-]*$", "description": "Default \"Q-\"."}, "credit_note_prefix": {"type": "string", "maxLength": 20, "pattern": "^[A-Za-z0-9 ._/#-]*$", "description": "Default \"CN-\"."}, "next_invoice_number": {"type": "integer", "minimum": 1, "maximum": 99999999, "description": "The number the next invoice gets, e.g. to carry on from another tool. Never one already used."}, "next_quote_number": {"type": "integer", "minimum": 1, "maximum": 99999999}, "next_credit_note_number": {"type": "integer", "minimum": 1, "maximum": 99999999}, "tax_rate": {"type": ["number", "string"], "maxLength": 24, "description": "Default tax percent for new lines, e.g. 19. 0 for none."}, "tax_label": {"type": "string", "maxLength": 30, "description": "What the tax is called on documents: \"VAT\", \"GST\", \"Sales tax\". Default \"Tax\"."}, "footer": {"type": "string", "maxLength": 2000, "description": "Payment instructions printed at the bottom of invoices, e.g. bank name, IBAN and BIC."}, "payment_link": {"type": "string", "maxLength": 500, "description": "An https link where customers pay, e.g. the business's own Stripe Payment Link. \"\" removes it."}, "pay_online": {"type": "boolean", "description": "A Pay button on each invoice's page: Stripe Checkout on the business's own Stripe (connect it with invoices_connect_stripe); each payment is recorded and posted to the books on its own. $0.10 per invoice paid online."}, "timezone": {"type": "string", "maxLength": 64, "description": "IANA time zone for dates, e.g. \"America/New_York\". Default UTC."}, "paper": {"type": "string", "enum": ["a4", "letter"], "description": "Default: Letter for USD and CAD businesses, else A4."}, "country": {"type": "string", "maxLength": 2, "description": "ISO 3166-1 code of the country the business is established in, e.g. \"DE\". Needed to send: it decides what invoices must show (in the EU the VAT ID, addresses, the date of supply, why a line has no tax, VAT in the national currency) and is checked before each one goes out."}, "legal_notes": {"type": "string", "maxLength": 2000, "description": "Printed at the foot of every quote, invoice and credit note: the company register and managing directors, a small-business VAT note, late-payment terms the law asks for (France: penalty rate and the EUR 40 indemnity). In France and Germany the country's default wording is filled in when the country is set and none is given; \"\" brings it back."}, "document_language": {"type": "string", "enum": ["", "en", "de", "fr"], "description": "The language of the fixed words on quotes, invoices and credit notes (labels, dates, amounts); \"\" picks it by country: German in Germany and Austria, French in France, else English. The business's own text is printed as written."}, "tax_exemption": {"type": "string", "enum": ["", "exempt", "zero_rated", "reverse_charge", "intra_eu", "export", "outside_scope", "small_business"], "description": "Why lines with tax_rate 0 carry no tax, printed on the invoice as the law asks: exempt, zero_rated, reverse_charge (the customer accounts for the VAT), intra_eu (goods to a business in another EU country), export (goods leaving the EU), outside_scope, small_business (a business under its country's small-business VAT exemption, such as UStG §19 or art. 293 B CGI: no line may carry tax). Needed in the EU for any line without tax. Default: the profile's."}, "tax_exemption_note": {"type": "string", "maxLength": 300, "description": "The wording printed for the exemption instead of the standard one, e.g. \"Steuerbefreit als Kleinunternehmer nach § 19 UStG\"."}, "e_invoice": {"type": "string", "enum": ["", "factur-x", "xrechnung", "none"], "description": "Invoices and their credit notes as EN 16931 e-invoices (German B2B invoices must be from 2027): factur-x (Factur-X/ZUGFeRD, the XML inside the PDF/A-3) or xrechnung (XRechnung 3.0, its own XML beside the PDF), checked against the EN 16931 schema before sending. \"\" is the default: none, except that from 2027 an invoice from a German business to a German business above EUR 250 is a factur-x; \"none\" opts out (a business under the EUR 800,000 turnover allowance until 2028). Needs the customer's country. Default: the profile's."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_get_profile": {"post": {"operationId": "invoices_get_profile", "summary": "Get the business details", "description": "The business details used on quotes and invoices, the next numbers, and what is still missing before documents can be sent. Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_create": {"post": {"operationId": "invoices_create", "summary": "Create a quote or invoice", "description": "Create a quote or an invoice as a draft: the customer (a CRM contact or company, or a name and email), line items, currency and dates. Nothing is numbered or sent yet; change drafts with invoices_update and send them with invoices_send. Amounts are the business's money in the document's currency, rounded half-up line by line. Costs $0.01 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["invoice", "quote"]}, "customer": {"type": "object", "additionalProperties": false, "description": "Who the document is for. Link a CRM record with contact_id or company_id, or give name and email (an email that matches a CRM contact links it). What is given here is printed as it is.", "properties": {"contact_id": {"type": "integer", "minimum": 1, "description": "A CRM contact; fills the name and email."}, "company_id": {"type": "integer", "minimum": 1, "description": "A CRM company; fills the name."}, "name": {"type": "string", "maxLength": 200, "description": "Who is billed, as printed."}, "email": {"type": "string", "maxLength": 254, "description": "Where the document is emailed."}, "address": {"type": "string", "maxLength": 1000, "description": "Postal address, one line per row."}, "tax_id": {"type": "string", "maxLength": 60, "description": "The customer's VAT or tax number, for business customers. A reverse-charge or intra-EU invoice needs their EU VAT ID, e.g. \"FR12345678901\"."}, "country": {"type": "string", "maxLength": 2, "description": "ISO 3166-1 code of the customer's country, e.g. \"FR\". Checks intra_eu and export invoices; e-invoices need it."}}}, "items": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["description", "unit_price"], "properties": {"description": {"type": "string", "maxLength": 2000, "minLength": 1, "description": "What was sold. Lines after the first print smaller, underneath."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Default 1. Up to 6 decimals, e.g. 1.5 (hours)."}, "unit_price": {"type": ["number", "string"], "maxLength": 24, "description": "The price of one, before tax, e.g. \"19.99\". Negative for a credit line."}, "tax_rate": {"type": ["number", "string"], "maxLength": 24, "description": "Tax percent, e.g. 19. Default: the profile's tax_rate."}, "discount": {"type": ["number", "string"], "maxLength": 24, "description": "Discount percent on this line, e.g. 10."}, "account": {"type": "string", "maxLength": 20, "description": "With books: the income account this line books to, e.g. \"4100\" for services. Default: the sales account."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "With books: tracking options, e.g. {\"Department\": \"Service\"}."}}}}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"USD\", \"EUR\" or \"JPY\"."}, "notes": {"type": "string", "maxLength": 5000, "description": "Printed above the lines, e.g. \"Thank you for your order\" or a project reference."}, "payment_link": {"type": "string", "maxLength": 500, "description": "An https link to pay this document. Default: the profile's payment_link."}, "tax_exemption": {"type": "string", "enum": ["", "exempt", "zero_rated", "reverse_charge", "intra_eu", "export", "outside_scope", "small_business"], "description": "Why lines with tax_rate 0 carry no tax, printed on the invoice as the law asks: exempt, zero_rated, reverse_charge (the customer accounts for the VAT), intra_eu (goods to a business in another EU country), export (goods leaving the EU), outside_scope, small_business (a business under its country's small-business VAT exemption, such as UStG §19 or art. 293 B CGI: no line may carry tax). Needed in the EU for any line without tax. Default: the profile's."}, "tax_exemption_note": {"type": "string", "maxLength": 300, "description": "The wording printed for the exemption instead of the standard one, e.g. \"Steuerbefreit als Kleinunternehmer nach § 19 UStG\"."}, "e_invoice": {"type": "string", "enum": ["", "factur-x", "xrechnung", "none"], "description": "Invoices and their credit notes as EN 16931 e-invoices (German B2B invoices must be from 2027): factur-x (Factur-X/ZUGFeRD, the XML inside the PDF/A-3) or xrechnung (XRechnung 3.0, its own XML beside the PDF), checked against the EN 16931 schema before sending. \"\" is the default: none, except that from 2027 an invoice from a German business to a German business above EUR 250 is a factur-x; \"none\" opts out (a business under the EUR 800,000 turnover allowance until 2028). Needs the customer's country. Default: the profile's."}, "vat_exchange_rate": {"type": ["number", "string", "null"], "maxLength": 24, "description": "For an invoice in another currency than the national one of the business's country: one unit of it in the national currency, for the VAT shown in both. Default in the EU: the European Central Bank's rate for the day of supply; UK businesses give it."}, "supply_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoices: the day the goods or services were supplied, or the first day of a period. Default: the issue date, which the invoice then states."}, "supply_until": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoices: the last day of the supply period, e.g. a month of service."}, "issue_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Default: the day it is sent."}, "due_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoices. Default: issue date + the payment terms."}, "payment_terms_days": {"type": "integer", "minimum": 0, "maximum": 365, "description": "Invoices: days to pay, instead of the profile's terms."}, "valid_until": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Quotes. Default: issue date + the profile's quote_valid_days."}}, "required": ["kind", "customer", "items"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_set_expected_date": {"post": {"operationId": "invoices_set_expected_date", "summary": "Set when a customer will pay", "description": "The day a customer said they would pay an invoice that is sent and not paid yet, like Xero's expected date: the cash flow forecast (books_report cash_forecast) counts the invoice on that day, even one already overdue, which it otherwise leaves out. null clears it. Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to go back to the default."}}, "required": ["invoice_id", "date"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_update": {"post": {"operationId": "invoices_update", "summary": "Change a draft", "description": "Change a draft quote or invoice: give only what changes; customer and items replace the old ones. A sent document can't change: void it with invoices_void and create a new one. Costs $0.01 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "customer": {"type": "object", "additionalProperties": false, "description": "Who the document is for. Link a CRM record with contact_id or company_id, or give name and email (an email that matches a CRM contact links it). What is given here is printed as it is.", "properties": {"contact_id": {"type": "integer", "minimum": 1, "description": "A CRM contact; fills the name and email."}, "company_id": {"type": "integer", "minimum": 1, "description": "A CRM company; fills the name."}, "name": {"type": "string", "maxLength": 200, "description": "Who is billed, as printed."}, "email": {"type": "string", "maxLength": 254, "description": "Where the document is emailed."}, "address": {"type": "string", "maxLength": 1000, "description": "Postal address, one line per row."}, "tax_id": {"type": "string", "maxLength": 60, "description": "The customer's VAT or tax number, for business customers. A reverse-charge or intra-EU invoice needs their EU VAT ID, e.g. \"FR12345678901\"."}, "country": {"type": "string", "maxLength": 2, "description": "ISO 3166-1 code of the customer's country, e.g. \"FR\". Checks intra_eu and export invoices; e-invoices need it."}}}, "items": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["description", "unit_price"], "properties": {"description": {"type": "string", "maxLength": 2000, "minLength": 1, "description": "What was sold. Lines after the first print smaller, underneath."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Default 1. Up to 6 decimals, e.g. 1.5 (hours)."}, "unit_price": {"type": ["number", "string"], "maxLength": 24, "description": "The price of one, before tax, e.g. \"19.99\". Negative for a credit line."}, "tax_rate": {"type": ["number", "string"], "maxLength": 24, "description": "Tax percent, e.g. 19. Default: the profile's tax_rate."}, "discount": {"type": ["number", "string"], "maxLength": 24, "description": "Discount percent on this line, e.g. 10."}, "account": {"type": "string", "maxLength": 20, "description": "With books: the income account this line books to, e.g. \"4100\" for services. Default: the sales account."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "With books: tracking options, e.g. {\"Department\": \"Service\"}."}}}}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"USD\", \"EUR\" or \"JPY\"."}, "notes": {"type": "string", "maxLength": 5000, "description": "Printed above the lines, e.g. \"Thank you for your order\" or a project reference."}, "payment_link": {"type": "string", "maxLength": 500, "description": "An https link to pay this document. Default: the profile's payment_link."}, "tax_exemption": {"type": "string", "enum": ["", "exempt", "zero_rated", "reverse_charge", "intra_eu", "export", "outside_scope", "small_business"], "description": "Why lines with tax_rate 0 carry no tax, printed on the invoice as the law asks: exempt, zero_rated, reverse_charge (the customer accounts for the VAT), intra_eu (goods to a business in another EU country), export (goods leaving the EU), outside_scope, small_business (a business under its country's small-business VAT exemption, such as UStG §19 or art. 293 B CGI: no line may carry tax). Needed in the EU for any line without tax. Default: the profile's."}, "tax_exemption_note": {"type": "string", "maxLength": 300, "description": "The wording printed for the exemption instead of the standard one, e.g. \"Steuerbefreit als Kleinunternehmer nach § 19 UStG\"."}, "e_invoice": {"type": "string", "enum": ["", "factur-x", "xrechnung", "none"], "description": "Invoices and their credit notes as EN 16931 e-invoices (German B2B invoices must be from 2027): factur-x (Factur-X/ZUGFeRD, the XML inside the PDF/A-3) or xrechnung (XRechnung 3.0, its own XML beside the PDF), checked against the EN 16931 schema before sending. \"\" is the default: none, except that from 2027 an invoice from a German business to a German business above EUR 250 is a factur-x; \"none\" opts out (a business under the EUR 800,000 turnover allowance until 2028). Needs the customer's country. Default: the profile's."}, "vat_exchange_rate": {"type": ["number", "string", "null"], "maxLength": 24, "description": "For an invoice in another currency than the national one of the business's country: one unit of it in the national currency, for the VAT shown in both. Default in the EU: the European Central Bank's rate for the day of supply; UK businesses give it."}, "issue_date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to go back to the default."}, "due_date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to go back to the default."}, "valid_until": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to go back to the default."}, "supply_date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to go back to the default."}, "supply_until": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to go back to the default."}, "payment_terms_days": {"type": ["integer", "null"], "minimum": 0, "maximum": 365}}, "required": ["invoice_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_get": {"post": {"operationId": "invoices_get", "summary": "Get a quote or invoice", "description": "One quote, invoice or credit note in full: lines with their amounts, totals and taxes, payments, credit notes, history, its public page and a fresh PDF link. Find it by invoice_id, or by number (with kind if documents of two kinds share it). Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "number": {"type": "string", "maxLength": 40, "description": "e.g. \"INV-0042\"."}, "kind": {"type": "string", "enum": ["quote", "invoice", "credit_note"]}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the PDF download link works, in hours (up to 168)."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_list": {"post": {"operationId": "invoices_list", "summary": "List quotes and invoices", "description": "Quotes, invoices and credit notes, newest first, filtered by kind, status (also overdue, unpaid and expired), customer and issue date. Totals and balances come with each one. Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["quote", "invoice", "credit_note"]}, "status": {"type": "string", "enum": ["draft", "sent", "accepted", "declined", "paid", "partially_paid", "void", "overdue", "unpaid", "expired"], "description": "overdue: past due with a balance. unpaid: sent invoices with a balance. expired: sent quotes past valid_until."}, "contact_id": {"type": "integer", "minimum": 1}, "company_id": {"type": "integer", "minimum": 1}, "customer": {"type": "string", "maxLength": 200, "description": "Part of the customer's name or email, or of the number."}, "date_from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Issued on or after (YYYY-MM-DD). Drafts have no issue date yet."}, "date_to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Issued on or before."}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_send": {"post": {"operationId": "invoices_send", "summary": "Send a quote or invoice", "description": "Send a draft: it takes the next number (gapless), its PDF is made and kept in the file store, and the customer is emailed a link to its page (to view, pay or accept it) and to the PDF. On a document already sent it emails it again (to `to`, if given). email: false sends it without emailing anyone, to hand the link over yourself. Emailing people outside the business needs a paid account. When the account keeps books (books_setup), a sent invoice is posted to them. Before an invoice or credit note takes its number it is checked against the law of the business's country (in the EU, the UK and Switzerland: the business's address and VAT ID, the customer's VAT ID and address where needed, why a line has no tax, the VAT in the national currency); what is missing is refused for free, warnings come back. With e_invoice set it also goes out as an EN 16931 e-invoice (Factur-X inside the PDF, or an XRechnung XML beside it), validated against the official schema first. Costs $0.10 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "email": {"type": "boolean", "default": true, "description": "false: number it and make the PDF and the page, but email no one."}, "to": {"type": "string", "maxLength": 254, "description": "Send to this address instead of the customer's email."}, "message": {"type": "string", "maxLength": 2000, "description": "A short note in the email, e.g. \"Thanks for your order!\""}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the PDF download link works, in hours (up to 168)."}}, "required": ["invoice_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_convert_quote": {"post": {"operationId": "invoices_convert_quote", "summary": "Turn a quote into an invoice", "description": "Turn an accepted quote into a draft invoice with the same customer and lines, ready for invoices_send. If the customer accepted some other way (email, phone), pass mark_accepted: true to record it. Costs $0.01 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"quote_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The quote's invoice_id."}, "mark_accepted": {"type": "boolean", "default": false, "description": "Record a sent quote as accepted first (the customer said yes)."}}, "required": ["quote_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_record_payment": {"post": {"operationId": "invoices_record_payment", "summary": "Record a payment", "description": "Record money received against a sent invoice: amount, date, method and reference. It becomes partially_paid, or paid when nothing is left. A payment can't be more than the balance, unless keep_excess keeps the rest as the customer's credit (an overpayment, like Xero's, for invoices_use_credit); a negative amount records a refund. When the account keeps books, it is posted to them. Costs $0.01 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "amount": {"type": ["number", "string"], "maxLength": 24, "description": "In the invoice's currency, e.g. \"250.00\". Negative for a refund."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "When it was paid. Default today."}, "method": {"type": "string", "enum": ["bank_transfer", "card", "cash", "check", "online", "other"], "default": "other"}, "reference": {"type": "string", "maxLength": 120, "description": "e.g. the bank transfer reference or the payment id."}, "note": {"type": "string", "maxLength": 500}, "keep_excess": {"type": "boolean", "default": false, "description": "Paid more than the balance: keep the rest as the customer's credit."}}, "required": ["invoice_id", "amount"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_record_prepayment": {"post": {"operationId": "invoices_record_prepayment", "summary": "Record a prepayment", "description": "Record money a customer paid before there is an invoice, like a deposit, as Xero's prepayments: it waits as their credit (CR-0001 on) until invoices_use_credit puts it on their invoice or pays it back. With tax_rate it carries its VAT, owed when the money came in (as the EU has it for advance payments); using it on the invoice takes that VAT back off, so the sale's VAT counts once. With books kept it is posted at once: the bank against Customer prepayments (2400, made when missing) and the tax owed. Costs $0.01 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"customer": {"type": "object", "additionalProperties": false, "description": "Who paid: a CRM contact or company, or a name and email.", "properties": {"contact_id": {"type": "integer", "minimum": 1, "description": "A CRM contact; fills the name and email."}, "company_id": {"type": "integer", "minimum": 1, "description": "A CRM company; fills the name."}, "name": {"type": "string", "maxLength": 200, "description": "Who is billed, as printed."}, "email": {"type": "string", "maxLength": 254, "description": "Where the document is emailed."}, "address": {"type": "string", "maxLength": 1000, "description": "Postal address, one line per row."}, "tax_id": {"type": "string", "maxLength": 60, "description": "The customer's VAT or tax number, for business customers. A reverse-charge or intra-EU invoice needs their EU VAT ID, e.g. \"FR12345678901\"."}, "country": {"type": "string", "maxLength": 2, "description": "ISO 3166-1 code of the customer's country, e.g. \"FR\". Checks intra_eu and export invoices; e-invoices need it."}}}, "amount": {"type": ["number", "string"], "maxLength": 24, "description": "What they paid, tax included, e.g. \"3570.00\"."}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"USD\", \"EUR\" or \"JPY\"."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "When it came in. Default today."}, "method": {"type": "string", "enum": ["bank_transfer", "card", "cash", "check", "online", "other"], "default": "bank_transfer"}, "reference": {"type": "string", "maxLength": 120}, "note": {"type": "string", "maxLength": 500}, "tax_rate": {"type": "number", "minimum": 0, "maximum": 100, "description": "The VAT in it, in percent, e.g. 19. Default none."}}, "required": ["customer", "amount"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_use_credit": {"post": {"operationId": "invoices_use_credit", "summary": "Use or pay back a credit", "description": "Put a customer's credit (a prepayment or an overpayment) on one of their sent invoices, like Xero's allocate credit: invoice_id, and amount (default all it can: what is left on the credit or the invoice, the smaller); the invoice records it as a payment with method credit, and its share of the credit's VAT comes back off. Or refund: true pays what is left (or amount) back to the customer, with date and method; or void: true takes back a prepayment recorded by mistake while none of it is used. Same customer and currency only. Costs $0.01 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"credit": {"type": "string", "maxLength": 20, "minLength": 1, "description": "The credit's number, like \"CR-0001\" (invoices_list_credits)."}, "invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "amount": {"type": ["number", "string"], "maxLength": 24}, "refund": {"type": "boolean", "default": false}, "void": {"type": "boolean", "default": false}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "method": {"type": "string", "enum": ["bank_transfer", "card", "cash", "check", "online", "other"], "default": "bank_transfer"}, "reference": {"type": "string", "maxLength": 120}}, "required": ["credit"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_list_credits": {"post": {"operationId": "invoices_list_credits", "summary": "List customer credits", "description": "Customers' credits, prepayments and overpayments, newest first: what each was, what is left, its VAT and how it was used or paid back. Filter by customer, or status (open, used, refunded, void, all; default open). Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"customer": {"type": "object", "additionalProperties": false, "properties": {"contact_id": {"type": "integer", "minimum": 1, "description": "A CRM contact; fills the name and email."}, "company_id": {"type": "integer", "minimum": 1, "description": "A CRM company; fills the name."}, "name": {"type": "string", "maxLength": 200, "description": "Who is billed, as printed."}, "email": {"type": "string", "maxLength": 254, "description": "Where the document is emailed."}}, "description": "The customer: a CRM contact or company, or the email or name on their invoices."}, "status": {"type": "string", "enum": ["open", "used", "refunded", "void", "all"], "default": "open"}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_create_credit_note": {"post": {"operationId": "invoices_create_credit_note", "summary": "Credit an invoice", "description": "Issue a credit note against a sent invoice: all of it, some of its lines, or an amount. It takes the next credit note number (gapless, CN-0001...), gets a PDF and a page like an invoice, and is emailed to the customer unless email is false. It lowers what the customer still owes; refunded: true says the money went back to them instead, and the invoice records the refund. In much of the EU a sent invoice is corrected this way, not voided. When the account keeps books, the sale and its tax are reversed there. Costs $0.10 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "lines": {"type": "array", "minItems": 1, "maxItems": 200, "description": "Lines of the invoice to credit, at its prices. Leave out lines and amount to credit the whole invoice (or what is left of it).", "items": {"type": "object", "additionalProperties": false, "required": ["line"], "properties": {"line": {"type": "integer", "minimum": 1, "description": "The invoice's line number, from 1, in the order invoices_get lists its items."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "How many to credit. Default: all of the line not credited yet."}}}}, "amount": {"type": ["number", "string"], "maxLength": 24, "description": "A sum to credit, tax included, e.g. \"50.00\" off for a late delivery. Its tax follows the invoice's rates (or those of `lines`, when given too)."}, "reason": {"type": "string", "maxLength": 500, "description": "Printed on the credit note, e.g. \"Returned: 1 bike rack\"."}, "refunded": {"type": "boolean", "default": false, "description": "true: the money went back to the customer (say how with method and reference). false: the credit lowers what they still owe."}, "method": {"type": "string", "enum": ["bank_transfer", "card", "cash", "check", "online", "other"], "default": "other", "description": "With refunded: how the money went back."}, "reference": {"type": "string", "maxLength": 120, "description": "With refunded: e.g. the bank transfer or refund id."}, "email": {"type": "boolean", "default": true, "description": "false: issue it without emailing anyone."}, "to": {"type": "string", "maxLength": 254, "description": "Email it to this address instead of the customer's."}, "message": {"type": "string", "maxLength": 2000, "description": "A short note in the email."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the PDF download link works, in hours (up to 168)."}}, "required": ["invoice_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_void": {"post": {"operationId": "invoices_void", "summary": "Void a quote or invoice", "description": "Void a document. A sent one keeps its number (numbers stay gapless) but can no longer be paid, accepted or viewed; a draft is simply discarded. Refused while payments are recorded on it, on an invoice with credit notes and on a credit note (correct those with another credit note or a new invoice), and on an invoice that may be in the customer's hands (emailed, opened, or its PDF downloaded through a link): that one is cancelled with a credit note for all of it, as the law asks. An invoice posted to the books is reversed there. Costs $0.01 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "reason": {"type": "string", "maxLength": 500}}, "required": ["invoice_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_remind": {"post": {"operationId": "invoices_remind", "summary": "Remind about an unpaid invoice", "description": "Email the customer a reminder about a sent invoice that still has a balance: the amount due, the due date and the links to pay. At most once a day per invoice. Costs $0.02 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The invoice_id invoices_create returned (quotes and credit notes have one too)."}, "message": {"type": "string", "maxLength": 2000, "description": "A short note in the email, e.g. \"Just a friendly reminder.\""}, "to": {"type": "string", "maxLength": 254, "description": "Send to this address instead of the customer's email."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the PDF download link works, in hours (up to 168)."}}, "required": ["invoice_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_remind_overdue": {"post": {"operationId": "invoices_remind_overdue", "summary": "Remind everyone who is overdue", "description": "Email a reminder about every sent invoice at least days_overdue days past its due date that still has a balance, the longest overdue first, up to limit invoices: one call, or one weekly schedule (schedules_create), chases them all. Each invoice is reminded at most once a day; the ones that can't be (no customer email, emailed in the last 24 hours, the address bounced) are listed with why. $0.02 per reminder sent. Costs $0.02 per reminder sent; nothing if none are found.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"days_overdue": {"type": "integer", "minimum": 1, "maximum": 365, "default": 1}, "message": {"type": "string", "maxLength": 2000, "description": "A short note in each email, e.g. \"Just a friendly reminder.\""}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24, "description": "How long the PDF download link works, in hours (up to 168)."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_save_repeating": {"post": {"operationId": "invoices_save_repeating", "summary": "Repeat an invoice", "description": "An invoice made again every so many weeks, months or years, like Xero's repeating invoices: the customer and lines as for invoices_create, every and unit, the start date, and an end_date or a number of times. action draft leaves each one for you to check and send; send emails it to the customer on its day. Descriptions and notes may hold [Month], [Year], [Quarter] or [Week], with an offset like [Month+1], filled in from each invoice's date. Each invoice is made by Conecto's worker as this key and costs what invoices_create and invoices_send cost. Change one by repeating_id: only what you pass changes; status paused stops it, active resumes it (dates it missed are skipped). Costs $0.001 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"repeating_id": {"type": "integer", "minimum": 1, "description": "From invoices_list_repeating."}, "name": {"type": "string", "maxLength": 120, "description": "Your own label, e.g. \"Hotel service contract\"."}, "customer": {"type": "object", "additionalProperties": false, "description": "Who the document is for. Link a CRM record with contact_id or company_id, or give name and email (an email that matches a CRM contact links it). What is given here is printed as it is.", "properties": {"contact_id": {"type": "integer", "minimum": 1, "description": "A CRM contact; fills the name and email."}, "company_id": {"type": "integer", "minimum": 1, "description": "A CRM company; fills the name."}, "name": {"type": "string", "maxLength": 200, "description": "Who is billed, as printed."}, "email": {"type": "string", "maxLength": 254, "description": "Where the document is emailed."}, "address": {"type": "string", "maxLength": 1000, "description": "Postal address, one line per row."}, "tax_id": {"type": "string", "maxLength": 60, "description": "The customer's VAT or tax number, for business customers. A reverse-charge or intra-EU invoice needs their EU VAT ID, e.g. \"FR12345678901\"."}, "country": {"type": "string", "maxLength": 2, "description": "ISO 3166-1 code of the customer's country, e.g. \"FR\". Checks intra_eu and export invoices; e-invoices need it."}}}, "items": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["description", "unit_price"], "properties": {"description": {"type": "string", "maxLength": 2000, "minLength": 1, "description": "What was sold. Lines after the first print smaller, underneath."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Default 1. Up to 6 decimals, e.g. 1.5 (hours)."}, "unit_price": {"type": ["number", "string"], "maxLength": 24, "description": "The price of one, before tax, e.g. \"19.99\". Negative for a credit line."}, "tax_rate": {"type": ["number", "string"], "maxLength": 24, "description": "Tax percent, e.g. 19. Default: the profile's tax_rate."}, "discount": {"type": ["number", "string"], "maxLength": 24, "description": "Discount percent on this line, e.g. 10."}, "account": {"type": "string", "maxLength": 20, "description": "With books: the income account this line books to, e.g. \"4100\" for services. Default: the sales account."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "With books: tracking options, e.g. {\"Department\": \"Service\"}."}}}}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"USD\", \"EUR\" or \"JPY\"."}, "notes": {"type": "string", "maxLength": 5000, "description": "Printed above the lines, e.g. \"Thank you for your order\" or a project reference."}, "payment_link": {"type": "string", "maxLength": 500, "description": "An https link to pay this document. Default: the profile's payment_link."}, "tax_exemption": {"type": "string", "enum": ["", "exempt", "zero_rated", "reverse_charge", "intra_eu", "export", "outside_scope", "small_business"], "description": "Why lines with tax_rate 0 carry no tax, printed on the invoice as the law asks: exempt, zero_rated, reverse_charge (the customer accounts for the VAT), intra_eu (goods to a business in another EU country), export (goods leaving the EU), outside_scope, small_business (a business under its country's small-business VAT exemption, such as UStG §19 or art. 293 B CGI: no line may carry tax). Needed in the EU for any line without tax. Default: the profile's."}, "tax_exemption_note": {"type": "string", "maxLength": 300, "description": "The wording printed for the exemption instead of the standard one, e.g. \"Steuerbefreit als Kleinunternehmer nach § 19 UStG\"."}, "e_invoice": {"type": "string", "enum": ["", "factur-x", "xrechnung", "none"], "description": "Invoices and their credit notes as EN 16931 e-invoices (German B2B invoices must be from 2027): factur-x (Factur-X/ZUGFeRD, the XML inside the PDF/A-3) or xrechnung (XRechnung 3.0, its own XML beside the PDF), checked against the EN 16931 schema before sending. \"\" is the default: none, except that from 2027 an invoice from a German business to a German business above EUR 250 is a factur-x; \"none\" opts out (a business under the EUR 800,000 turnover allowance until 2028). Needs the customer's country. Default: the profile's."}, "payment_terms_days": {"type": "integer", "minimum": 0, "maximum": 365, "description": "Each invoice falls due this long after its date. Default: the profile's payment terms."}, "every": {"type": "integer", "minimum": 1, "maximum": 52, "description": "Default 1."}, "unit": {"type": "string", "enum": ["week", "month", "year"]}, "start": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The first invoice's date, today or later. Monthly and yearly invoices keep to its day of the month."}, "end_date": {"type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$", "description": "No invoice after this date. \"\" for none."}, "times": {"type": "integer", "minimum": 1, "maximum": 1000, "description": "How many invoices in all."}, "status": {"type": "string", "enum": ["active", "paused"]}, "action": {"type": "string", "enum": ["draft", "send"], "description": "Default draft."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_list_repeating": {"post": {"operationId": "invoices_list_repeating", "summary": "List repeating invoices", "description": "The repeating invoices: who each is for, its lines, how often, the next dates, whether it is drafted or sent, how many were made and the last one, and why one is paused. Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["active", "paused", "ended"]}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_delete_repeating": {"post": {"operationId": "invoices_delete_repeating", "summary": "Stop a repeating invoice", "description": "Stop a repeating invoice for good. The invoices it made stay as they are. Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"repeating_id": {"type": "integer", "minimum": 1, "description": "From invoices_list_repeating."}}, "required": ["repeating_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_statement": {"post": {"operationId": "invoices_statement", "summary": "Make a customer statement", "description": "A customer statement, like Xero's. outstanding (the default) lists every invoice the customer still owed on as_of (default today) with what was paid or credited, how late each is and the money owed by how late; activity starts from what they owed before from, lists each invoice, payment and credit note up to to (default this month so far) with the running balance, and ends with what they owed. One currency (default the one they are billed in most). It is a PDF in the file store in the business's look and document language; email: true also emails the customer a link to it in the business's name, under the rules every bot email follows and at most once a day per customer. $0.05. Costs $0.05 per call; nothing if it fails.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"customer": {"type": "object", "additionalProperties": false, "description": "Whose statement: a CRM contact_id or company_id, or the email or the name on their invoices.", "properties": {"contact_id": {"type": "integer", "minimum": 1}, "company_id": {"type": "integer", "minimum": 1}, "email": {"type": "string", "maxLength": 254}, "name": {"type": "string", "maxLength": 200}}}, "kind": {"type": "string", "enum": ["outstanding", "activity"]}, "as_of": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"USD\", \"EUR\" or \"JPY\"."}, "email": {"type": "boolean", "default": false}, "send_to": {"type": "string", "maxLength": 254, "description": "Another address to email it to."}, "message": {"type": "string", "maxLength": 2000, "description": "Your own words above the amount due."}, "link_hours": {"type": "integer", "minimum": 1, "maximum": 168, "default": 24}}, "required": ["customer"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_report": {"post": {"operationId": "invoices_report", "summary": "Run a receivables report", "description": "aged_receivables: what each customer owes on as_of (default today), by how long past due: current (not due yet), 1-30, 31-60, 61-90 and over 90 days, per currency. sales: what was invoiced from-to (by issue date; default this month) per customer, less the credit notes issued in it: net, tax and total, and what was paid in it. To show a person, put it in a view (view_show). Free. Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"report": {"type": "string", "enum": ["aged_receivables", "sales"]}, "as_of": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}}, "required": ["report"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/invoices_summary": {"post": {"operationId": "invoices_summary", "summary": "What customers owe", "description": "What customers owe, per currency: outstanding, overdue and paid this month, plus quotes still open. Free.", "tags": ["invoices"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/qr_create": {"post": {"operationId": "qr_create", "summary": "Make a QR code", "description": "A QR code for a link or any text (a payment link, a booking page, Wi-Fi details), saved in the file store as PNG or SVG with a download link. Dark modules must contrast with the background so phones can read it. Costs $0.01 per call; nothing if it fails.", "tags": ["links"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "string", "minLength": 1, "maxLength": 2000}, "name": {"type": "string", "maxLength": 200, "description": "File name; defaults to \"QR code\"."}, "format": {"type": "string", "enum": ["png", "svg"], "default": "png"}, "size": {"type": "integer", "minimum": 128, "maximum": 2048, "default": 1024, "description": "PNG width and height in pixels."}, "dark": {"type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#171717"}, "light": {"type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#ffffff"}, "error_correction": {"type": "string", "enum": ["low", "medium", "quartile", "high"], "default": "medium", "description": "Higher survives damage or a logo on top, at the cost of density."}}, "required": ["data"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/links_shorten": {"post": {"operationId": "links_shorten", "summary": "Make a short link", "description": "A short link at cncto.co/<code> that sends people to url and counts the clicks, for messages, print and QR codes. Give alias for a readable one (cncto.co/spring-sale) or leave it out for a random 7-character code. The destination can be changed later; a deleted link's code is never reused. Needs an account that has topped up once. Costs $0.01 per call; nothing if it fails.", "tags": ["links"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"url": {"type": "string", "minLength": 8, "maxLength": 2000, "description": "Where it goes: https://..."}, "alias": {"type": "string", "minLength": 3, "maxLength": 40, "description": "Lower-case letters, digits and dashes, e.g. \"spring-sale\"."}, "title": {"type": "string", "maxLength": 200, "description": "A note for yourself, e.g. \"Flyer, October\"."}}, "required": ["url"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/links_list": {"post": {"operationId": "links_list", "summary": "List short links", "description": "This account's short links, newest first, with their clicks. query matches the code, title or address. Free.", "tags": ["links"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "maxLength": 200}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/links_get": {"post": {"operationId": "links_get", "summary": "Get a short link", "description": "One short link: where it goes, its clicks and the last click. Free.", "tags": ["links"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"code": {"type": "string", "minLength": 3, "maxLength": 40, "description": "The code after cncto.co/, e.g. \"x7Kp2Qa\"."}}, "required": ["code"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/links_update": {"post": {"operationId": "links_update", "summary": "Change a short link", "description": "Send a short link somewhere else, retitle it, or pause it (a paused link shows a page saying so) and resume it. Give only what changes. Costs $0.01 per call; nothing if it fails.", "tags": ["links"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"code": {"type": "string", "minLength": 3, "maxLength": 40, "description": "The code after cncto.co/, e.g. \"x7Kp2Qa\"."}, "url": {"type": "string", "minLength": 8, "maxLength": 2000}, "title": {"type": "string", "maxLength": 200}, "paused": {"type": "boolean"}}, "required": ["code"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/links_delete": {"post": {"operationId": "links_delete", "summary": "Delete a short link", "description": "Delete a short link for good. Its code stays retired, so it never opens anything again. Free.", "tags": ["links"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"code": {"type": "string", "minLength": 3, "maxLength": 40, "description": "The code after cncto.co/, e.g. \"x7Kp2Qa\"."}}, "required": ["code"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/lookup_company": {"post": {"operationId": "lookup_company", "summary": "Look up a company", "description": "What a company is, from its domain: name, description, location, industries, size, funding, languages, the technologies its site uses, its shared mailboxes (info@, sales@ ...) and phone numbers, and its social profiles. From Conecto's index of public company facts, else from its own homepage. Never people. The business's Conecto inboxes never write first to a mailbox found here. $0.05 when found; free when nothing is known. Costs $0.05 per call; nothing if it fails.", "tags": ["lookups"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The company's web address, e.g. hansenvoss.example."}}, "required": ["domain"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/email_verify": {"post": {"operationId": "email_verify", "summary": "Check email addresses", "description": "Whether each address can take mail: deliverable, undeliverable, risky (a disposable provider, or a domain that accepts every address) or unknown, with the checks behind it (syntax, mail servers, disposable or free provider, shared mailbox, and the mailbox itself, asked of its mail server without sending anything). Up to 50 at a time. The business's Conecto inboxes never write first to an address checked here. $0.005 per address with a verdict; unknown is free. Costs $0.005 per address with a verdict; nothing if none are found.", "tags": ["lookups"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"emails": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "string", "maxLength": 254}}}, "required": ["emails"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_connect_service": {"post": {"operationId": "newsletters_connect_service", "summary": "Connect the business's email service", "description": "Newsletters go out through the business's own email service, from an address on its own domain: any service that takes mail over SMTP, such as Brevo, Amazon SES, Mailgun, Postmark, SendGrid, Mailchimp Transactional or the web host. Give its SMTP server, login and the from address; Conecto logs in to check them and keeps the password encrypted, never shown again. Calling it again replaces them, and issues waiting for the service go out on the next round. With test_to, a short email also goes out, which shows the service takes mail from that address. Free. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"host": {"type": "string", "minLength": 3, "maxLength": 255, "description": "The SMTP server, e.g. smtp-relay.brevo.com or email-smtp.eu-west-1.amazonaws.com."}, "port": {"type": "integer", "minimum": 1, "maximum": 65535, "default": 587, "description": "587 (STARTTLS) or 465 (SSL/TLS). Port 25 is blocked on Conecto's servers."}, "security": {"type": "string", "enum": ["starttls", "ssl"], "description": "starttls or ssl. Left out: ssl on port 465, starttls otherwise."}, "username": {"type": "string", "minLength": 1, "maxLength": 254, "description": "The SMTP login (for Brevo the SMTP login, for SendGrid \"apikey\")."}, "password": {"type": "string", "minLength": 1, "maxLength": 1000, "description": "The SMTP password or key (for Brevo an SMTP key, not the account password).", "writeOnly": true}, "from_email": {"type": "string", "maxLength": 254, "description": "The address issues come from, on a domain the service lets the business send from, e.g. news@halversoncycle.com."}, "per_day": {"type": "integer", "minimum": 1, "maximum": 10000000, "description": "The service's own daily limit, if it has one (Brevo's free plan: 300). Issues then go out over several days."}, "test_to": {"type": "string", "maxLength": 254, "description": "Also send a short test email to this address."}}, "required": ["host", "username", "password", "from_email"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_remove_service": {"post": {"operationId": "newsletters_remove_service", "summary": "Disconnect the email service", "description": "Forget the business's email service and its password. Until another is connected, newsletters take no sign-ups, send no invitations, and issues going out wait. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_create": {"post": {"operationId": "newsletters_create", "summary": "Create a newsletter", "description": "A newsletter people join on its own page (cncto.co/n/<name>) by confirming their address, like Buttondown or listmonk. Issues go out through the business's own email service (connect it first with newsletters_connect_service); every issue carries postal_address (the law in the US and the EU asks for one) and a one-click unsubscribe. Free; needs an account that has topped up once. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 120, "description": "e.g. \"Halverson Ride Notes\"."}, "postal_address": {"type": "string", "minLength": 10, "maxLength": 300, "description": "The business's postal address, shown at the foot of every issue."}, "description": {"type": "string", "maxLength": 500, "description": "One or two lines on its page: what it is and how often it comes."}, "public_archive": {"type": "boolean", "default": true, "description": "Show past issues on its page."}}, "required": ["name", "postal_address"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_update": {"post": {"operationId": "newsletters_update", "summary": "Change a newsletter", "description": "Rename it, or change its description, postal address or archive. Give only what changes. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"newsletter": {"type": "string", "minLength": 1, "maxLength": 120, "description": "The newsletter's slug (from newsletters_list) or its exact name."}, "name": {"type": "string", "minLength": 1, "maxLength": 120}, "postal_address": {"type": "string", "minLength": 10, "maxLength": 300}, "description": {"type": "string", "maxLength": 500}, "public_archive": {"type": "boolean"}}, "required": ["newsletter"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_list": {"post": {"operationId": "newsletters_list", "summary": "List newsletters", "description": "This account's newsletters with their pages and subscriber counts, and the email service they go out through. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_invite": {"post": {"operationId": "newsletters_invite", "summary": "Invite people to a newsletter", "description": "Email each person a request to confirm their subscription: only those who press Confirm ever get an issue. For people who asked to hear from the business. Skips anyone already in, invited in the last day, unsubscribed or undeliverable. At most 20 invitations a day per account. Free: they go out through the business's own email service. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"newsletter": {"type": "string", "minLength": 1, "maxLength": 120, "description": "The newsletter's slug (from newsletters_list) or its exact name."}, "people": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "object", "required": ["email"], "additionalProperties": false, "properties": {"email": {"type": "string", "maxLength": 254}, "name": {"type": "string", "maxLength": 120}}}}, "how_they_asked": {"type": "string", "minLength": 3, "maxLength": 300, "description": "How these people asked to hear from the business, like \"they signed up at the counter\" or \"they asked for it by email\". The invitations are checked first: people who never asked are cold outreach, and nobody is invited."}}, "required": ["newsletter", "people", "how_they_asked"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_subscribers": {"post": {"operationId": "newsletters_subscribers", "summary": "List subscribers", "description": "Who is on a newsletter, newest first: active (confirmed), pending (not yet confirmed), unsubscribed, bounced or complained. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"newsletter": {"type": "string", "minLength": 1, "maxLength": 120, "description": "The newsletter's slug (from newsletters_list) or its exact name."}, "status": {"type": "string", "enum": ["active", "pending", "unsubscribed", "bounced", "complained"]}, "query": {"type": "string", "maxLength": 200}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": ["newsletter"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_remove_subscriber": {"post": {"operationId": "newsletters_remove_subscriber", "summary": "Remove a subscriber", "description": "Delete someone from a newsletter for good, with their history (for example when they ask to be forgotten). To only stop their issues, they unsubscribe themselves. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"newsletter": {"type": "string", "minLength": 1, "maxLength": 120, "description": "The newsletter's slug (from newsletters_list) or its exact name."}, "email": {"type": "string", "maxLength": 254}}, "required": ["newsletter", "email"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_write_issue": {"post": {"operationId": "newsletters_write_issue", "summary": "Write an issue", "description": "A draft issue in Markdown. Look at it with newsletters_send_test, then send it with newsletters_send_issue. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"newsletter": {"type": "string", "minLength": 1, "maxLength": 120, "description": "The newsletter's slug (from newsletters_list) or its exact name."}, "subject": {"type": "string", "minLength": 1, "maxLength": 200}, "body": {"type": "string", "minLength": 1, "maxLength": 100000, "description": "Markdown: headings, lists, links, bold, quotes, tables and https images."}, "preheader": {"type": "string", "maxLength": 200, "description": "The line mail apps show after the subject."}}, "required": ["newsletter", "subject", "body"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_update_issue": {"post": {"operationId": "newsletters_update_issue", "summary": "Change a draft issue", "description": "Change a draft's subject, body or preheader. Give only what changes. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"issue_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The issue_id newsletters_write_issue returned."}, "subject": {"type": "string", "minLength": 1, "maxLength": 200}, "body": {"type": "string", "minLength": 1, "maxLength": 100000, "description": "Markdown: headings, lists, links, bold, quotes, tables and https images."}, "preheader": {"type": "string", "maxLength": 200}}, "required": ["issue_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_send_test": {"post": {"operationId": "newsletters_send_test", "summary": "Send a test of an issue", "description": "Email an issue as subscribers will see it to up to 5 addresses (the owner, a colleague), with \"[Test]\" before the subject, through the business's own email service. Links are not counted and nothing is numbered. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"issue_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The issue_id newsletters_write_issue returned."}, "to": {"type": "array", "minItems": 1, "maxItems": 5, "items": {"type": "string", "maxLength": 254}}}, "required": ["issue_id", "to"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_send_issue": {"post": {"operationId": "newsletters_send_issue", "summary": "Send an issue", "description": "Send a draft to everyone who confirmed, now or at send_at, through the business's own email service. It goes out in batches, within the service's daily limit when one is set; newsletters_get_issue shows how far it got. It is checked first: one that looks like cold outreach isn't sent. Free. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"issue_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The issue_id newsletters_write_issue returned."}, "send_at": {"type": "string", "maxLength": 40, "description": "When, as ISO 8601 with a time zone, e.g. 2026-10-20T09:00:00+02:00. Now if left out."}}, "required": ["issue_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_cancel_issue": {"post": {"operationId": "newsletters_cancel_issue", "summary": "Cancel an issue", "description": "Stop a scheduled issue, or one still going out. Whatever went out already stays sent. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"issue_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The issue_id newsletters_write_issue returned."}}, "required": ["issue_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_get_issue": {"post": {"operationId": "newsletters_get_issue", "summary": "Get an issue", "description": "One issue: its text, where it stands (with what holds it up, if anything), and once sent how many it reached, bounced, unsubscribed and clicked, link by link. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"issue_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The issue_id newsletters_write_issue returned."}}, "required": ["issue_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/newsletters_list_issues": {"post": {"operationId": "newsletters_list_issues", "summary": "List issues", "description": "A newsletter's issues, newest first. Free.", "tags": ["newsletters"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"newsletter": {"type": "string", "minLength": 1, "maxLength": 120, "description": "The newsletter's slug (from newsletters_list) or its exact name."}, "status": {"type": "string", "enum": ["draft", "scheduled", "sending", "sent", "failed", "cancelled"]}}, "required": ["newsletter"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_add_channel": {"post": {"operationId": "notify_add_channel", "summary": "Add a notification channel", "description": "Save a place to send messages, by name: Slack, Microsoft Teams, Discord or Google Chat (an incoming webhook URL), Telegram (bot_token and chat_id), ntfy (topic, optional server and access_token), Pushover (user_key and app_token), or your own webhook (url; each request is signed with a secret returned once). A test message is sent first unless send_test is false; if it doesn't arrive, nothing is saved or charged. Tokens are stored encrypted and never shown back. Costs $0.001 per call; nothing if it fails.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "A short name for the channel, e.g. \"sales-alerts\" (lowercase letters, numbers, dashes)."}, "kind": {"type": "string", "enum": ["slack", "teams", "discord", "google_chat", "telegram", "ntfy", "pushover", "webhook"]}, "webhook_url": {"type": "string", "maxLength": 1000, "writeOnly": true}, "bot_token": {"type": "string", "maxLength": 100, "writeOnly": true}, "chat_id": {"type": "string", "maxLength": 40}, "topic": {"type": "string", "maxLength": 64}, "server": {"type": "string", "maxLength": 300}, "access_token": {"type": "string", "maxLength": 200, "writeOnly": true}, "user_key": {"type": "string", "maxLength": 40, "writeOnly": true}, "app_token": {"type": "string", "maxLength": 40, "writeOnly": true}, "url": {"type": "string", "maxLength": 1000}, "send_test": {"type": "boolean", "default": true}}, "required": ["name", "kind"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_list_channels": {"post": {"operationId": "notify_list_channels", "summary": "List notification channels", "description": "The saved channels, where each one goes (never its token), and whether the last message arrived. Free.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_remove_channel": {"post": {"operationId": "notify_remove_channel", "summary": "Remove a notification channel", "description": "Delete a saved channel. Free.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "A short name for the channel, e.g. \"sales-alerts\" (lowercase letters, numbers, dashes)."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_send": {"post": {"operationId": "notify_send", "summary": "Send a notification", "description": "Send a message to one or more saved channels. Charged only for the channels it reached. Costs $0.005 per channel reached; nothing if none are found.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channels": {"type": "array", "items": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "A short name for the channel, e.g. \"sales-alerts\" (lowercase letters, numbers, dashes)."}, "minItems": 1, "maxItems": 10}, "message": {"type": "string", "minLength": 1, "maxLength": 4000}, "title": {"type": "string", "maxLength": 200}, "link": {"type": "string", "maxLength": 1000, "pattern": "^https://", "description": "An https link to open, e.g. the deal or ticket."}, "urgent": {"type": "boolean", "default": false, "description": "High priority where the channel has one (ntfy, Pushover)."}}, "required": ["channels", "message"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_list_events": {"post": {"operationId": "notify_list_events", "summary": "List events", "description": "Every event a channel can receive on its own: a new job application, a booking, a form response, a signed document, a customer reply, a site going down and more. Free.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_subscribe": {"post": {"operationId": "notify_subscribe", "summary": "Send events to a channel", "description": "Send events to a saved channel as they happen, so the business's own tools hear about them: Slack, Teams, Discord, Google Chat, Telegram, ntfy, Pushover, or a webhook (signed JSON with the event's data; use one to connect Zapier, Make, n8n or your own systems). Replaces the channel's list. Free to send. Costs $0.001 per call; nothing if it fails.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channel": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "A short name for the channel, e.g. \"sales-alerts\" (lowercase letters, numbers, dashes)."}, "events": {"type": "array", "minItems": 1, "maxItems": 30, "items": {"type": "string"}, "description": "Event names from notify_list_events, \"hiring.*\", your bots' \"custom.*\", or \"*\"."}}, "required": ["channel", "events"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_unsubscribe": {"post": {"operationId": "notify_unsubscribe", "summary": "Stop events to a channel", "description": "Stop sending events to a channel. The channel stays for notify_send. Free.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channel": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "A short name for the channel, e.g. \"sales-alerts\" (lowercase letters, numbers, dashes)."}}, "required": ["channel"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_request_approval": {"post": {"operationId": "notify_request_approval", "summary": "Ask a person to approve", "description": "Ask a person before you act: approve or decline (or pick one of up to 5 options), with an optional comment, on a one-time page sent through a saved channel or by email. The first answer reaches you as the event notify.answered (subscribe a webhook, or check notify_get_approval). For refunds, big orders, offers and posts. Anyone holding the link can answer, so send it only to the person who decides. Email follows the account's rules (free credit emails only the owner). $0.01 a request, $0.02 more by email; the answer is free. Costs $0.01 a request, $0.02 more by email (at most $0.03 a call); nothing if it fails.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"question": {"type": "string", "minLength": 1, "maxLength": 300, "description": "What to decide, e.g. \"Refund order 1042 in full ($849)?\""}, "details": {"type": "string", "maxLength": 4000, "description": "What the person should know first."}, "options": {"type": "array", "minItems": 2, "maxItems": 5, "uniqueItems": true, "items": {"type": "string", "minLength": 1, "maxLength": 80}, "description": "The answers to pick from. Default: Approve, Decline."}, "comment": {"type": "boolean", "default": true, "description": "Offer a comment box."}, "channel": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "A saved channel to send it to (notify_list_channels)."}, "email": {"type": "string", "maxLength": 254, "description": "Or an email address to send it to."}, "expires_in_hours": {"type": "integer", "minimum": 1, "maximum": 720, "default": 72}, "reference": {"type": "string", "maxLength": 120, "description": "Your own reference, sent back with the answer (an order number, a refund)."}}, "required": ["question"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/notify_get_approval": {"post": {"operationId": "notify_get_approval", "summary": "Check an approval", "description": "Where a question you asked with notify_request_approval stands: waiting, answered (with the answer and the comment), expired or cancelled. The answer also comes as the event notify.answered. Free.", "tags": ["notify"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"request_id": {"type": "string", "minLength": 36, "maxLength": 36}}, "required": ["request_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/phone_search_numbers": {"post": {"operationId": "phone_search_numbers", "summary": "Find a phone number", "description": "Numbers the business can rent right now, with the monthly price. Rent one by passing its quote to phone_rent_number (quotes last 30 minutes). Bots can rent numbers where the carrier needs no identity documents and answering a call costs less than the $0.25 a minute charged, which includes the US and Canada; for other countries this says why not. Free.", "tags": ["phone"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"country": {"type": "string", "pattern": "^[A-Za-z]{2}$", "default": "US", "description": "Two-letter country code, e.g. US or CA."}, "type": {"type": "string", "enum": ["local", "mobile"], "default": "local"}, "area_code": {"type": "string", "pattern": "^[0-9]{2,6}$", "description": "Digits the number should start with after the country code, e.g. 503."}, "city": {"type": "string", "maxLength": 80, "description": "A city the local number should belong to."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/phone_rent_number": {"post": {"operationId": "phone_rent_number", "summary": "Rent a phone number", "description": "Rent a number found by phone_search_numbers. It is the business's at once; callers reach the AI assistant after phone_setup_assistant has run. This call pays the first month; it then renews monthly from the balance (if the balance is short there are 7 days' grace, then the number is released). Up to 5 numbers per account. Costs the price in the quote (at most $25.00); nothing if it fails.", "tags": ["phone"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"quote": {"type": "string", "minLength": 20, "maxLength": 4000, "description": "The quote of the number to rent, from phone_search_numbers."}}, "required": ["quote"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/phone_list_numbers": {"post": {"operationId": "phone_list_numbers", "summary": "List phone numbers", "description": "The numbers this account rents, with their monthly price and next renewal. Free.", "tags": ["phone"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/phone_release_number": {"post": {"operationId": "phone_release_number", "summary": "Release a phone number", "description": "Give a number back. It stops answering at once, its rental ends and the number may go to someone else. This can't be undone, and the rest of the month is not refunded. Free.", "tags": ["phone"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"number": {"type": "string", "pattern": "^\\+[1-9][0-9]{6,15}$", "description": "The number in E.164 form, e.g. +15035550123."}}, "required": ["number"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/phone_setup_assistant": {"post": {"operationId": "phone_setup_assistant", "summary": "Set up how calls are answered", "description": "Choose how the business's numbers are answered; Conecto hears and speaks, you are the brain. answer_with webhook: each thing a caller says is POSTed to webhook_url (signed with the webhook_secret returned once: X-Conecto-Signature is sha256= the HMAC of the body) with the conversation so far, and you answer {\"say\": \"...\", \"end_call\": false} within about 2.5 seconds (the caller hears \"one moment\" after that; after 8 seconds the line takes a message instead). answer_with messages: the line takes the caller's message. Either way the whole call reaches you afterwards as a phone.message_left or phone.call_ended event. Only the fields you pass change; the first time pass greeting and timezone. Answered calls cost $0.25 per started minute; each call holds max_call_minutes × $0.25 while it runs. Costs $0.001 per call; nothing if it fails.", "tags": ["phone"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"greeting": {"type": "string", "minLength": 1, "maxLength": 600, "description": "What callers hear right after Conecto's short notice, in the line's language, that the AI call is recorded and transcribed. It must say they reached an automated line or an AI, e.g. \"Hi, you've reached Acme. This is our automated line: how can we help?\" Taking messages, ask for their message, name and number."}, "answer_with": {"type": "string", "enum": ["messages", "webhook"], "description": "messages (the default) or webhook."}, "webhook_url": {"type": "string", "maxLength": 500, "description": "Your https endpoint for each turn."}, "rotate_secret": {"type": "boolean", "default": false, "description": "Make a new webhook_secret (the old one stops working)."}, "message_ack": {"type": "string", "maxLength": 300, "description": "Taking a message: what the line says after each thing the caller says."}, "cant_answer": {"type": "string", "maxLength": 300, "description": "What the line says when your webhook did not answer in time."}, "open_tickets": {"type": "string", "enum": ["off", "messages", "calls"], "description": "messages: each message left opens a help desk ticket with the transcript (or joins the open one the caller has); calls: every call the caller spoke on. $0.01 per ticket opened. Default off."}, "name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The line's name."}, "language": {"type": "string", "enum": ["af", "ar", "hy", "as", "az", "be", "bn", "bs", "bg", "ca", "ceb", "ny", "hr", "cs", "da", "nl", "en", "et", "fil", "fi", "fr", "gl", "ka", "de", "el", "gu", "ha", "he", "hi", "hu", "is", "id", "ga", "it", "ja", "jv", "kn", "kk", "ky", "ko", "lv", "ln", "lt", "lb", "mk", "ms", "ml", "zh", "mr", "ne", "no", "ps", "fa", "pl", "pt", "pa", "ro", "ru", "sr", "sd", "sk", "sl", "so", "es", "sw", "sv", "ta", "te", "th", "tr", "uk", "ur", "vi", "cy"], "description": "The language it speaks."}, "voice": {"type": "string", "maxLength": 100, "description": "A voice id or name from phone_get_assistant."}, "timezone": {"type": "string", "maxLength": 80, "description": "IANA time zone of the business, e.g. America/New_York. Needed the first time."}, "hours": {"type": "array", "maxItems": 7, "description": "When to answer, in the timezone; empty answers around the clock. Outside these hours callers get a busy signal.", "items": {"type": "object", "required": ["day", "start", "end"], "additionalProperties": false, "properties": {"day": {"type": "string", "enum": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]}, "start": {"type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"}, "end": {"type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"}}}}, "max_call_minutes": {"type": "integer", "minimum": 1, "maximum": 10, "description": "Calls end after this long (default 5)."}, "answering": {"type": "boolean", "description": "false pauses answering; true resumes it."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/phone_get_assistant": {"post": {"operationId": "phone_get_assistant", "summary": "Get how calls are answered", "description": "How the business's numbers answer (your webhook or taking messages), whether they are answering right now (and if not, why), and the voices the line can use. Free.", "tags": ["phone"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/phone_list_calls": {"post": {"operationId": "phone_list_calls", "summary": "List phone calls", "description": "Calls to and from the business's numbers, newest first: who, when, how long and what it cost. Missed calls (outside hours, paused, balance too low, lines busy) are included with the reason, and so are the calls the assistant made to confirm meetings. When the balance was too low the caller could leave a message, free: it is on the missed call as left_message. Read a whole conversation with phone_get_call. Free.", "tags": ["phone"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}, "before": {"type": "string", "format": "date-time", "description": "Only calls before this time (ISO 8601), to page back."}, "include_missed": {"type": "boolean", "default": true}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/phone_get_call": {"post": {"operationId": "phone_get_call", "summary": "Get a phone call", "description": "One call with its whole transcript (who said what, and when). Free.", "tags": ["phone"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string", "minLength": 36, "maxLength": 36}}, "required": ["call_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/projects_create": {"post": {"operationId": "projects_create", "summary": "Create a project", "description": "A board of tasks with a short key that numbers them (WEB-1, WEB-2). Statuses default to Backlog, To do, In progress, Done and Canceled; give your own as [{\"name\": ..., \"kind\": \"backlog|unstarted|started|completed|canceled\"}] in board order. Costs $0.001 per call; nothing if it fails.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80}, "key": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9]{1,5}$", "description": "2 to 6 letters or digits; made from the name when left out."}, "description": {"type": "string", "maxLength": 2000}, "statuses": {"type": "array", "minItems": 2, "maxItems": 12, "items": {"type": "object", "additionalProperties": false, "required": ["name", "kind"], "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 40}, "kind": {"type": "string", "enum": ["backlog", "unstarted", "started", "completed", "canceled"]}}}}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/projects_list": {"post": {"operationId": "projects_list", "summary": "List projects", "description": "Every project with how many tasks are in each status. Free.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"include_archived": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/projects_board": {"post": {"operationId": "projects_board", "summary": "See a project's board", "description": "A project as a board: each status with its tasks in order (finished and canceled ones only if asked). Free.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"project": {"type": "string", "minLength": 1, "maxLength": 80, "description": "A project's key (\"WEB\") or name."}, "include_finished": {"type": "boolean", "default": false}, "per_status": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, "required": ["project"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tasks_create": {"post": {"operationId": "tasks_create", "summary": "Create a task", "description": "A new task in a project, numbered like WEB-13. Starts in the project's first \"to do\" status unless status says otherwise. Link it to a CRM contact, company or deal, or make it a subtask with parent. Costs $0.01 per call; nothing if it fails.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"project": {"type": "string", "minLength": 1, "maxLength": 80, "description": "A project's key (\"WEB\") or name."}, "title": {"type": "string", "minLength": 1, "maxLength": 200}, "description": {"type": "string", "maxLength": 20000, "description": "Markdown."}, "status": {"type": "string", "maxLength": 40, "description": "One of the project's statuses, e.g. \"In progress\"."}, "priority": {"type": "string", "enum": ["none", "low", "medium", "high", "urgent"]}, "assignee": {"type": "string", "maxLength": 120, "description": "A bot's name or a person's email; \"\" to clear."}, "labels": {"type": "array", "maxItems": 10, "items": {"type": "string", "minLength": 1, "maxLength": 30}}, "due_date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null."}, "contact_id": {"type": ["integer", "null"]}, "company_id": {"type": ["integer", "null"]}, "deal_id": {"type": ["integer", "null"]}, "parent": {"type": "string", "maxLength": 20, "description": "The task this is a subtask of, like \"WEB-4\"."}}, "required": ["project", "title"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tasks_update": {"post": {"operationId": "tasks_update", "summary": "Change a task", "description": "Change a task: move it to another status, reassign, reprioritize, relabel, set a due date, edit its title or description, or link CRM records. Give only what changes; order \"top\" puts it first in its column. Costs $0.01 per call; nothing if it fails.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"task": {"type": "string", "minLength": 1, "maxLength": 20, "description": "A task like \"WEB-12\", or its task_id."}, "title": {"type": "string", "minLength": 1, "maxLength": 200}, "description": {"type": "string", "maxLength": 20000, "description": "Markdown."}, "status": {"type": "string", "maxLength": 40, "description": "One of the project's statuses, e.g. \"In progress\"."}, "priority": {"type": "string", "enum": ["none", "low", "medium", "high", "urgent"]}, "assignee": {"type": "string", "maxLength": 120, "description": "A bot's name or a person's email; \"\" to clear."}, "labels": {"type": "array", "maxItems": 10, "items": {"type": "string", "minLength": 1, "maxLength": 30}}, "due_date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null."}, "contact_id": {"type": ["integer", "null"]}, "company_id": {"type": ["integer", "null"]}, "deal_id": {"type": ["integer", "null"]}, "order": {"type": "string", "enum": ["top", "bottom"]}}, "required": ["task"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tasks_list": {"post": {"operationId": "tasks_list", "summary": "Find tasks", "description": "Tasks across projects or in one, filtered by status, assignee, label, priority, due date or words in the title and description. Open tasks only, unless include_finished; most urgent first. Free.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"project": {"type": "string", "minLength": 1, "maxLength": 80, "description": "A project's key (\"WEB\") or name."}, "status": {"type": "string", "maxLength": 40}, "assignee": {"type": "string", "maxLength": 120}, "label": {"type": "string", "maxLength": 30}, "priority": {"type": "string", "enum": ["none", "low", "medium", "high", "urgent"]}, "due_before": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, "query": {"type": "string", "maxLength": 100}, "include_finished": {"type": "boolean", "default": false}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tasks_get": {"post": {"operationId": "tasks_get", "summary": "Get a task", "description": "One task in full: description, links, subtasks, comments and history. Free.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"task": {"type": "string", "minLength": 1, "maxLength": 20, "description": "A task like \"WEB-12\", or its task_id."}}, "required": ["task"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tasks_comment": {"post": {"operationId": "tasks_comment", "summary": "Comment on a task", "description": "Add a comment (Markdown) to a task's thread. Costs $0.01 per call; nothing if it fails.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"task": {"type": "string", "minLength": 1, "maxLength": 20, "description": "A task like \"WEB-12\", or its task_id."}, "body": {"type": "string", "minLength": 1, "maxLength": 10000}}, "required": ["task", "body"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tasks_delete": {"post": {"operationId": "tasks_delete", "summary": "Delete a task", "description": "Delete a task and its subtasks for good. Free.", "tags": ["projects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"task": {"type": "string", "minLength": 1, "maxLength": 20, "description": "A task like \"WEB-12\", or its task_id."}}, "required": ["task"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/schedules_create": {"post": {"operationId": "schedules_create", "summary": "Repeat a tool call", "description": "Run any tool on a timetable, e.g. a weekly report, a daily export or a reminder every Monday at 9:00, in the business's time zone. It runs as this bot, under its daily budget, and each run costs the tool's own price; the reply estimates the most it can cost a month. arguments are checked now; date words in them ({today}, {today+7}, {month}, {last_month}, {year}) are filled in at each run. For one run, use schedules_run_later. Tools that take tokens or read the vault can't be scheduled. A schedule is $0.50 a month, renewed from the balance; the first month is this call. Five failed runs in a row pause it and email the owner. Costs $0.50 per call; nothing if it fails.", "tags": ["schedules"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "e.g. \"Monday invoice reminders\"."}, "tool": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The tool to run, e.g. \"invoices_remind\"."}, "arguments": {"type": "object", "description": "The tool's arguments, as you would send them."}, "timetable": {"type": "object", "description": "When it runs, in time_zone. {\"every\": \"minutes\", \"interval\": 30} (15 at the least, 60 for tools that contact people or sites outside the business); {\"every\": \"hour\", \"interval\": 1, \"minute\": 0}; {\"every\": \"day\", \"at\": \"09:00\"}; {\"every\": \"week\", \"days\": [\"mon\", \"thu\"], \"at\": \"09:00\"}; {\"every\": \"month\", \"day\": 1, \"at\": \"09:00\"} (day 1 to 28, or \"last\").", "properties": {"every": {"type": "string", "enum": ["minutes", "hour", "day", "week", "month"]}, "interval": {"type": "integer"}, "minute": {"type": "integer"}, "at": {"type": "string"}, "days": {"type": "array", "items": {"type": "string"}, "maxItems": 7}, "day": {"type": ["integer", "string"]}}, "required": ["every"], "additionalProperties": false}, "time_zone": {"type": "string", "maxLength": 64, "description": "e.g. \"America/Los_Angeles\". The business calendar's time zone if left out, else UTC."}}, "required": ["name", "tool", "timetable"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/schedules_run_later": {"post": {"operationId": "schedules_run_later", "summary": "Run a tool call once, later", "description": "Run one tool call once at a set time: \"send this Tuesday at 9:00\", \"check on Friday whether invoice 42 was paid\". Give at (ISO 8601 with its offset, up to a year ahead) or in_minutes. It runs as this bot, under its daily budget, and costs the tool's own price when it runs, plus $0.01 now; no monthly rent. Date words in arguments ({today}, {today+7}, {month}, {last_month}, {year}) are filled in when it runs, in time_zone. schedules_list shows it; schedules_delete cancels it before it runs. Costs $0.01 per call; nothing if it fails.", "tags": ["schedules"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"tool": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The tool to run, e.g. \"email_send\"."}, "arguments": {"type": "object", "description": "The tool's arguments, as you would send them."}, "at": {"type": "string", "maxLength": 40, "description": "e.g. \"2026-10-20T09:00:00-07:00\"."}, "in_minutes": {"type": "integer", "minimum": 1, "maximum": 527040}, "name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "e.g. \"Monday invoice reminders\"."}, "time_zone": {"type": "string", "maxLength": 64, "description": "e.g. \"America/Los_Angeles\". The business calendar's time zone if left out, else UTC."}}, "required": ["tool"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/schedules_list": {"post": {"operationId": "schedules_list", "summary": "List schedules", "description": "Every schedule on the account: what it runs and when, which bot it runs as, its next run and how its last run went. Free.", "tags": ["schedules"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/schedules_get": {"post": {"operationId": "schedules_get", "summary": "Get a schedule", "description": "One schedule in full: its next three runs, its last ten runs (each a call_id for account_get_call, which has the result) and its rent. Free.", "tags": ["schedules"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"schedule_id": {"type": "integer", "minimum": 1, "description": "The schedule_id schedules_create returned."}}, "required": ["schedule_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/schedules_update": {"post": {"operationId": "schedules_update", "summary": "Change a schedule", "description": "Change a schedule's name, arguments, timetable or time zone, or pause and resume it. Give only what changes. Changing what it runs makes it run as this bot from then on. Resuming starts from the next slot, never the missed ones. Costs $0.001 per call; nothing if it fails.", "tags": ["schedules"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"schedule_id": {"type": "integer", "minimum": 1, "description": "The schedule_id schedules_create returned."}, "name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "e.g. \"Monday invoice reminders\"."}, "arguments": {"type": "object"}, "timetable": {"type": "object", "description": "When it runs, in time_zone. {\"every\": \"minutes\", \"interval\": 30} (15 at the least, 60 for tools that contact people or sites outside the business); {\"every\": \"hour\", \"interval\": 1, \"minute\": 0}; {\"every\": \"day\", \"at\": \"09:00\"}; {\"every\": \"week\", \"days\": [\"mon\", \"thu\"], \"at\": \"09:00\"}; {\"every\": \"month\", \"day\": 1, \"at\": \"09:00\"} (day 1 to 28, or \"last\").", "properties": {"every": {"type": "string", "enum": ["minutes", "hour", "day", "week", "month"]}, "interval": {"type": "integer"}, "minute": {"type": "integer"}, "at": {"type": "string"}, "days": {"type": "array", "items": {"type": "string"}, "maxItems": 7}, "day": {"type": ["integer", "string"]}}, "required": ["every"], "additionalProperties": false}, "time_zone": {"type": "string", "maxLength": 64, "description": "e.g. \"America/Los_Angeles\". The business calendar's time zone if left out, else UTC."}, "paused": {"type": "boolean"}}, "required": ["schedule_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/schedules_delete": {"post": {"operationId": "schedules_delete", "summary": "Delete a schedule", "description": "Stop a schedule for good and end its monthly rent. Its past runs stay in the call log. Free.", "tags": ["schedules"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"schedule_id": {"type": "integer", "minimum": 1, "description": "The schedule_id schedules_create returned."}}, "required": ["schedule_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/speech_transcribe": {"post": {"operationId": "speech_transcribe", "summary": "Transcribe audio", "description": "Turn the speech in an audio or video file from the file store (MP3, WAV, M4A, OGG, FLAC, WebM, MP4, MOV, up to 25 MB) into text, in any of about 100 languages, detected by itself. With speakers, it says who spoke when; with timestamps, it gives timed segments. Runs in the background: poll the call_id. Charged per started minute of audio, never more than max_minutes. Costs $0.01 per started minute of audio; nothing if none are found. Runs in the background: the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>.", "tags": ["speech"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36}, "language": {"type": "string", "pattern": "^[a-z]{2,3}$", "description": "ISO 639 code like \"en\" or \"deu\" when you know it."}, "speakers": {"type": "boolean", "default": false}, "timestamps": {"type": "boolean", "default": false}, "max_minutes": {"type": "integer", "minimum": 1, "maximum": 180, "default": 60, "description": "The most minutes to pay for; audio past it is transcribed but not charged."}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}, "202": {"description": "Started; poll /v1/calls/{call_id}.", "content": {"application/json": {"schema": {"type": "object"}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/speech_list_voices": {"post": {"operationId": "speech_list_voices", "summary": "List voices", "description": "The voices speech_synthesize can use. Each speaks about 30 languages; the text decides the language. Free.", "tags": ["speech"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/speech_synthesize": {"post": {"operationId": "speech_synthesize", "summary": "Turn text into speech", "description": "An MP3 of the text read aloud by one of the voices (speech_list_voices), saved in the file store with a download link. Up to 5,000 characters a call; it reads the language the text is written in. The file carries a machine-readable mark that the speech is AI-generated (ID3: AIGenerated, IPTC digital source type). Costs $0.07 per 1,000 characters, rounded up (at most $0.35 a call); nothing if it fails.", "tags": ["speech"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"text": {"type": "string", "minLength": 1, "maxLength": 5000}, "voice": {"type": "string", "maxLength": 40, "description": "A voice from speech_list_voices; the first one when left out."}, "name": {"type": "string", "maxLength": 200, "description": "File name for the MP3."}}, "required": ["text"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tables_create": {"post": {"operationId": "tables_create", "summary": "Create a table", "description": "A table with typed columns: text, long_text, number (with decimals or a currency), checkbox, date, datetime, select and multi_select (with options), email, url, phone, or file (a file_id from the file store). Values are checked against their column on the way in. Up to 100 columns and 100,000 rows. Costs $0.001 per call; nothing if it fails.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80}, "description": {"type": "string", "maxLength": 500}, "columns": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 60}, "type": {"type": "string", "enum": ["text", "long_text", "number", "checkbox", "date", "datetime", "select", "multi_select", "email", "url", "phone", "file"], "default": "text"}, "required": {"type": "boolean"}, "options": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 60}}, "decimals": {"type": "integer", "minimum": 0, "maximum": 6}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$"}}}}}, "required": ["name", "columns"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tables_list": {"post": {"operationId": "tables_list", "summary": "List tables", "description": "Every table with its columns and row count. Free.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tables_change_columns": {"post": {"operationId": "tables_change_columns", "summary": "Change columns", "description": "Add columns, rename them, or remove them (their values go too). Rows keep their values through renames. Costs $0.001 per call; nothing if it fails.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "add": {"type": "array", "maxItems": 50, "items": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 60}, "type": {"type": "string", "enum": ["text", "long_text", "number", "checkbox", "date", "datetime", "select", "multi_select", "email", "url", "phone", "file"], "default": "text"}, "required": {"type": "boolean"}, "options": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 60}}, "decimals": {"type": "integer", "minimum": 0, "maximum": 6}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$"}}}}, "rename": {"type": "object", "additionalProperties": {"type": "string", "minLength": 1, "maxLength": 60}, "description": "{\"old name\": \"new name\"}"}, "remove": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 60}}}, "required": ["table"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/rows_add": {"post": {"operationId": "rows_add", "summary": "Add rows", "description": "Add up to 500 rows, each an object of column names to values, e.g. {\"Name\": \"Maria Santos\", \"Budget\": 5000}. All rows are checked first; if one is wrong, none is added and the error names its row and column. Costs $0.001 per row added; nothing if none are found.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "rows": {"type": "array", "minItems": 1, "maxItems": 500, "items": {"type": "object"}}}, "required": ["table", "rows"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/rows_update": {"post": {"operationId": "rows_update", "summary": "Change rows", "description": "Change values in up to 500 rows by their row number: [{\"row\": 12, \"values\": {\"Stage\": \"Ordered\"}}]. A null value clears a cell. Only the columns given change. Costs $0.001 per row changed; nothing if none are found.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "rows": {"type": "array", "minItems": 1, "maxItems": 500, "items": {"type": "object", "additionalProperties": false, "required": ["row", "values"], "properties": {"row": {"type": "integer", "minimum": 1}, "values": {"type": "object"}}}}}, "required": ["table", "rows"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/rows_upsert": {"post": {"operationId": "rows_upsert", "summary": "Add or update rows by a key", "description": "Sync rows from anywhere without reading the table first: each row whose key column matches a row in the table updates it (only the columns given change; a null value clears a cell), the rest are added. The key is a text, email, url, phone, select or number column whose values are unique (text matches in any case). Up to 500 rows, checked first: if one is wrong, nothing changes. Costs $0.001 per row added or updated; nothing if none are found.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "key": {"type": "string", "minLength": 1, "maxLength": 60, "description": "The column that identifies a row, e.g. \"Email\" or \"SKU\"."}, "rows": {"type": "array", "minItems": 1, "maxItems": 500, "items": {"type": "object"}}}, "required": ["table", "key", "rows"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/rows_summarize": {"post": {"operationId": "rows_summarize", "summary": "Summarize rows", "description": "Count rows, and sum, average, min and max number columns (min and max of dates), for the rows matching filters, overall and per value of group_by: one call instead of paging through every row. Filters work as in rows_query. Free.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "columns": {"type": "array", "maxItems": 10, "items": {"type": "string", "maxLength": 60}, "description": "Number or date columns to measure."}, "group_by": {"type": "string", "maxLength": 60, "description": "A column to group the rows by."}, "filters": {"type": "array", "maxItems": 20, "items": {"type": "object", "additionalProperties": false, "required": ["column"], "properties": {"column": {"type": "string", "maxLength": 60}, "op": {"type": "string", "enum": ["eq", "neq", "contains", "not_contains", "gt", "gte", "lt", "lte", "empty", "not_empty", "in"]}, "value": {}}}}, "match": {"type": "string", "enum": ["all", "any"], "default": "all"}}, "required": ["table"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/rows_delete": {"post": {"operationId": "rows_delete", "summary": "Delete rows", "description": "Delete rows by their numbers, for good. Free.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "rows": {"type": "array", "minItems": 1, "maxItems": 1000, "items": {"type": "integer"}}}, "required": ["table", "rows"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/rows_query": {"post": {"operationId": "rows_query", "summary": "Find rows", "description": "Rows matching filters ([{\"column\": \"Stage\", \"op\": \"eq\", \"value\": \"New\"}]; ops: eq, neq, contains, not_contains, gt, gte, lt, lte for numbers and dates, empty, not_empty, in), all or any of them, sorted by columns, a page at a time. Free.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "filters": {"type": "array", "maxItems": 20, "items": {"type": "object", "additionalProperties": false, "required": ["column"], "properties": {"column": {"type": "string", "maxLength": 60}, "op": {"type": "string", "enum": ["eq", "neq", "contains", "not_contains", "gt", "gte", "lt", "lte", "empty", "not_empty", "in"]}, "value": {}}}}, "match": {"type": "string", "enum": ["all", "any"], "default": "all"}, "sort": {"type": "array", "maxItems": 3, "items": {"type": "object", "additionalProperties": false, "required": ["column"], "properties": {"column": {"type": "string"}, "direction": {"type": "string", "enum": ["asc", "desc"]}}}}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": ["table"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tables_export": {"post": {"operationId": "tables_export", "summary": "Export a table to CSV", "description": "A CSV of the table (or of the rows matching filters) in the file store, with a download link. Costs $0.001 per call; nothing if it fails.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "filters": {"type": "array", "maxItems": 20, "items": {"type": "object", "additionalProperties": false, "required": ["column"], "properties": {"column": {"type": "string", "maxLength": 60}, "op": {"type": "string", "enum": ["eq", "neq", "contains", "not_contains", "gt", "gte", "lt", "lte", "empty", "not_empty", "in"]}, "value": {}}}}, "match": {"type": "string", "enum": ["all", "any"], "default": "all"}}, "required": ["table"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tables_import": {"post": {"operationId": "tables_import", "summary": "Import a CSV", "description": "Rows from a CSV in the file store: into an existing table (CSV headers matched to column names; unknown headers listed and skipped) or, with new_table, into a new table with a text column per header. Every row is checked first; nothing is added if one is wrong. Costs $0.001 per row imported; nothing if none are found.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36}, "table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}, "new_table": {"type": "string", "minLength": 1, "maxLength": 80}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/tables_delete": {"post": {"operationId": "tables_delete", "summary": "Delete a table", "description": "Delete a table and all its rows, for good. Free.", "tags": ["tables"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"table": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The table's name (or its table_id)."}}, "required": ["table"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/uptime_add_monitor": {"post": {"operationId": "uptime_add_monitor", "summary": "Watch a page", "description": "Check a page every 1, 5, 15 or 60 minutes from our servers. It counts as down after two failed checks in a row (an error, no answer within 10 seconds, or missing expect_text) and up again on the first good one; each change alerts the notification channels you name and the owner by email. HTTPS certificates are watched too. $0.50 a month per monitor, renewed from the balance; the first month is this call, which also runs the first check. Costs $0.50 per call; nothing if it fails.", "tags": ["uptime"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "e.g. \"Online shop\"."}, "url": {"type": "string", "minLength": 8, "maxLength": 2000, "pattern": "^https://", "description": "The https:// page to check."}, "interval_minutes": {"type": "integer", "enum": [1, 5, 15, 60], "default": 5}, "expect_text": {"type": "string", "maxLength": 200, "description": "Text the page must contain to count as up, e.g. \"Add to cart\"."}, "notify_channels": {"type": "array", "maxItems": 10, "items": {"type": "string", "maxLength": 40}, "description": "Notification channels (notify_add_channel) to alert."}, "email_alerts": {"type": "boolean", "default": true, "description": "Also email the owner."}, "public": {"type": "boolean", "default": true, "description": "Show it on the status page."}}, "required": ["name", "url"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/uptime_list_monitors": {"post": {"operationId": "uptime_list_monitors", "summary": "List monitors", "description": "Every watched page: up, down or paused, its last check, and uptime over 24 hours and 30 days. Free.", "tags": ["uptime"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/uptime_get_monitor": {"post": {"operationId": "uptime_get_monitor", "summary": "Get a monitor", "description": "One watched page in full: uptime over 90 days, average response time, the certificate's expiry and its incidents (when it went down and for how long). Free.", "tags": ["uptime"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"monitor_id": {"type": "integer", "minimum": 1, "description": "The monitor_id uptime_add_monitor returned."}}, "required": ["monitor_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/uptime_update_monitor": {"post": {"operationId": "uptime_update_monitor", "summary": "Change a monitor", "description": "Change what a monitor checks, how often, who is told, or pause and resume it. Give only what changes. Costs $0.001 per call; nothing if it fails.", "tags": ["uptime"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"monitor_id": {"type": "integer", "minimum": 1, "description": "The monitor_id uptime_add_monitor returned."}, "name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "e.g. \"Online shop\"."}, "url": {"type": "string", "minLength": 8, "maxLength": 2000, "pattern": "^https://", "description": "The https:// page to check."}, "interval_minutes": {"type": "integer", "enum": [1, 5, 15, 60]}, "expect_text": {"type": "string", "maxLength": 200, "description": "Text the page must contain to count as up, e.g. \"Add to cart\"."}, "notify_channels": {"type": "array", "maxItems": 10, "items": {"type": "string", "maxLength": 40}, "description": "Notification channels (notify_add_channel) to alert."}, "email_alerts": {"type": "boolean", "description": "Also email the owner."}, "public": {"type": "boolean", "description": "Show it on the status page."}, "paused": {"type": "boolean"}}, "required": ["monitor_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/uptime_remove_monitor": {"post": {"operationId": "uptime_remove_monitor", "summary": "Stop watching a page", "description": "Remove a monitor and stop its monthly rent. Its history goes with it. Free.", "tags": ["uptime"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"monitor_id": {"type": "integer", "minimum": 1, "description": "The monitor_id uptime_add_monitor returned."}}, "required": ["monitor_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/uptime_setup_status_page": {"post": {"operationId": "uptime_setup_status_page", "summary": "Set up the status page", "description": "A public page at cncto.co/s/<name> showing every public monitor: up or down now, 90 days of uptime and recent incidents, like an Atlassian or Instatus status page. One per account; call again to change its title or description. Costs $0.001 per call; nothing if it fails.", "tags": ["uptime"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "minLength": 1, "maxLength": 120}, "description": {"type": "string", "maxLength": 300}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/vault_save": {"post": {"operationId": "vault_save", "summary": "Save a secret", "description": "Keep a secret (an API key, a password, a login) encrypted in the account's vault under a name, to read back later with vault_get. Saving under an existing name replaces it. username, url and note are not secret and show in vault_list. With bots, only those of the account's bots may read it. Costs $0.001 per call; nothing if it fails.", "tags": ["vault"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,79}$", "description": "e.g. \"Shopify admin\" or \"SUPPLIER_API_KEY\"."}, "value": {"type": "string", "minLength": 1, "maxLength": 10000, "writeOnly": true}, "username": {"type": "string", "maxLength": 200}, "url": {"type": "string", "maxLength": 500}, "note": {"type": "string", "maxLength": 500}, "bots": {"type": "array", "maxItems": 20, "items": {"type": ["string", "integer"]}, "description": "Bot names (or key ids) allowed to read it; all of the account's bots if left out."}}, "required": ["name", "value"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/vault_get": {"post": {"operationId": "vault_get", "summary": "Read a secret", "description": "A secret's value, for this call only: it is never stored in the call log. Each read is counted. Free.", "tags": ["vault"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,79}$", "description": "e.g. \"Shopify admin\" or \"SUPPLIER_API_KEY\"."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/vault_list": {"post": {"operationId": "vault_list", "summary": "List secrets", "description": "The names of the vault's secrets with their username, URL, note, who may read them and when they were last read. Never the values. Free.", "tags": ["vault"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/vault_delete": {"post": {"operationId": "vault_delete", "summary": "Delete a secret", "description": "Remove a secret from the vault, for good. Free.", "tags": ["vault"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,79}$", "description": "e.g. \"Shopify admin\" or \"SUPPLIER_API_KEY\"."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/vault_generate_password": {"post": {"operationId": "vault_generate_password", "summary": "Make a strong password", "description": "A random password (letters, digits and symbols, or only letters and digits) saved straight into the vault under name, and returned for this call only. Costs $0.001 per call; nothing if it fails.", "tags": ["vault"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,79}$", "description": "e.g. \"Shopify admin\" or \"SUPPLIER_API_KEY\"."}, "length": {"type": "integer", "minimum": 12, "maximum": 128, "default": 24}, "symbols": {"type": "boolean", "default": true}, "username": {"type": "string", "maxLength": 200}, "url": {"type": "string", "maxLength": 500}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/web_read": {"post": {"operationId": "web_read", "summary": "Read a web page", "description": "Fetch one public page and get its main content as clean Markdown (menus, ads and footers left out), with its title, description and the links on it. PDFs come back as their text. Pages that need JavaScript to show anything, need a login, or whose robots.txt closes them to bots can't be read, and cost nothing. Costs $0.002 per call; nothing if it fails.", "tags": ["web"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"url": {"type": "string", "minLength": 4, "maxLength": 2000}, "links": {"type": "boolean", "default": true, "description": "Include the links on the page."}, "max_characters": {"type": "integer", "minimum": 1000, "maximum": 100000, "default": 20000}}, "required": ["url"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/web_search": {"post": {"operationId": "web_search", "summary": "Search the web", "description": "Search the web through Conecto's own search service. Each result comes with its title, link, site and snippet; read a page in full with web_read. Narrow by country and language. $0.009 a search; a failed one costs nothing. Costs $0.009 per call; nothing if it fails.", "tags": ["web"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "minLength": 1, "maxLength": 256}, "count": {"type": "integer", "minimum": 1, "maximum": 20, "default": 10}, "country": {"type": "string", "minLength": 2, "maxLength": 2}, "language": {"type": "string", "minLength": 2, "maxLength": 2}}, "required": ["query"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/visibility_setup": {"post": {"operationId": "visibility_setup", "summary": "Set up AI visibility tracking", "description": "Choose what to track for a website: the buyer questions to ask the assistants (up to 10), the competitors to compare against (up to 10, each with its domains), and which assistants to check (default: all of ChatGPT, Claude, Gemini, Grok, Perplexity, DeepSeek, AI Overviews). Send only what you want to change. Without questions, the first check writes five from the website. Costs $0.001 per call; nothing if it fails.", "tags": ["visibility"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"website": {"type": "string", "minLength": 4, "maxLength": 500, "description": "The business website, e.g. https://acme.com"}, "brand_name": {"type": "string", "maxLength": 80}, "questions": {"type": "array", "maxItems": 10, "items": {"type": "object", "additionalProperties": false, "required": ["question"], "properties": {"question": {"type": "string", "minLength": 3, "maxLength": 300}, "country": {"type": "string", "pattern": "^[A-Za-z]{2}$"}, "topic": {"type": "string", "maxLength": 60}}}}, "competitors": {"type": "array", "maxItems": 10, "items": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80}, "domains": {"type": "array", "maxItems": 5, "items": {"type": "string", "maxLength": 255}}}}}, "assistants": {"type": "array", "minItems": 1, "items": {"type": "string", "enum": ["ChatGPT", "Claude", "Gemini", "Grok", "Perplexity", "DeepSeek", "AI Overviews"]}}}, "required": ["website"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/visibility_check": {"post": {"operationId": "visibility_check", "summary": "Run an AI visibility check", "description": "Ask every tracked buyer question on each chosen assistant, with web search on, and measure how often the business is named, where, how favourably, against which competitors, and which sites the assistants cite. Takes a few minutes. When it finishes, the result is the same report as visibility_report. Costs $0.04 per answer (one question on one assistant); nothing if none are found. Runs in the background: the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>.", "tags": ["visibility"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"website": {"type": "string", "minLength": 4, "maxLength": 500, "description": "The business website, e.g. https://acme.com"}}, "required": ["website"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}, "202": {"description": "Started; poll /v1/calls/{call_id}.", "content": {"application/json": {"schema": {"type": "object"}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/visibility_report": {"post": {"operationId": "visibility_report", "summary": "Get the AI visibility report", "description": "The latest check: overall visibility (share of answers naming the business), its trend, each assistant, rank against the competitors, the sites the assistants cite, and the next actions. Free. Free.", "tags": ["visibility"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"website": {"type": "string", "minLength": 4, "maxLength": 500, "description": "The business website, e.g. https://acme.com"}}, "required": ["website"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/visibility_answers": {"post": {"operationId": "visibility_answers", "summary": "Read the assistants' answers", "description": "The answers behind the latest check, page by page. named=true keeps answers that named the business, named=false the ones that did not (the gaps to work on). Free. Free.", "tags": ["visibility"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"website": {"type": "string", "minLength": 4, "maxLength": 500, "description": "The business website, e.g. https://acme.com"}, "named": {"type": "boolean"}, "cursor": {"type": "integer", "minimum": 0}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}, "required": ["website"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/visibility_improve": {"post": {"operationId": "visibility_improve", "summary": "How to improve AI visibility", "description": "What to do next to be named more often: the actions from the latest check, ordered by impact, each with the gap it closes and concrete steps (pages to write, sources to get listed on). Free. Free.", "tags": ["visibility"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"website": {"type": "string", "minLength": 4, "maxLength": 500, "description": "The business website, e.g. https://acme.com"}}, "required": ["website"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/view_show": {"post": {"operationId": "view_show", "summary": "Show someone a page of results", "description": "Draw numbers, charts, bars, tables, lists and text on one page and get a one-time link to it, to send to a person: the first browser that opens it keeps it for an hour, and an unopened link expires after 7 days. Conecto keeps no dashboards of its own; this is how a person sees what you found, from any area or anywhere else. blocks is a list, drawn top to bottom. Each block is one of: {\"type\": \"heading\", \"text\"}; {\"type\": \"text\", \"text\"} (blank lines make paragraphs); {\"type\": \"metrics\", \"items\": [{\"label\", \"value\", \"format\", \"currency\", \"change\" (percent), \"better\": \"up\"|\"down\", \"note\", \"tone\": \"good\"|\"warn\"|\"bad\"}]} (up to 8 numbers in a row); {\"type\": \"chart\", \"title\", \"kind\": \"line\"|\"bar\", \"labels\": [...], \"series\": [{\"name\", \"values\": [...]}], \"format\", \"currency\"} (up to 4 series of up to 400 points); {\"type\": \"bars\", \"title\", \"label_header\", \"value_header\", \"items\": [{\"label\", \"value\", \"detail\", \"link\", \"country\" (a two-letter code: shows the flag, and the name when label is left out)}], \"format\", \"currency\"} (ranked rows with a bar each, up to 50); {\"type\": \"table\", \"title\", \"columns\": [{\"label\", \"format\", \"currency\"}], \"rows\": [[...], ...]} (up to 12 columns and 500 rows); {\"type\": \"list\", \"title\", \"items\": [{\"title\", \"text\", \"meta\", \"link\"}]} (up to 100); {\"type\": \"divider\"}. format is number, percent (49 means 49%), currency (with currency, like \"EUR\"), seconds (a length of time), milliseconds or text. bars, table, list and metrics take \"width\": \"half\" to sit beside the next half block. Costs $0.01 per call; nothing if it fails.", "tags": ["views"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "minLength": 1, "maxLength": 200}, "subtitle": {"type": "string", "maxLength": 300, "description": "A line under the title, like the period it covers."}, "blocks": {"type": "array", "minItems": 1, "maxItems": 60, "description": "blocks is a list, drawn top to bottom. Each block is one of: {\"type\": \"heading\", \"text\"}; {\"type\": \"text\", \"text\"} (blank lines make paragraphs); {\"type\": \"metrics\", \"items\": [{\"label\", \"value\", \"format\", \"currency\", \"change\" (percent), \"better\": \"up\"|\"down\", \"note\", \"tone\": \"good\"|\"warn\"|\"bad\"}]} (up to 8 numbers in a row); {\"type\": \"chart\", \"title\", \"kind\": \"line\"|\"bar\", \"labels\": [...], \"series\": [{\"name\", \"values\": [...]}], \"format\", \"currency\"} (up to 4 series of up to 400 points); {\"type\": \"bars\", \"title\", \"label_header\", \"value_header\", \"items\": [{\"label\", \"value\", \"detail\", \"link\", \"country\" (a two-letter code: shows the flag, and the name when label is left out)}], \"format\", \"currency\"} (ranked rows with a bar each, up to 50); {\"type\": \"table\", \"title\", \"columns\": [{\"label\", \"format\", \"currency\"}], \"rows\": [[...], ...]} (up to 12 columns and 500 rows); {\"type\": \"list\", \"title\", \"items\": [{\"title\", \"text\", \"meta\", \"link\"}]} (up to 100); {\"type\": \"divider\"}. format is number, percent (49 means 49%), currency (with currency, like \"EUR\"), seconds (a length of time), milliseconds or text. bars, table, list and metrics take \"width\": \"half\" to sit beside the next half block.", "items": {"type": "object", "properties": {"type": {"type": "string", "enum": ["heading", "text", "metrics", "chart", "bars", "table", "list", "divider"]}}, "required": ["type"]}}}, "required": ["title", "blocks"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/view_save": {"post": {"operationId": "view_save", "summary": "Save a dashboard", "description": "Keep a view under a name, like the company's weekly dashboard, and replace what it shows whenever you like (same blocks as view_show). view_link makes one-time links to its latest version. Costs $0.01 per call; nothing if it fails.", "tags": ["views"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The saved view's name, like weekly-sales."}, "title": {"type": "string", "minLength": 1, "maxLength": 200}, "subtitle": {"type": "string", "maxLength": 300, "description": "A line under the title, like the period it covers."}, "blocks": {"type": "array", "minItems": 1, "maxItems": 60, "description": "blocks is a list, drawn top to bottom. Each block is one of: {\"type\": \"heading\", \"text\"}; {\"type\": \"text\", \"text\"} (blank lines make paragraphs); {\"type\": \"metrics\", \"items\": [{\"label\", \"value\", \"format\", \"currency\", \"change\" (percent), \"better\": \"up\"|\"down\", \"note\", \"tone\": \"good\"|\"warn\"|\"bad\"}]} (up to 8 numbers in a row); {\"type\": \"chart\", \"title\", \"kind\": \"line\"|\"bar\", \"labels\": [...], \"series\": [{\"name\", \"values\": [...]}], \"format\", \"currency\"} (up to 4 series of up to 400 points); {\"type\": \"bars\", \"title\", \"label_header\", \"value_header\", \"items\": [{\"label\", \"value\", \"detail\", \"link\", \"country\" (a two-letter code: shows the flag, and the name when label is left out)}], \"format\", \"currency\"} (ranked rows with a bar each, up to 50); {\"type\": \"table\", \"title\", \"columns\": [{\"label\", \"format\", \"currency\"}], \"rows\": [[...], ...]} (up to 12 columns and 500 rows); {\"type\": \"list\", \"title\", \"items\": [{\"title\", \"text\", \"meta\", \"link\"}]} (up to 100); {\"type\": \"divider\"}. format is number, percent (49 means 49%), currency (with currency, like \"EUR\"), seconds (a length of time), milliseconds or text. bars, table, list and metrics take \"width\": \"half\" to sit beside the next half block.", "items": {"type": "object", "properties": {"type": {"type": "string", "enum": ["heading", "text", "metrics", "chart", "bars", "table", "list", "divider"]}}, "required": ["type"]}}}, "required": ["name", "title", "blocks"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/view_link": {"post": {"operationId": "view_link", "summary": "Get a link to a saved dashboard", "description": "A one-time link to a saved view as it is now: the first browser that opens it keeps it for an hour, and an unopened link expires after 7 days. Make one per person. Free.", "tags": ["views"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The saved view's name, like weekly-sales."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/view_send_link": {"post": {"operationId": "view_send_link", "summary": "Send a saved dashboard", "description": "Send each person their own one-time link to a saved view as it is now: by email in the business's name, and to saved notify channels. Email follows the rules of every email from the account (free credit emails only the owner; new addresses are capped a day). A schedule repeating this call every Monday is the weekly dashboard. $0.02 per email and $0.005 per channel, for the ones that went out. Costs $0.02 per email, $0.005 per channel (at most $0.225 a call); nothing if it fails.", "tags": ["views"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The saved view's name, like weekly-sales."}, "to": {"type": "array", "maxItems": 10, "items": {"type": "string", "maxLength": 254}, "description": "Email addresses; each gets its own link."}, "channels": {"type": "array", "maxItems": 5, "items": {"type": "string", "maxLength": 60}, "description": "Saved notify channels (notify_list_channels); each gets its own link."}, "message": {"type": "string", "maxLength": 1000, "description": "A line above the link."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/view_list": {"post": {"operationId": "view_list", "summary": "List saved dashboards", "description": "The saved views, newest change first. Free.", "tags": ["views"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/view_get": {"post": {"operationId": "view_get", "summary": "Read a saved dashboard", "description": "A saved view with all its blocks, to change part of it. Free.", "tags": ["views"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The saved view's name, like weekly-sales."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/view_delete": {"post": {"operationId": "view_delete", "summary": "Delete a saved dashboard", "description": "Delete a saved view; links to it stop working. Free.", "tags": ["views"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The saved view's name, like weekly-sales."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_setup": {"post": {"operationId": "books_setup", "summary": "Set up the books", "description": "Start the business's double-entry books, or change their settings. The first call needs currency (the base currency of every report; it can't change once something is booked) and makes the chart: \"starter\" (cash, bank, receivables, tax, equity, sales and common costs, numbered 1000-8000) or \"minimal\" (only the eight accounts the books post to on their own). The books start on start_date (default: the start of this fiscal year); enter what the business owned and owed that day as one entry against the opening balances account (3900), unpaid invoices and bills from before included. With post_invoices (default on), sent invoices and supplier bills, their payments and voids post on their own, those from start_date on right away. payment_accounts says where payments land per method, in and out (default: the bank account, cash in the cash account); rates are standing exchange rates for currencies the European Central Bank doesn't publish. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"EUR\"."}, "start_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The first day the books cover."}, "chart": {"type": "string", "enum": ["starter", "minimal"], "description": "Only on the first call."}, "fiscal_year_start": {"type": "integer", "minimum": 1, "maximum": 12, "description": "The month the fiscal year starts. Default 1 (January)."}, "post_invoices": {"type": "boolean"}, "payment_accounts": {"type": "object", "additionalProperties": {"type": ["string", "null"]}, "description": "Payment method -> account code, e.g. {\"card\": \"1020\"}; null goes back to the default. Methods: bank_transfer, card, cash, check, online, other."}, "rates": {"type": "object", "additionalProperties": {"type": ["number", "string", "null"]}, "description": "Currency -> one unit of it in the base currency, e.g. {\"AED\": \"0.2486\"}; null removes one. Used instead of the ECB's rate."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_get": {"post": {"operationId": "books_get", "summary": "Read the books' settings", "description": "The base currency, start date, fiscal year, locked period, which accounts hold which role, where invoice payments land, the taxes, how many entries there are and how many bank lines wait to be matched. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_list_accounts": {"post": {"operationId": "books_list_accounts", "summary": "List the chart of accounts", "description": "Every account with its code, type, role and balance on as_of (default today). Balance sheet accounts show their balance; income and expense accounts show the fiscal year so far. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"as_of": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "include_archived": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_save_accounts": {"post": {"operationId": "books_save_accounts", "summary": "Add or change accounts", "description": "Add accounts or change them, matched by code: name, type (only while unused), description, a new code, archived (only with no balance and no role), a bank account's IBAN and BIC, and role. Roles are the accounts the books post to on their own: bank, cash, receivable, inventory, input_tax, sales_tax, payable, retained_earnings, opening_balances, sales, cost_of_sales, exchange, depreciation, accumulated_depreciation, asset_disposals, customer_credits, supplier_credits, expense_claims, import_vat. Giving a role moves it from the account that had it. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"accounts": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "required": ["code"], "properties": {"code": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "name": {"type": "string", "maxLength": 120}, "type": {"type": "string", "enum": ["asset", "liability", "equity", "income", "expense"]}, "role": {"type": "string", "enum": ["", "bank", "cash", "receivable", "inventory", "input_tax", "sales_tax", "payable", "retained_earnings", "opening_balances", "sales", "cost_of_sales", "exchange", "depreciation", "accumulated_depreciation", "asset_disposals", "customer_credits", "supplier_credits", "expense_claims", "import_vat"]}, "description": {"type": "string", "maxLength": 500}, "archived": {"type": "boolean"}, "new_code": {"type": "string", "maxLength": 20}, "iban": {"type": "string", "maxLength": 42, "description": "A bank account's IBAN, what bills paid in a batch are paid from; \"\" clears it."}, "bic": {"type": "string", "maxLength": 11}}}}}, "required": ["accounts"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_save_tax": {"post": {"operationId": "books_save_tax", "summary": "Add or change a tax", "description": "A tax rate the books use (VAT, GST, sales tax), matched by name. Tax charged on sales is owed on sales_account (default: the sales tax account); tax paid on purchases is reclaimed on purchase_account (default: the tax to reclaim account; null when it can't be reclaimed, and it stays part of the cost). A rate in use can't change: add a new tax and archive the old one. Invoices make the taxes they need on their own. kind makes a new tax one the business owes itself, like Xero's reverse charge rates: rc_eu (services from another EU country), rc_abroad (from outside it), rc_home (reverse charge at home) or eu_goods (goods from another EU country); on an expense or a bank line it books the VAT owed and reclaimed at once, the amount paid being without VAT. kind import is import VAT paid at customs, no rate: what is booked with it is the VAT itself, reclaimed whole on the import VAT account (1310, made with it), where an expense or a bank line counts with no tax named (box 62 in Germany, box 4 in the UK). Conecto gives no tax advice; the rates are the business's. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 60, "minLength": 1}, "rate": {"type": ["number", "string"], "maxLength": 24, "description": "Percent, e.g. 19."}, "sales_account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "purchase_account": {"type": ["string", "null"], "maxLength": 20}, "archived": {"type": "boolean"}, "new_name": {"type": "string", "maxLength": 60}, "kind": {"type": "string", "enum": ["rc_eu", "rc_abroad", "rc_home", "eu_goods", "import"], "description": "For a new tax: VAT the business owes itself, or import VAT."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_record_entry": {"post": {"operationId": "books_record_entry", "summary": "Book a journal entry", "description": "Book an entry: two or more lines, each a debit or a credit on an account, which must balance. For anything the other tools don't cover: opening balances, a loan, depreciation, owner's drawings, moving money between accounts, a correction. Entries are never edited; undo one with books_reverse_entry. Lines can carry a tax so the tax report counts them. Costs $0.01 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "memo": {"type": "string", "maxLength": 500}, "reference": {"type": "string", "maxLength": 120}, "party": {"type": "string", "maxLength": 200, "description": "Who paid or was paid."}, "lines": {"type": "array", "minItems": 2, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["account"], "properties": {"account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "debit": {"type": ["number", "string"], "maxLength": 24, "description": "A positive amount."}, "credit": {"type": ["number", "string"], "maxLength": 24, "description": "A positive amount."}, "description": {"type": "string", "maxLength": 300}, "tax": {"type": "string", "maxLength": 60, "description": "A tax by name (books_get lists them), e.g. \"VAT 19%\"."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "Tracking options by category, e.g. {\"Department\": \"Service\"} (books_list_tracking)."}}}}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "When it is not the base currency, e.g. \"USD\". The rate is then rate, a standing rate, or the European Central Bank's for the date."}, "rate": {"type": ["number", "string"], "maxLength": 24, "description": "One unit of currency in the base currency, e.g. \"0.9241\". Default: a standing rate, else the European Central Bank's reference rate for the date."}, "receipt_file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file_id from the file store."}}, "required": ["date", "lines"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_record_expense": {"post": {"operationId": "books_record_expense", "summary": "Book an expense", "description": "Book a cost the business paid: account is what it was for (an expense, or an asset like equipment), paid_from where the money came from (default the bank account; a card, cash or the owner's account). paid_by instead (an email) makes it an expense claim, like Xero's: someone paid with their own money and is paid back with books_repay_claims. With a tax, the tax to reclaim is split off (amount includes it unless amount_includes_tax is false). Attach the receipt from the file store. A negative amount is a refund. Costs $0.01 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "amount": {"type": ["number", "string"], "maxLength": 24, "description": "e.g. \"119.00\"."}, "account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "paid_from": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "tax": {"type": "string", "maxLength": 60, "description": "A tax by name (books_get lists them), e.g. \"VAT 19%\"."}, "amount_includes_tax": {"type": "boolean", "default": true}, "vendor": {"type": "string", "maxLength": 200}, "memo": {"type": "string", "maxLength": 500}, "reference": {"type": "string", "maxLength": 120, "description": "e.g. the receipt number."}, "receipt_file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file_id from the file store."}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "When it is not the base currency, e.g. \"USD\". The rate is then rate, a standing rate, or the European Central Bank's for the date."}, "rate": {"type": ["number", "string"], "maxLength": 24, "description": "One unit of currency in the base currency, e.g. \"0.9241\". Default: a standing rate, else the European Central Bank's reference rate for the date."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "Tracking options by category, e.g. {\"Department\": \"Service\"} (books_list_tracking)."}, "paid_by": {"type": "string", "maxLength": 254, "description": "The email of whoever paid it privately and is paid back: an expense claim. Not with paid_from."}, "paid_by_name": {"type": "string", "maxLength": 200}}, "required": ["date", "amount", "account"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_repay_claims": {"post": {"operationId": "books_repay_claims", "summary": "Pay back expense claims", "description": "Pay back what someone paid for the business with their own money (expense claims, from books_record_expense with paid_by), like Xero's: all their open claims in one currency, or the claims named, in one entry from paid_from (default the bank account) against Expense claims to repay. sepa_file: true adds a SEPA credit transfer file to their iban, to upload to the bank. Costs $0.01 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "maxLength": 254, "minLength": 3, "description": "Their email, as paid_by had it."}, "claims": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "integer", "minimum": 1}, "description": "Only these claims (claim_id)."}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "When it is not the base currency, e.g. \"USD\". The rate is then rate, a standing rate, or the European Central Bank's for the date."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "When it was paid. Default today."}, "paid_from": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "reference": {"type": "string", "maxLength": 140}, "sepa_file": {"type": "boolean", "default": false}, "iban": {"type": "string", "maxLength": 42}, "bic": {"type": "string", "maxLength": 11}}, "required": ["person"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_list_claims": {"post": {"operationId": "books_list_claims", "summary": "List expense claims", "description": "Expense claims: what people paid for the business with their own money, still to repay (the default), repaid, void or all, newest first, with what each person is owed per currency; person keeps to one. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "maxLength": 254}, "status": {"type": "string", "enum": ["to_repay", "repaid", "void", "all"], "default": "to_repay"}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_reverse_entry": {"post": {"operationId": "books_reverse_entry", "summary": "Reverse an entry", "description": "Undo an entry by booking its mirror image (entries are never edited or deleted). It is dated like the entry, or today when that period is locked, unless date is given. Bank lines matched to the entry wait to be matched again. Entries posted from invoices follow the invoice: void it, or record a refund. Costs $0.01 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"entry": {"type": "integer", "minimum": 1, "description": "The entry number."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "memo": {"type": "string", "maxLength": 500}}, "required": ["entry"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_attach_receipt": {"post": {"operationId": "books_attach_receipt", "summary": "Attach a receipt", "description": "Attach a receipt or invoice from the file store to an entry that has none. It stays with the books: the file can't be deleted while the entry has it. Costs $0.01 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"entry": {"type": "integer", "minimum": 1, "description": "The entry number."}, "file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file_id from the file store."}}, "required": ["entry", "file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_list_entries": {"post": {"operationId": "books_list_entries", "summary": "List entries", "description": "Entries newest first, each with its lines, filtered by dates, an account, where it came from (manual, expense, bank, invoice, invoice_payment, invoice_void, reversal) or text in the memo, reference or party. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "source": {"type": "string", "enum": ["manual", "expense", "bank", "invoice", "invoice_payment", "invoice_void", "reversal", "stock", "bill", "bill_payment", "bill_void", "credit_note", "depreciation", "asset_disposal", "customer_credit", "supplier_credit", "expense_claim"]}, "text": {"type": "string", "maxLength": 100}, "entry": {"type": "integer", "minimum": 1, "description": "The entry number."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_import_bank": {"post": {"operationId": "books_import_bank", "summary": "Import a bank statement", "description": "Read a bank statement from the file store onto a bank account (default the bank account): CSV as the bank exports it, CAMT.053 (.052, .054) or OFX/QFX. CSV columns are found by their headers in several languages; when they aren't, name them with columns. Lines imported before are skipped, so overlapping statements are fine. Each line then waits in books_bank_lines to be matched. Charged per line added. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file_id from the file store."}, "account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "columns": {"type": "object", "additionalProperties": false, "properties": {"date": {"type": "string", "maxLength": 100}, "amount": {"type": "string", "maxLength": 100}, "money_in": {"type": "string", "maxLength": 100}, "money_out": {"type": "string", "maxLength": 100}, "description": {"type": "string", "maxLength": 100}, "counterparty": {"type": "string", "maxLength": 100}, "reference": {"type": "string", "maxLength": 100}, "currency": {"type": "string", "maxLength": 100}, "balance": {"type": "string", "maxLength": 100}, "direction": {"type": "string", "maxLength": 100}, "bank_id": {"type": "string", "maxLength": 100}}, "description": "CSV header names, e.g. {\"date\": \"Buchungstag\", \"amount\": \"Betrag\", \"description\": \"Verwendungszweck\"}. money_in and money_out are for files with two amount columns; direction for a debit/credit marker column."}, "date_format": {"type": "string", "enum": ["YYYY-MM-DD", "DD.MM.YYYY", "DD.MM.YY", "DD/MM/YYYY", "MM/DD/YYYY", "DD/MM/YY", "MM/DD/YY", "DD-MM-YYYY", "MM-DD-YYYY", "YYYY/MM/DD", "YYYY.MM.DD", "YYYYMMDD", "DD MMM YYYY", "DD-MMM-YYYY", "MMM DD, YYYY", "DD MMMM YYYY"]}, "decimal": {"type": "string", "enum": [",", "."], "description": "The CSV's decimal mark."}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "The statement's currency when the file doesn't say. Default the base currency."}, "max_lines": {"type": "integer", "minimum": 1, "maximum": 5000, "default": 500, "description": "The most lines this call may add (and hold the price for)."}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_bank_lines": {"post": {"operationId": "books_bank_lines", "summary": "List bank lines", "description": "Imported bank lines, by default those still to match, oldest first, each with up to three suggestions of what it was: entries already booked (same amount, close in date), an open invoice it pays (money in) or an open supplier bill it pays (money out), or the account earlier lines from the same party went to. Suggestions are plain rules; you decide, with books_match_bank_lines (pass a suggestion's match as it is). A first suggestion with sure: true is one the books are sure of (a bank rule, or the number and the exact amount, well ahead of any other); such lines can be matched together in one call. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "status": {"type": "string", "enum": ["new", "matched", "ignored", "all"], "default": "new"}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_match_bank_lines": {"post": {"operationId": "books_match_bank_lines", "summary": "Match bank lines", "description": "Say what bank lines were, up to 100 at a time, each one of: entries (entry numbers already booked whose lines on the bank account add up to the line), invoices (the open invoices money in pays: their payments are recorded and posted, the amount spread in the order given unless amounts are given), bills (the open supplier bills money out pays, the same way), account (book it there now, with an optional tax split off: a sale when money came in, a cost when it went out), rule (book it the way a bank rule says), ignore (not for the books, e.g. a duplicate), or unmatch (undo; a line booked to an account is reversed). Each line succeeds or fails on its own; only those done are charged. Costs $0.02 per bank line matched; nothing if none are found.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"matches": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "required": ["line_id"], "properties": {"line_id": {"type": "integer", "minimum": 1}, "entries": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "integer", "minimum": 1, "description": "The entry number."}}, "invoices": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "object", "additionalProperties": false, "required": ["invoice_id"], "properties": {"invoice_id": {"type": "string", "minLength": 36, "maxLength": 36}, "amount": {"type": ["number", "string"], "maxLength": 24}}}}, "bills": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "object", "additionalProperties": false, "required": ["bill_id"], "properties": {"bill_id": {"type": "string", "minLength": 36, "maxLength": 36}, "amount": {"type": ["number", "string"], "maxLength": 24}}}}, "account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "tax": {"type": "string", "maxLength": 60, "description": "A tax by name (books_get lists them), e.g. \"VAT 19%\"."}, "description": {"type": "string", "maxLength": 300}, "rate": {"type": ["number", "string"], "maxLength": 24, "description": "One unit of currency in the base currency, e.g. \"0.9241\". Default: a standing rate, else the European Central Bank's reference rate for the date."}, "rule": {"type": "string", "maxLength": 80, "description": "A bank rule by name (books_list_bank_rules)."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "Tracking options by category, e.g. {\"Department\": \"Service\"} (books_list_tracking)."}, "ignore": {"type": "boolean"}, "unmatch": {"type": "boolean"}}}}}, "required": ["matches"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_save_bank_rule": {"post": {"operationId": "books_save_bank_rule", "summary": "Save a bank rule", "description": "A bank rule, like Xero's: which new bank lines it matches and how to book them, so lines that come every month (bank fees, rent, the phone bill) book themselves. when: conditions on the counterparty, description or reference (contains, equals, starts_with, ends_with; any case), all of them or any (match). Narrow it with direction (in, out), amount_min and amount_max (the line's size, no sign) and bank_account. Book to account with an optional tax split off, or split by percent across accounts (70% phone, 30% private), each part with its own tax. Rules are tried by position, lowest first; the first that matches is the line's first suggestion in books_bank_lines, and books_apply_bank_rules books every line a rule matches. Matched by name; only what you pass changes. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 80, "minLength": 1, "description": "The rule's name, e.g. \"Bank fees\"."}, "new_name": {"type": "string", "maxLength": 80}, "when": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "object", "additionalProperties": false, "required": ["field", "value"], "properties": {"field": {"type": "string", "enum": ["counterparty", "description", "reference"]}, "op": {"type": "string", "enum": ["contains", "equals", "starts_with", "ends_with"], "default": "contains"}, "value": {"type": "string", "maxLength": 120, "minLength": 1, "description": "The words to look for, in any case."}}}}, "match": {"type": "string", "enum": ["all", "any"], "default": "all"}, "direction": {"type": "string", "enum": ["any", "in", "out"]}, "amount_min": {"type": ["number", "string"], "maxLength": 24}, "amount_max": {"type": ["number", "string"], "maxLength": 24}, "bank_account": {"type": "string", "maxLength": 20, "description": "Only lines on this bank account (its code); \"\" for any."}, "account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "tax": {"type": "string", "maxLength": 60, "description": "A tax by name (books_get lists them), e.g. \"VAT 19%\"."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "Tracking options by category, e.g. {\"Department\": \"Service\"} (books_list_tracking)."}, "split": {"type": "array", "minItems": 2, "maxItems": 10, "items": {"type": "object", "additionalProperties": false, "required": ["account", "percent"], "properties": {"account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "tax": {"type": "string", "maxLength": 60, "description": "A tax by name (books_get lists them), e.g. \"VAT 19%\"."}, "percent": {"type": "number", "exclusiveMinimum": 0, "maximum": 100}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "Tracking options by category, e.g. {\"Department\": \"Service\"} (books_list_tracking)."}}}}, "description": {"type": "string", "maxLength": 300, "description": "The memo of the entries it books. Default: the line's own text."}, "position": {"type": "integer", "minimum": 0, "maximum": 10000}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_list_bank_rules": {"post": {"operationId": "books_list_bank_rules", "summary": "List bank rules", "description": "The bank rules, in the order they are tried: their conditions, where they book, and how often and when each was last used. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_delete_bank_rule": {"post": {"operationId": "books_delete_bank_rule", "summary": "Delete a bank rule", "description": "Delete a bank rule. What it booked stays booked. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 80, "minLength": 1, "description": "The rule's name, e.g. \"Bank fees\"."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_apply_bank_rules": {"post": {"operationId": "books_apply_bank_rules", "summary": "Book lines by the bank rules", "description": "Book every new bank line a rule matches, oldest first, each by the first rule that matches (up to limit), on one bank account or all. Run it after books_import_bank. Lines no rule matches wait for books_match_bank_lines; a line the books can't take (a locked month) is listed under skipped with why. $0.02 per line booked, as matching it by hand. Costs $0.02 per bank line booked; nothing if none are found.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"bank_account": {"type": "string", "maxLength": 20, "description": "Only lines on this bank account (its code)."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 100}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_save_tracking": {"post": {"operationId": "books_save_tracking", "summary": "Save a tracking category", "description": "A tracking category, like Xero's: a department, a region or a project line, with its options. Up to two at a time. Any line can then carry one option of each (tracking: {\"Department\": \"Service\"}): journal entry lines, expenses, bank lines booked to an account, invoice and bill lines; profit and loss splits by a category with books_report by_tracking, or keeps to one option with tracking. Matched by name: options adds options, rename renames them on every line, archive stops new use. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 60, "minLength": 1}, "new_name": {"type": "string", "maxLength": 60}, "options": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 60, "minLength": 1}}, "rename": {"type": "array", "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "required": ["from", "to"], "properties": {"from": {"type": "string", "maxLength": 60}, "to": {"type": "string", "maxLength": 60}}}}, "archive": {"type": "array", "maxItems": 100, "items": {"type": "string", "maxLength": 60}}, "archived": {"type": "boolean", "description": "Archive (or bring back) the whole category."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_list_tracking": {"post": {"operationId": "books_list_tracking", "summary": "List tracking categories", "description": "The tracking categories with their options, archived ones marked. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_save_budget": {"post": {"operationId": "books_save_budget", "summary": "Save a budget", "description": "A budget, like Xero's budget manager: an amount per income or expense account for each month from start (12 months unless months says otherwise). Each line gives amounts (one per month), monthly (the same every month) or yearly (spread evenly); a line for an account already in it replaces that line, and remove takes one out. Hold it against what happened with books_report budget_variance. Matched by name. Not a team's spending budget at Conecto. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 80, "minLength": 1, "description": "The budget's name, e.g. \"2026\"."}, "new_name": {"type": "string", "maxLength": 80}, "start": {"type": "string", "maxLength": 7, "description": "Its first month, like 2026-01."}, "months": {"type": "integer", "minimum": 1, "maximum": 36}, "lines": {"type": "array", "maxItems": 300, "items": {"type": "object", "additionalProperties": false, "required": ["account"], "properties": {"account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "amounts": {"type": "array", "minItems": 1, "maxItems": 36, "items": {"type": ["number", "string"], "maxLength": 24}, "description": "One amount per month of the budget."}, "monthly": {"type": ["number", "string"], "maxLength": 24, "description": "The same amount every month."}, "yearly": {"type": ["number", "string"], "maxLength": 24, "description": "A year's amount, spread evenly over the months."}, "remove": {"type": "boolean", "description": "Take the account out of the budget."}}}}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_list_budgets": {"post": {"operationId": "books_list_budgets", "summary": "List budgets", "description": "The budgets with their months and every line's amounts and total. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_delete_budget": {"post": {"operationId": "books_delete_budget", "summary": "Delete a budget", "description": "Delete a budget. The books don't change. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 80, "minLength": 1, "description": "The budget's name, e.g. \"2026\"."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_save_asset": {"post": {"operationId": "books_save_asset", "summary": "Register a fixed asset", "description": "Put an asset the business bought in the register, like Xero's fixed assets: a van, a machine, a laptop, with its cost, purchase date and the asset account its purchase was booked to (registering books nothing). method: straight_line over its life down to residual, declining_balance at rate_percent of its book value at the start of each fiscal year, full (all of it in the month it starts, for something cheap enough to write off at once) or none (land). averaging: full_month counts the month it starts in full, actual_days counts days. Depreciation goes to the depreciation expense and accumulated depreciation accounts (made as 6950 and 1590 when missing) unless expense_account and accumulated_account say otherwise. An asset depreciated before the books started brings opening_accumulated. To change one, pass asset: once its depreciation is booked, only its name, description, serial number, warranty and tracking change. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"asset": {"type": "string", "maxLength": 20, "minLength": 1, "description": "The asset to change, by its number. Leave out to register one."}, "number": {"type": "string", "maxLength": 20, "description": "A new asset's number. Default: the next FA-0001."}, "name": {"type": "string", "maxLength": 120, "minLength": 1}, "purchase_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "cost": {"type": ["number", "string"], "maxLength": 24, "description": "What it cost before tax, in the base currency."}, "account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "The asset account its purchase was booked to, e.g. \"1500\"."}, "method": {"type": "string", "enum": ["straight_line", "declining_balance", "full", "none"], "default": "straight_line"}, "averaging": {"type": "string", "enum": ["full_month", "actual_days"], "default": "full_month"}, "life_years": {"type": "number", "minimum": 0.1, "maximum": 100}, "life_months": {"type": "integer", "minimum": 1, "maximum": 1200}, "rate_percent": {"type": ["number", "string"], "maxLength": 24, "description": "Declining balance: the share of its book value a year."}, "residual": {"type": ["number", "string"], "maxLength": 24, "description": "What it is worth at the end of its life. Default 0."}, "depreciation_start": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "When it was first used, if after the purchase date."}, "opening_accumulated": {"type": ["number", "string"], "maxLength": 24, "description": "Depreciation booked before the books started."}, "expense_account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "accumulated_account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "Tracking options by category, e.g. {\"Department\": \"Service\"} (books_list_tracking)."}, "description": {"type": "string", "maxLength": 500}, "serial_number": {"type": "string", "maxLength": 80}, "warranty_until": {"type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$", "description": "YYYY-MM-DD, \"\" for none."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_list_assets": {"post": {"operationId": "books_list_assets", "summary": "List the fixed assets", "description": "The asset register: each asset's cost, accumulated depreciation, book value, how it depreciates and through which month that is booked, with totals. due: what books_depreciate would book through the end of last month. check: the register held against the books per account, like Xero's fixed asset reconciliation; a difference is a purchase not registered yet, or an asset booked out another way. asset gives one asset with its schedule (depreciation and book value per fiscal year) and the months booked. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"asset": {"type": "string", "maxLength": 20, "minLength": 1, "description": "The asset's number, like \"FA-0001\" (books_list_assets)."}, "status": {"type": "string", "enum": ["registered", "disposed", "all"], "default": "registered"}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_depreciate": {"post": {"operationId": "books_depreciate", "summary": "Book depreciation", "description": "Book the depreciation of every registered asset through a month's end (default: the end of last month), like Xero's run depreciation: one entry per month, dated its last day, from the month after the last one booked, so running it again books nothing twice. Months in a locked period are refused; catch_up: true books them in the first open month instead. undo_after books the opposite of what was booked for the months after that date, for every asset or the one asset names; undo before changing an asset's cost, life or method. Costs $0.01 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"through": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "catch_up": {"type": "boolean", "default": false}, "undo_after": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Undo the months after this date."}, "asset": {"type": "string", "maxLength": 20, "minLength": 1, "description": "Only this asset."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_dispose_asset": {"post": {"operationId": "books_dispose_asset", "summary": "Sell or write off an asset", "description": "Take an asset out of the books, sold or written off, like Xero's dispose. Its depreciation is booked through the month it goes first (to the day with actual_days; what was booked for later months is undone), then one entry takes its cost and accumulated depreciation out, books price to paid_to and the difference as a gain or a loss on gain_account (made as 4950 Gains and losses on assets sold when missing). paid_to is the bank account the money went to, or the income account the invoice to the buyer booked it to, which this then clears. A write-off has no price. undo: true brings it back. Costs $0.01 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"asset": {"type": "string", "maxLength": 20, "minLength": 1, "description": "The asset's number, like \"FA-0001\" (books_list_assets)."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "price": {"type": ["number", "string"], "maxLength": 24, "description": "What it sold for before tax. Default 0, a write-off."}, "paid_to": {"type": "string", "maxLength": 20, "minLength": 1, "description": "Where the price went, e.g. \"1010\"."}, "gain_account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "catch_up": {"type": "boolean", "default": false}, "undo": {"type": "boolean", "description": "Bring a sold or written off asset back."}}, "required": ["asset"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_delete_asset": {"post": {"operationId": "books_delete_asset", "summary": "Delete an asset", "description": "Take an asset registered by mistake out of the register. Only while none of its depreciation is booked and it is not sold or written off: else undo its depreciation first (books_depreciate undo_after with asset). The books don't change. Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"asset": {"type": "string", "maxLength": 20, "minLength": 1, "description": "The asset's number, like \"FA-0001\" (books_list_assets)."}}, "required": ["asset"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_report": {"post": {"operationId": "books_report", "summary": "Run a report", "description": "A report in the base currency. profit_and_loss and tax cover from-to (default: this fiscal year so far); balance_sheet and trial_balance are as of to (default today); general_ledger lists each account's lines from-to with running balances (one account, or all, paged); oss is a quarter's sales to consumers in other EU countries for the One Stop Shop return, per country and VAT rate in euros (quarter, default the last one ended; no books needed); reconciliation holds each bank account's books against the closing balance its latest statement on or before to stated: reconciled, to_match (statement lines and entries still to pair explain the difference) or off (unexplained). Like Xero's: profit_and_loss with compare adds columns for earlier months, quarters or years; cash_summary shows the money accounts at the start and end of from-to and what came in and went out, by account; executive_summary (default this month so far) gives cash, profit, margins, what is owed both ways, debtor and creditor days and invoices issued, against the same days a month before; budget_variance holds a budget (books_save_budget) against the actual figures for the months from-to touches; vat_return gives from-to by the boxes of the VAT return the business files itself, Germany's advance return by Kennzahl or the UK's nine boxes (country, default the business's), with what the books can't tell yet. Like Xero's short-term cash flow, cash_forecast projects the money accounts `days` ahead (default 30, up to 180) from open invoices and bills on their due, expected or planned dates and what repeating templates will make, by day and week, with the lowest point and the overdue invoices and bills it leaves out until they have a date to come (each with the id that invoices_set_expected_date or purchasing_set_planned_date takes). snapshot is the year so far (default) against the same days a year before: profit, margins, income and expenses by month, the largest costs, the balance sheet, cash, and the average days from an invoice's or a bill's date to the payment that settled it, for those paid in the period. To show a person, put it in a view (view_show). Free.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"report": {"type": "string", "enum": ["profit_and_loss", "balance_sheet", "trial_balance", "general_ledger", "tax", "oss", "reconciliation", "cash_summary", "executive_summary", "budget_variance", "vat_return", "cash_forecast", "snapshot"]}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "account": {"type": "string", "maxLength": 20, "minLength": 1, "description": "An account code from the chart, e.g. \"6600\"."}, "compare": {"type": "string", "enum": ["month", "quarter", "year"], "description": "For profit_and_loss: add columns for the same days `periods` months, quarters or years before."}, "periods": {"type": "integer", "minimum": 1, "maximum": 11, "description": "With compare; default 1."}, "budget": {"type": "string", "maxLength": 80, "description": "For budget_variance: the budget's name (books_list_budgets)."}, "by_tracking": {"type": "string", "maxLength": 60, "description": "For profit_and_loss: a tracking category to split by, one column per option and one for what is not tracked."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "For profit_and_loss: only lines with these options, e.g. {\"Department\": \"Service\"}."}, "quarter": {"type": "string", "pattern": "^\\d{4}-[Qq][1-4]$", "description": "For oss: like 2026-Q3."}, "country": {"type": "string", "enum": ["DE", "GB"], "description": "For vat_return: whose form. Default the business's country."}, "days": {"type": "integer", "minimum": 1, "maximum": 180, "default": 30, "description": "For cash_forecast: how many days ahead."}, "limit": {"type": "integer", "minimum": 1, "maximum": 2000, "default": 500}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": ["report"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_lock": {"post": {"operationId": "books_lock", "summary": "Lock a period", "description": "Lock the books through a date (a closed month, a filed tax return): nothing new can be booked on or before it, by any tool or invoice. null unlocks. Every change is kept in the books' history. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"through": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, "reason": {"type": "string", "maxLength": 300}}, "required": ["through"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_close_year": {"post": {"operationId": "books_close_year", "summary": "Close a fiscal year for good", "description": "Close a fiscal year once its accounts and tax returns are final: nothing can be booked on or before its last day again, by any tool, invoice or unlock, and every earlier year is closed with it. It can't be undone; a correction found later is booked in the open year. Monthly work uses books_lock instead. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"year_end": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The fiscal year's last day, like 2025-12-31."}, "reason": {"type": "string", "maxLength": 300}}, "required": ["year_end"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/books_export": {"post": {"operationId": "books_export", "summary": "Export the books", "description": "A file in the file store, with a download link: journal (a CSV of every line of every entry from-to, for an accountant or another program), accounts (the chart with balances on to) or datev (a DATEV Buchungsstapel for a German tax adviser: one fiscal year, from-to, default the year so far; needs the datev settings once) or fec (the French Fichier des Écritures Comptables for a tax audit: the fiscal year that holds to, every entry; needs the fec settings once). Conecto files no tax returns: for UK VAT (Making Tax Digital) the journal CSV is the digital link into bridging software. Costs $0.001 per call; nothing if it fails.", "tags": ["books"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"what": {"type": "string", "enum": ["journal", "accounts", "datev", "fec"]}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "datev": {"type": "object", "additionalProperties": false, "description": "For what: datev, kept for the next export. adviser (Beraternummer) and client (Mandantennummer) from the tax adviser; chart \"03\" (SKR03) or \"04\" (SKR04); account_length (4 to 8, default 4); accounts: each account code used to its DATEV number, like {\"4000\": \"8400\", \"1010\": \"1200\"} (same_numbers: true when the chart already uses them); tax_keys: a tax's BU-Schlüssel when it isn't German VAT at 19 or 7 percent.", "properties": {"adviser": {"type": "integer", "minimum": 1001, "maximum": 9999999}, "client": {"type": "integer", "minimum": 1, "maximum": 99999}, "chart": {"type": "string", "enum": ["03", "04"]}, "account_length": {"type": "integer", "minimum": 4, "maximum": 8}, "accounts": {"type": "object", "maxProperties": 500, "additionalProperties": {"type": "string", "maxLength": 9}}, "same_numbers": {"type": "boolean"}, "tax_keys": {"type": "object", "maxProperties": 50, "additionalProperties": {"type": "string", "maxLength": 4}}}}, "fec": {"type": "object", "additionalProperties": false, "description": "For what: fec, kept for the next export. siren (9 digits; read from a French VAT ID when left out); accounts: each account code used to its plan comptable général number, like {\"4000\": \"706000\", \"1010\": \"512000\"} (same_numbers: true when the chart already uses them).", "properties": {"siren": {"type": "string", "maxLength": 14}, "accounts": {"type": "object", "maxProperties": 500, "additionalProperties": {"type": "string", "maxLength": 20}}, "same_numbers": {"type": "boolean"}}}}, "required": ["what"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_save_items": {"post": {"operationId": "inventory_save_items", "summary": "Add or change items", "description": "Add stock items or change them, matched by SKU: name, unit (pcs, kg, m...), barcode, cost (the unit cost used when stock comes in without one), selling price, reorder point (inventory.low_stock is sent when the stock falls to it), a new SKU, archived (only with none in stock). Stock itself changes only by moves (inventory_move) or counts (inventory_stocktake). Costs $0.005 per item saved; nothing if none are found.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"items": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "required": ["sku"], "properties": {"sku": {"type": "string", "maxLength": 64, "minLength": 1, "description": "The item's SKU."}, "name": {"type": "string", "maxLength": 200}, "description": {"type": "string", "maxLength": 1000}, "unit": {"type": "string", "maxLength": 20}, "barcode": {"type": "string", "maxLength": 64}, "cost": {"type": ["number", "string"], "maxLength": 24}, "price": {"type": ["number", "string", "null"], "maxLength": 24}, "reorder_point": {"type": ["number", "string", "null"], "maxLength": 24}, "new_sku": {"type": "string", "maxLength": 64}, "archived": {"type": "boolean"}}}}}, "required": ["items"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_list_items": {"post": {"operationId": "inventory_list_items", "summary": "List items", "description": "Items with what is in stock (in total and per location), the moving-average unit cost and the value. Search by SKU, name or an exact barcode; only those at a location; only those at or below their reorder point. Free.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"search": {"type": "string", "maxLength": 100}, "location": {"type": "string", "maxLength": 120, "description": "A location by name. Default: \"Main\" (made on first use)."}, "low_only": {"type": "boolean", "default": false}, "include_archived": {"type": "boolean", "default": false}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_move": {"post": {"operationId": "inventory_move", "summary": "Move stock", "description": "Change stock, all moves or none: receive (in, at unit_cost, which becomes part of the moving average), ship (out, at the moving average), transfer (from location to another, to), adjust (a signed quantity: found, damaged, used). Stock can't go below 0 at a location. reference ties a move to an order or invoice number. Costs $0.005 per move; nothing if none are found.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"moves": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "required": ["kind", "sku", "quantity"], "properties": {"kind": {"type": "string", "enum": ["receive", "ship", "transfer", "adjust"]}, "sku": {"type": "string", "maxLength": 64, "minLength": 1, "description": "The item's SKU."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Up to 6 decimals; negative only for adjust."}, "location": {"type": "string", "maxLength": 120, "description": "A location by name. Default: \"Main\" (made on first use)."}, "to": {"type": "string", "maxLength": 120, "description": "transfer: where the stock goes."}, "unit_cost": {"type": ["number", "string"], "maxLength": 24, "description": "receive (and adjust in): what one cost. Default: the moving average, else the item's cost."}, "reference": {"type": "string", "maxLength": 120}, "note": {"type": "string", "maxLength": 500}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Default today."}}}}}, "required": ["moves"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_stocktake": {"post": {"operationId": "inventory_stocktake", "summary": "Count a location", "description": "Record a count of one location: each difference from what the moves left there becomes a count move (found stock comes in at the moving average, missing stock leaves at it), so the stock matches what was counted. With full: true, items held there but left out of counts were not found (counted 0). Costs $0.002 per line counted; nothing if none are found.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"location": {"type": "string", "maxLength": 120, "description": "A location by name. Default: \"Main\" (made on first use)."}, "counts": {"type": "array", "minItems": 1, "maxItems": 1000, "items": {"type": "object", "additionalProperties": false, "required": ["sku", "counted"], "properties": {"sku": {"type": "string", "maxLength": 64, "minLength": 1, "description": "The item's SKU."}, "counted": {"type": ["number", "string"], "maxLength": 24}}}}, "full": {"type": "boolean", "default": false}, "note": {"type": "string", "maxLength": 500}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}}, "required": ["counts"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_history": {"post": {"operationId": "inventory_history", "summary": "Stock history", "description": "Moves newest first: of one item, at one location, of one kind, in a period. Free.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"sku": {"type": "string", "maxLength": 64, "minLength": 1, "description": "The item's SKU."}, "location": {"type": "string", "maxLength": 120, "description": "A location by name. Default: \"Main\" (made on first use)."}, "kind": {"type": "string", "enum": ["receive", "ship", "transfer", "adjust", "count"]}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_locations": {"post": {"operationId": "inventory_locations", "summary": "List locations", "description": "Every location with how many items it holds and their value at the moving average. Free.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"include_archived": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_save_location": {"post": {"operationId": "inventory_save_location", "summary": "Add or change a location", "description": "Add a location (a warehouse, a shop, a van) or rename, describe or archive one (only when empty). Costs $0.001 per call; nothing if it fails.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 120, "minLength": 1}, "new_name": {"type": "string", "maxLength": 120}, "description": {"type": "string", "maxLength": 500}, "archived": {"type": "boolean"}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_report": {"post": {"operationId": "inventory_report", "summary": "Run an inventory report", "description": "valuation: what was held on as_of (default today) and its value at the moving average. movement: per item what was received, shipped, adjusted and counted from-to (default this month), with the cost of goods shipped, which the bot books if the business keeps books. low_stock: items at or below their reorder point. Free.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"report": {"type": "string", "enum": ["valuation", "movement", "low_stock"]}, "as_of": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}}, "required": ["report"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_import": {"post": {"operationId": "inventory_import", "summary": "Import items from CSV", "description": "Items from a CSV in the file store, created or changed by SKU. Columns: sku, name, description, unit, barcode, cost, price, reorder_point, quantity, location (sku and, for new items, name). A quantity sets what is held at the row's location (default Main, made if new): the difference becomes an adjustment, in at the row's cost. All rows or none. Charged per row. Costs $0.001 per row imported; nothing if none are found.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file_id": {"type": "string", "minLength": 36, "maxLength": 36}, "max_rows": {"type": "integer", "minimum": 1, "maximum": 5000, "default": 1000, "description": "The most rows this call may import (and hold the price for)."}}, "required": ["file_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/inventory_export": {"post": {"operationId": "inventory_export", "summary": "Export to CSV", "description": "A CSV in the file store, with a download link: items (one row per item and location, with quantities, unit cost and value) or moves (from-to). Costs $0.001 per call; nothing if it fails.", "tags": ["inventory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"what": {"type": "string", "enum": ["items", "moves"]}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}}, "required": ["what"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_create": {"post": {"operationId": "website_create", "summary": "Create a website", "description": "Start a website for the business at cncto.co/w/<name>: a draft with a home page, drawn in the brand kit (account_set_brand: logo and colour). Build it with website_save_page, look at it with website_preview, put it online with website_publish. Nothing is public and nothing is charged by the month until it is published. Costs $0.01 per call; nothing if it fails.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 60, "minLength": 3, "description": "Lowercase letters, digits and dashes, e.g. \"halverson-cycle\"."}, "title": {"type": "string", "maxLength": 120, "minLength": 1, "description": "The site's name, shown in the header and in titles."}, "description": {"type": "string", "maxLength": 300, "description": "One or two sentences for search engines and link previews."}, "language": {"type": "string", "maxLength": 12, "description": "e.g. \"en\", \"de\", \"pt-BR\". Default \"en\"."}}, "required": ["name", "title"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_list": {"post": {"operationId": "website_list", "summary": "List websites", "description": "The account's websites, published or not. Free.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_get": {"post": {"operationId": "website_get", "summary": "Read a website", "description": "A site with every page of its draft (sections, posts), its settings, the kept versions and whether the draft has changes that aren't published yet. Free.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_save_page": {"post": {"operationId": "website_save_page", "summary": "Save a page or a post", "description": "Create or change a page of the draft, matched by path (\"\" is the home page, \"about\", \"services/cleaning\"); only what is passed changes, and sections replace all of the page's sections. A page is made of sections; a blog post (kind \"post\", path = its slug) has a Markdown body and a date, and lives at /blog/<slug>. nav puts the page in the menu with that label. Images are image file_ids from the file store; in Markdown write ![alt](file:<file_id>). Sections, each {\"type\": ...}: hero {heading, text, image, image_alt, buttons [{label, link}] (up to 2), layout \"center\" | \"split\"}; text {heading, body (Markdown)}; features {heading, text, items [{title, text}]}; image {image, alt, caption, size \"normal\" | \"wide\"}; gallery {heading, images [{image, alt, caption}]}; pricing {heading, text, plans [{name, price, period, description, features [..], button, highlight, label (above a highlighted plan; default \"Most popular\" in the site's language)}]}; testimonials {heading, items [{quote, name, role}]}; faq {heading, items [{question, answer (Markdown)}]}; cta {heading, text, button}; stats {heading, items [{value, label}]}; logos {heading, images [{image, alt}]}; contact {heading, text, email, phone, address, form (a form's slug), button_label}; booking {heading, text, meeting (a meeting type's slug), button_label}; newsletter {heading, text, newsletter (its slug), button_label}; posts {heading, count} lists the latest blog posts. Images are image file_ids from the file store, with alt text. A link is a page of the site (\"/about\"), https://..., mailto: or tel:. Optional on any section: id (for \"#links\") and background \"plain\" | \"tinted\" | \"brand\". Costs $0.01 per call; nothing if it fails.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}, "path": {"type": "string", "maxLength": 120}, "kind": {"type": "string", "enum": ["page", "post"], "default": "page"}, "title": {"type": "string", "maxLength": 120}, "description": {"type": "string", "maxLength": 300, "description": "For search engines and link previews."}, "nav": {"type": "string", "maxLength": 40, "description": "The page's label in the menu; \"\" takes it out."}, "nav_order": {"type": "integer", "minimum": -999, "maximum": 999}, "sections": {"type": "array", "maxItems": 40, "description": "Sections, each {\"type\": ...}: hero {heading, text, image, image_alt, buttons [{label, link}] (up to 2), layout \"center\" | \"split\"}; text {heading, body (Markdown)}; features {heading, text, items [{title, text}]}; image {image, alt, caption, size \"normal\" | \"wide\"}; gallery {heading, images [{image, alt, caption}]}; pricing {heading, text, plans [{name, price, period, description, features [..], button, highlight, label (above a highlighted plan; default \"Most popular\" in the site's language)}]}; testimonials {heading, items [{quote, name, role}]}; faq {heading, items [{question, answer (Markdown)}]}; cta {heading, text, button}; stats {heading, items [{value, label}]}; logos {heading, images [{image, alt}]}; contact {heading, text, email, phone, address, form (a form's slug), button_label}; booking {heading, text, meeting (a meeting type's slug), button_label}; newsletter {heading, text, newsletter (its slug), button_label}; posts {heading, count} lists the latest blog posts. Images are image file_ids from the file store, with alt text. A link is a page of the site (\"/about\"), https://..., mailto: or tel:. Optional on any section: id (for \"#links\") and background \"plain\" | \"tinted\" | \"brand\".", "items": {"type": "object", "required": ["type"], "properties": {"type": {"type": "string", "enum": ["hero", "text", "features", "image", "gallery", "pricing", "testimonials", "faq", "cta", "stats", "logos", "contact", "booking", "newsletter", "posts"]}}}}, "body": {"type": "string", "maxLength": 100000, "description": "Posts: Markdown."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Posts. Default today."}, "image": {"type": "string", "maxLength": 36, "description": "A file_id: the image shown when the page is shared, and a post's cover."}}, "required": ["site", "path"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_delete_page": {"post": {"operationId": "website_delete_page", "summary": "Delete a page", "description": "Remove a page or post from the draft (the published site keeps it until the next publish). The home page stays. Costs $0.001 per call; nothing if it fails.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}, "path": {"type": "string", "maxLength": 120}}, "required": ["site", "path"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_settings": {"post": {"operationId": "website_settings", "summary": "Change a website's settings", "description": "The site's title, description and language, the footer (text, links, email, phone, address, social links), a button in the header, the blog's title and menu label, show_name (the site's name beside the logo; by default the logo stands alone, since it usually carries the name), and two switches: analytics_site (a site_id from analytics_add_site whose script the pages carry) and chat (the account's chat widget on every page). Only what is passed changes; it applies to the draft. Costs $0.001 per call; nothing if it fails.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}, "title": {"type": "string", "maxLength": 120}, "description": {"type": "string", "maxLength": 300}, "language": {"type": "string", "maxLength": 12}, "footer": {"type": "object", "additionalProperties": false, "properties": {"text": {"type": "string", "maxLength": 500}, "email": {"type": "string", "maxLength": 254}, "phone": {"type": "string", "maxLength": 40}, "address": {"type": "string", "maxLength": 300}, "links": {"type": "array", "maxItems": 12, "items": {"type": "object", "additionalProperties": false, "required": ["label", "link"], "properties": {"label": {"type": "string", "maxLength": 40}, "link": {"type": "string", "maxLength": 500}}}}, "social": {"type": "array", "maxItems": 8, "items": {"type": "object", "additionalProperties": false, "required": ["label", "link"], "properties": {"label": {"type": "string", "maxLength": 40}, "link": {"type": "string", "maxLength": 500}}}}}}, "header_button": {"type": ["object", "null"], "additionalProperties": false, "required": ["label", "link"], "properties": {"label": {"type": "string", "maxLength": 40}, "link": {"type": "string", "maxLength": 500}}}, "blog": {"type": "object", "additionalProperties": false, "properties": {"title": {"type": "string", "maxLength": 80}, "description": {"type": "string", "maxLength": 300}, "nav": {"type": "string", "maxLength": 40}}}, "analytics_site": {"type": ["string", "null"], "maxLength": 36}, "chat": {"type": "boolean"}, "show_name": {"type": "boolean"}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_preview": {"post": {"operationId": "website_preview", "summary": "Preview a website", "description": "A private link to the draft as it would look published, working for 24 hours (search engines are told to stay away). Open it, or send it to a person to check. Free.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}, "path": {"type": "string", "maxLength": 120, "description": "The page to open. Default the home page."}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_publish": {"post": {"operationId": "website_publish", "summary": "Publish a website", "description": "Put the draft online at cncto.co/w/<name>: visitors see exactly this version until the next publish. The first publish starts the site's rent, $5 a month from the balance; later publishes cost $0.01. The last 20 versions are kept (website_rollback). Costs $5 for the first publish (the first month of the site's rent), $0.01 after that ($5.00 the first time, then $0.01; at most $5.00 a call); nothing if it fails.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_rollback": {"post": {"operationId": "website_rollback", "summary": "Go back to an earlier version", "description": "Publish one of the kept versions again (website_get lists them). The draft stays as it is. Costs $0.01 per call; nothing if it fails.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}, "version": {"type": "integer", "minimum": 1}}, "required": ["site", "version"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_unpublish": {"post": {"operationId": "website_unpublish", "summary": "Take a website offline", "description": "Take the site offline and end its rent. The draft and the kept versions stay; publishing again starts a new month. Free.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/website_delete": {"post": {"operationId": "website_delete", "summary": "Delete a website", "description": "Delete the site for good: its pages, versions and address. It is taken offline first, and its name is never used again, so old links can't open someone else's site. Free.", "tags": ["websites"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"site": {"type": "string", "maxLength": 60, "minLength": 3, "description": "The site's name, as in cncto.co/w/<name>."}}, "required": ["site"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/code_run": {"post": {"operationId": "code_run", "summary": "Run Python or Node.js code", "description": "Run a short program in a fresh sandbox: Python 3.12 (pandas, numpy, scipy, matplotlib, openpyxl, xlsxwriter, pillow, pypdf, python-docx) or Node.js 22 (date-fns, csv-parse, csv-stringify, lodash). Files from the store are in /input (by their names); anything the program writes in its working folder comes back as new files in the store. One CPU, 1 GB of memory, no network (fetch data first with web_read or files_upload). The reply has stdout, stderr (each up to 64 KB), the exit code and the saved files. Costs $0.0001 per started second of run time, at least $0.005 a run ($0.005 for a run under 50 seconds; at most $0.031 a call); nothing if it fails.", "tags": ["code"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"language": {"type": "string", "enum": ["python", "node"]}, "code": {"type": "string", "minLength": 1, "maxLength": 200000, "description": "The whole program."}, "files": {"type": "array", "maxItems": 10, "items": {"type": "string", "minLength": 36, "maxLength": 36}, "description": "file_ids to put in /input."}, "stdin": {"type": "string", "maxLength": 1048576}, "timeout_seconds": {"type": "integer", "minimum": 1, "maximum": 300, "default": 60}}, "required": ["language", "code"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_save_people": {"post": {"operationId": "hr_save_people", "summary": "Add or change people", "description": "Add people or change them, up to 100 at a time, all or none: matched by person_id, else by work email (any case); anyone not found is added (first_name needed). Give only what changes: \"\" clears text, null clears a date. A manager can be anyone on the account, also someone added later in the same call; loops are refused. Status left follows from a past end_date (their last day). Each saved person comes back with their person_id. When you add people partway through a leave year, record what they have already used or carried over with hr_adjust_leave. Costs $1.00 per person added; nothing if none are found.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"people": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "properties": {"person_id": {"type": "integer", "minimum": 1, "maximum": 9223372036854775807, "description": "Who to change. Left out, work_email finds them; if nobody has it, a new person is added."}, "first_name": {"type": "string", "maxLength": 100}, "last_name": {"type": "string", "maxLength": 100}, "preferred_name": {"type": "string", "maxLength": 100, "description": "What they like to be called."}, "work_email": {"type": "string", "maxLength": 254, "description": "One person per address on the account, any case; \"\" clears it."}, "personal_email": {"type": "string", "maxLength": 254}, "phone": {"type": "string", "maxLength": 40}, "job_title": {"type": "string", "maxLength": 120}, "department": {"type": "string", "maxLength": 120}, "location": {"type": "string", "maxLength": 120, "description": "Where they work, e.g. \"Berlin\". Holidays set for this location apply to them."}, "manager": {"type": ["integer", "string", "null"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "Their manager: a person_id or work email on this account (someone added later in the same call is fine); null for none."}, "employment_type": {"type": "string", "enum": ["full_time", "part_time", "contractor", "intern"]}, "start_date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to clear it."}, "probation_end": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to clear it."}, "end_date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Their last day, YYYY-MM-DD (null to clear). Once it has passed their status is left."}, "status": {"type": "string", "enum": ["active", "on_leave"], "description": "on_leave for a long absence (parental leave, a sabbatical). \"left\" follows from end_date."}, "birthday": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to clear it."}, "emergency_contact": {"type": "string", "maxLength": 500, "description": "Who to call, how they are related and their number, as text."}, "notes": {"type": "string", "maxLength": 5000}, "custom": {"type": "object", "maxProperties": 20, "propertyNames": {"minLength": 1, "maxLength": 40}, "additionalProperties": {"type": ["string", "null"], "maxLength": 500}, "description": "Your own fields as text, e.g. {\"T-shirt\": \"M\"}: merged into what is there, null removes one. Up to 20."}, "allowances": {"type": "object", "maxProperties": 20, "propertyNames": {"minLength": 1, "maxLength": 60}, "additionalProperties": {"type": ["number", "string", "null"], "maxLength": 8}, "description": "Their own annual days per tracked leave type where they differ from the type's, e.g. {\"Vacation\": 28}; null goes back to the type's."}}}}}, "required": ["people"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_list_people": {"post": {"operationId": "hr_list_people", "summary": "List people", "description": "People on the account by last name; by default everyone who hasn't left (current, future joiners included). Filter by status (active, on_leave, left, all), department, location, manager (their direct reports), employment type, or search words across names, emails and job title (every word must match). Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["current", "active", "on_leave", "left", "all"], "default": "current"}, "department": {"type": "string", "maxLength": 120}, "location": {"type": "string", "maxLength": 120}, "manager": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "employment_type": {"type": "string", "enum": ["full_time", "part_time", "contractor", "intern"]}, "search": {"type": "string", "maxLength": 100}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_get_person": {"post": {"operationId": "hr_get_person", "summary": "Get a person", "description": "Everything about one person: their details, their time-off balance of each leave type for a leave year (entitlement, carried over, adjustments, approved, pending, available after pending), the adjustments in it, their pending requests and approved leave from today on, documents with download links, open checklist tasks and direct reports. Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "year": {"type": "integer", "minimum": 2000, "maximum": 2100, "description": "A leave year, named by the year it starts in. Default: the current one."}}, "required": ["person"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_delete_person": {"post": {"operationId": "hr_delete_person", "summary": "Delete a person", "description": "Erase a person for good with everything that is theirs: leave requests, adjustments, checklist tasks and document records, for example when they ask to be forgotten. Their files stay in the file store (files_delete removes those). Refused while they manage others: give those people another manager first. To keep someone's history after they go, set their end_date instead. Free. Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}}, "required": ["person"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_get_settings": {"post": {"operationId": "hr_get_settings", "summary": "Read the HR settings", "description": "The working days, hours per day, the month the leave year starts, the time zone and today's date in it; every leave type; the public holidays of a calendar year (every location's, or one location's with everyone's); and the onboarding and offboarding checklists. Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"year": {"type": "integer", "minimum": 2000, "maximum": 2100, "description": "Holidays of this calendar year. Default: this year."}, "location": {"type": "string", "maxLength": 120, "description": "Only this location's holidays and everyone's."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_save_settings": {"post": {"operationId": "hr_save_settings", "summary": "Change the HR settings", "description": "Set the work calendar. working_days: ISO weekday numbers, 1 (Monday) to 7 (Sunday); default 1 to 5. hours_per_day: default 8, used to show leave in hours. leave_year_start: the month the leave year starts, default 1. time_zone: an IANA name; null follows the invoice profile's or the calendar's. holidays: one location's public holidays for one calendar year, replacing that location's list for that year (no location: everyone's; an empty list clears it). Leave already requested keeps the days it was counted with. Costs $0.001 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"working_days": {"type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": {"type": "integer", "minimum": 1, "maximum": 7}}, "hours_per_day": {"type": ["number", "string"], "maxLength": 6}, "leave_year_start": {"type": "integer", "minimum": 1, "maximum": 12}, "time_zone": {"type": ["string", "null"], "maxLength": 64}, "holidays": {"type": "object", "additionalProperties": false, "required": ["year", "days"], "properties": {"year": {"type": "integer", "minimum": 2000, "maximum": 2100, "description": "The calendar year the holidays are in."}, "location": {"type": "string", "maxLength": 120, "description": "Blank or left out: everyone."}, "days": {"type": "array", "maxItems": 60, "items": {"type": "object", "additionalProperties": false, "required": ["date", "name"], "properties": {"date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "name": {"type": "string", "maxLength": 120, "minLength": 1}}}}}}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_save_leave_type": {"post": {"operationId": "hr_save_leave_type", "summary": "Add or change a leave type", "description": "A kind of time off, matched by name (any case), e.g. Vacation (tracked, 25 days), Sick, or Unpaid (tracked: false, paid: false). A tracked type gives everyone annual_days per leave year: all at its start (accrual yearly) or 1/12 per started month (monthly), pro-rated by the months employed for people who join or leave during it and rounded to half days, with up to carry_over_max unused days carried into the next year. An untracked type has no balance; its days are only counted. A person's own allowance is set on them (hr_save_people allowances). Archived types take no new requests. Costs $0.001 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 60, "minLength": 1}, "new_name": {"type": "string", "maxLength": 60}, "annual_days": {"type": ["number", "string"], "maxLength": 8, "description": "Days, in half days, e.g. 25 or 2.5."}, "accrual": {"type": "string", "enum": ["yearly", "monthly"]}, "carry_over_max": {"type": ["number", "string"], "maxLength": 8, "description": "The most unused days carried into the next leave year. Default 0."}, "paid": {"type": "boolean"}, "tracked": {"type": "boolean"}, "archived": {"type": "boolean"}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_adjust_leave": {"post": {"operationId": "hr_adjust_leave", "summary": "Adjust a leave balance", "description": "Add days to, or take days off, one person's balance of a tracked leave type in one leave year, with the reason: what they had already used or carried over when you started keeping their leave here, a day in lieu, a correction. Conecto counts from the leave year a person was added, so earlier history comes in this way. Returns the new balance. Costs $0.01 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "leave_type": {"type": "string", "maxLength": 60, "minLength": 1, "description": "A leave type by name, e.g. \"Vacation\"."}, "days": {"type": ["number", "string"], "maxLength": 8, "description": "Positive adds, negative takes off, in half days, e.g. -12 or 1.5."}, "reason": {"type": "string", "maxLength": 300, "minLength": 1}, "year": {"type": "integer", "minimum": 2000, "maximum": 2100, "description": "A leave year, named by the year it starts in. Default: the current one."}}, "required": ["person", "leave_type", "days", "reason"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_request_leave": {"post": {"operationId": "hr_request_leave", "summary": "Request time off", "description": "Ask for time off for someone, from start to end (default: one day), with a half day on the first and/or last day if wanted. Only working days count, minus the holidays of everyone and of their location; leave that crosses into a new leave year counts in each. Refused when it overlaps their pending or approved leave, has no working days, falls outside their employment or they have left, or when a tracked balance (after pending requests) can't take it, unless allow_negative: true (the reply then says how far below 0 it goes). It waits for hr_decide_leave unless approve: true decides at once. Returns the request_id and the balance after it. Costs $0.01 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "leave_type": {"type": "string", "maxLength": 60, "minLength": 1, "description": "A leave type by name, e.g. \"Vacation\"."}, "start": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "end": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The last day off, YYYY-MM-DD. Default: start."}, "half_start": {"type": "boolean", "default": false, "description": "The first day is a half day."}, "half_end": {"type": "boolean", "default": false, "description": "The last day is a half day."}, "note": {"type": "string", "maxLength": 1000}, "approve": {"type": "boolean", "default": false}, "allow_negative": {"type": "boolean", "default": false}}, "required": ["person", "leave_type", "start"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_decide_leave": {"post": {"operationId": "hr_decide_leave", "summary": "Approve, decline or cancel leave", "description": "Decide on a leave request: approve or decline one that is pending, or cancel one that is pending or approved (approved days go back to the balance). Declined and cancelled requests stay as they are; ask again with hr_request_leave. Approving checks the balance again; allow_negative: true lets it go below 0. Returns the request and the balance after it. Costs $0.01 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"request_id": {"type": "integer", "minimum": 1, "maximum": 9223372036854775807}, "decision": {"type": "string", "enum": ["approve", "decline", "cancel"]}, "note": {"type": "string", "maxLength": 1000}, "allow_negative": {"type": "boolean", "default": false}}, "required": ["request_id", "decision"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_list_leave": {"post": {"operationId": "hr_list_leave", "summary": "List leave requests", "description": "Leave requests, latest start first, each with its request_id: filter by person, status (pending ones wait for hr_decide_leave), leave type, or dates (requests that touch from-to). Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "status": {"type": "string", "enum": ["pending", "approved", "declined", "cancelled"]}, "leave_type": {"type": "string", "maxLength": 60, "minLength": 1, "description": "A leave type by name, e.g. \"Vacation\"."}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_who_is_out": {"post": {"operationId": "hr_who_is_out", "summary": "See who is out", "description": "Who is off from `from` to `to` (default: today only), per person: each leave with its request_id and the working days it takes in the period; plus the public holidays in the period and anyone whose status is on_leave. Filter by department or location; include_pending adds requests still waiting for a decision. Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "department": {"type": "string", "maxLength": 120}, "location": {"type": "string", "maxLength": 120}, "include_pending": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_save_checklist": {"post": {"operationId": "hr_save_checklist", "summary": "Add or change a checklist", "description": "An onboarding or offboarding checklist, matched by name; items replace the ones it had. Each item has a title, an owner (person: the one joining or leaving; manager: their manager; hr; it) and due_days: calendar days from the start date (onboarding) or the last day (offboarding), negative for before it. Tasks already started keep their own copy. Costs $0.001 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 120, "minLength": 1}, "new_name": {"type": "string", "maxLength": 120}, "kind": {"type": "string", "enum": ["onboarding", "offboarding"]}, "items": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "object", "additionalProperties": false, "required": ["title", "owner", "due_days"], "properties": {"title": {"type": "string", "maxLength": 200, "minLength": 1}, "owner": {"type": "string", "enum": ["person", "manager", "hr", "it"]}, "due_days": {"type": "integer", "minimum": -365, "maximum": 365}}}}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_start_checklist": {"post": {"operationId": "hr_start_checklist", "summary": "Start a checklist for someone", "description": "Turn a checklist into tasks for one person, each due its due_days from their start date (onboarding) or last day (offboarding), which must be set. Refused while they still have open tasks from the same checklist. Returns the tasks with their task_id. Costs $0.01 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "checklist": {"type": "string", "maxLength": 120, "minLength": 1, "description": "The checklist's name."}}, "required": ["person", "checklist"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_tasks": {"post": {"operationId": "hr_tasks", "summary": "List checklist tasks", "description": "Checklist tasks, soonest due first: open (default), overdue, done or all; for one person, one owner (person, manager, hr, it), or due on or before a date. Each names who does it: the person or their manager, with their work email. Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "owner": {"type": "string", "enum": ["person", "manager", "hr", "it"]}, "due_before": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Only tasks due on or before this date."}, "status": {"type": "string", "enum": ["open", "overdue", "done", "all"], "default": "open"}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_complete_task": {"post": {"operationId": "hr_complete_task", "summary": "Complete or reopen a task", "description": "Mark a checklist task done, or open it again with done: false. Costs $0.01 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"task_id": {"type": "integer", "minimum": 1, "maximum": 9223372036854775807}, "done": {"type": "boolean", "default": true}}, "required": ["task_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_save_document": {"post": {"operationId": "hr_save_document", "summary": "Attach, change or remove a document", "description": "Keep a file from the file store on a person's record: give person and file_id, a category (contract, id, certificate, review, other), a title (default: the file's name) and expires_on for things like work permits and certificates (the daily digest mentions them 30 days ahead). With document_id, change its category, title or expiry, or take it off the record with remove: true. While attached, the file can't be deleted; removed, it stays in the store. Costs $0.01 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file_id from the file store."}, "document_id": {"type": "integer", "minimum": 1, "maximum": 9223372036854775807}, "category": {"type": "string", "enum": ["contract", "id", "certificate", "review", "other"]}, "title": {"type": "string", "maxLength": 200}, "expires_on": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null to clear it."}, "remove": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_report": {"post": {"operationId": "hr_report", "summary": "Run an HR report", "description": "headcount: who works here on as_of (default today), by department, location and employment type, people on leave counted. joiners_leavers: who started, and whose last day fell, from-to. time_off: approved working days off from-to, per leave type and per person. balances: everyone's balance of each tracked leave type for a leave year (default the current one), paged. Periods default to this leave year so far. To show a person, put it in a view (view_show). Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"report": {"type": "string", "enum": ["headcount", "joiners_leavers", "time_off", "balances"]}, "as_of": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "year": {"type": "integer", "minimum": 2000, "maximum": 2100, "description": "A leave year, named by the year it starts in. Default: the current one."}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": ["report"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_dashboard_link": {"post": {"operationId": "hr_dashboard_link", "summary": "Get a link to the team overview", "description": "A one-time link to HR at a glance: who works here, who is out today and in the next 14 days, leave waiting for a decision, open tasks, and who starts or leaves in the next 30 days. Only when the person you work for asks to see it themselves: answer who is out and decide leave with HR's own tools first, and offer a link when they would rather look, making it once they say yes. The page is made when it opens, from HR's own reads as this key, so it shows only what this key may see: the same page as account_dashboard_link with area hr. It opens once and keeps for an hour; an unopened link ends after 7 days. Free. Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_save_policy": {"post": {"operationId": "hr_save_policy", "summary": "Save a policy to acknowledge", "description": "A policy people must read and confirm (an AI use policy, a code of conduct, a security policy), in Markdown, for everyone or some departments. Changing its title or text makes a new version, which needs confirming again. Send it with hr_send_policy. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$", "description": "Like ai-use-policy."}, "title": {"type": "string", "maxLength": 200, "minLength": 1}, "text": {"type": "string", "maxLength": 100000, "minLength": 1}, "departments": {"type": "array", "maxItems": 50, "items": {"type": "string", "maxLength": 120, "minLength": 1}, "description": "Only these departments; everyone if left out."}}, "required": ["name", "title", "text"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_send_policy": {"post": {"operationId": "hr_send_policy", "summary": "Send a policy to confirm", "description": "Email each person in the policy's scope (or just those named) a one-time link to read the current version and confirm it. People who confirmed it already, or have no work email, are skipped. Needs a paid account; at most 500 a day. $0.02 per email sent. Costs $0.02 per email sent; nothing if none are found.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$", "description": "Like ai-use-policy."}, "people": {"type": "array", "maxItems": 500, "items": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_record_training": {"post": {"operationId": "hr_record_training", "summary": "Record a training", "description": "A training someone completed: its kind (ai_literacy for the EU AI Act's Art. 4, privacy, security, safety, other), date, hours, certificate from the file store and expiry. $0.01. Costs $0.01 per call; nothing if it fails.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 254, "description": "The person_id, or their work email."}, "course": {"type": "string", "maxLength": 200, "minLength": 1}, "kind": {"type": "string", "enum": ["ai_literacy", "privacy", "security", "safety", "other"]}, "completed_on": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "hours": {"type": "number", "minimum": 0, "maximum": 9999}, "certificate_file_id": {"type": "string", "minLength": 36, "maxLength": 36}, "expires_on": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}}, "required": ["person", "course", "kind", "completed_on"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hr_policy_status": {"post": {"operationId": "hr_policy_status", "summary": "See who confirmed policies and trainings", "description": "Per policy, its current version and who in its scope confirmed it, who has a link waiting and who was never sent one; per kind of training (or one kind), who holds a valid one, who has none and what expires within 60 days. For audits and AI literacy (EU AI Act Art. 4). Free.", "tags": ["hr"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$", "description": "Like ai-use-policy."}, "training_kind": {"type": "string", "enum": ["ai_literacy", "privacy", "security", "safety", "other"]}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_save_supplier": {"post": {"operationId": "purchasing_save_supplier", "summary": "Add or change a supplier", "description": "Add a supplier, matched by name (any case), or change one by supplier_id (name then renames it): contact name, email (purchase orders are emailed there), phone, address, tax ID, the currency they bill in (default: the books' or the invoice profile's), payment terms in days (their bills fall due that long after their date; default 30), and account: the book account code their bills' lines go to by default (an expense or asset account, e.g. \"6600\"). iban and bic are where the business pays them: new or changed bank details always wait for a person other than the one asking (approval_required), because a changed account is how invoice fraud takes payments. Give only what changes. Archived suppliers take no new orders or bills. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 200, "minLength": 1}, "supplier_id": {"type": "integer", "minimum": 1, "maximum": 9223372036854775807}, "contact_name": {"type": "string", "maxLength": 120}, "email": {"type": "string", "maxLength": 254}, "phone": {"type": "string", "maxLength": 60}, "address": {"type": "string", "maxLength": 1000, "description": "Postal address, one line per row."}, "tax_id": {"type": "string", "maxLength": 60}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"EUR\"."}, "terms_days": {"type": "integer", "minimum": 0, "maximum": 365}, "account": {"type": "string", "maxLength": 20, "description": "A book account code, e.g. \"6600\"; \"\" clears it."}, "notes": {"type": "string", "maxLength": 5000}, "iban": {"type": "string", "maxLength": 42, "description": "Their IBAN; spaces are fine."}, "bic": {"type": "string", "maxLength": 11}, "country": {"type": "string", "maxLength": 2, "description": "Where they are, ISO 3166-1 like \"FR\": tells reverse-charge bills apart."}, "archived": {"type": "boolean"}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_list_suppliers": {"post": {"operationId": "purchasing_list_suppliers", "summary": "List suppliers", "description": "Suppliers by name, each with what the business owes them on open bills (per currency) and how many orders are open. Search by name, contact or email. Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"search": {"type": "string", "maxLength": 100}, "include_archived": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_create_order": {"post": {"operationId": "purchasing_create_order", "summary": "Draft a purchase order", "description": "Draft an order to a supplier: lines with an optional Inventory sku (received stock then comes into Inventory at the line's unit cost), a description, quantity, unit cost and tax rate; the currency (default the supplier's), the expected delivery date and the stock location deliveries go to (default Main). A draft changes freely (purchasing_update_order) until it is sent; it has no number yet. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "lines": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["unit_cost"], "properties": {"sku": {"type": "string", "maxLength": 64, "description": "An Inventory item's SKU: received stock comes into Inventory. Its name is the default description."}, "description": {"type": "string", "maxLength": 2000, "description": "What is bought. Lines after the first print smaller, underneath."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Default 1. Up to 6 decimals."}, "unit_cost": {"type": ["number", "string"], "maxLength": 24, "description": "The cost of one before tax, e.g. \"12.50\"."}, "tax_rate": {"type": ["number", "string"], "maxLength": 24, "description": "Tax percent on the line, e.g. 19. Default 0."}}}}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"EUR\". Default: the supplier's."}, "expected_on": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "When delivery is expected, YYYY-MM-DD."}, "location": {"type": "string", "maxLength": 120, "description": "An Inventory location for received stock. Default: Main."}, "notes": {"type": "string", "maxLength": 5000, "description": "Printed above the lines, e.g. delivery instructions."}}, "required": ["supplier", "lines"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_save_supplier_items": {"post": {"operationId": "purchasing_save_supplier_items", "summary": "Say what a supplier sells", "description": "Which Inventory items a supplier sells: their article code, the unit cost in the supplier's currency, the pack size and minimum order, the lead time in days, and a fixed quantity to order at a time when there is one. Saved by SKU (saving again changes it). The first supplier of an item is its preferred one; preferred: true moves it. purchasing_draft_reorders orders from the preferred supplier. Costs $0.005 per item saved; nothing if none are found.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "items": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["sku", "unit_cost"], "properties": {"sku": {"type": "string", "maxLength": 64}, "code": {"type": "string", "maxLength": 64, "description": "The supplier's own article number."}, "unit_cost": {"type": ["number", "string"], "maxLength": 24}, "pack_size": {"type": ["number", "string"], "maxLength": 24, "description": "Sold in packs of this many. Default 1."}, "min_order": {"type": ["number", "string"], "maxLength": 24}, "order_quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Always order this many (rounded up to packs)."}, "lead_days": {"type": "integer", "minimum": 0, "maximum": 365}, "preferred": {"type": "boolean"}}}}}, "required": ["supplier", "items"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_list_supplier_items": {"post": {"operationId": "purchasing_list_supplier_items", "summary": "List what suppliers sell", "description": "The items suppliers sell, with their codes, costs, packs, minimums, lead times and which supplier is preferred, for one supplier or one SKU. Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "sku": {"type": "string", "maxLength": 64}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_draft_reorders": {"post": {"operationId": "purchasing_draft_reorders", "summary": "Draft reorders for low stock", "description": "For every Inventory item at or below its reorder point, counting what is already on order (drafts too), draft one purchase order per supplier: the preferred supplier's fixed order quantity, or enough to bring stock and orders to twice the reorder point, raised to the minimum order and rounded up to whole packs. You check and send them (purchasing_send_order). dry_run: true only shows the plan. Items no supplier sells are listed. $0.01 per draft order. Costs $0.01 per draft order; nothing if none are found.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"skus": {"type": "array", "maxItems": 200, "items": {"type": "string", "maxLength": 64}, "description": "Only these items."}, "dry_run": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_update_order": {"post": {"operationId": "purchasing_update_order", "summary": "Change a draft order, or mark it sent", "description": "Change a draft: its supplier, lines (they replace the old ones), currency, expected delivery date, stock location or notes. mark_sent: true records it as sent without emailing anyone (you sent it some other way): it takes the next number (PO-0001 on, without gaps) and its PDF is made. A sent order no longer changes; to email it, use purchasing_send_order instead. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"order": {"type": "string", "maxLength": 40, "minLength": 1, "description": "The order_id, or the order's number like \"PO-0007\"."}, "supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "lines": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["unit_cost"], "properties": {"sku": {"type": "string", "maxLength": 64, "description": "An Inventory item's SKU: received stock comes into Inventory. Its name is the default description."}, "description": {"type": "string", "maxLength": 2000, "description": "What is bought. Lines after the first print smaller, underneath."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Default 1. Up to 6 decimals."}, "unit_cost": {"type": ["number", "string"], "maxLength": 24, "description": "The cost of one before tax, e.g. \"12.50\"."}, "tax_rate": {"type": ["number", "string"], "maxLength": 24, "description": "Tax percent on the line, e.g. 19. Default 0."}}}}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"EUR\". Default: the supplier's."}, "expected_on": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null."}, "location": {"type": "string", "maxLength": 120}, "notes": {"type": "string", "maxLength": 5000}, "mark_sent": {"type": "boolean", "default": false}}, "required": ["order"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_send_order": {"post": {"operationId": "purchasing_send_order", "summary": "Email a purchase order", "description": "Email an order to the supplier in the business's name, with a link to its PDF. A draft takes the next number first (PO-0001 on, without gaps), its PDF is made and kept in the file store, and it no longer changes; a failed email numbers nothing. An order already sent is emailed again (to `to`, if given). Needs the business's name for documents (invoices_set_profile legal_name) and, for anyone outside the business, a paid account. To record an order as sent without emailing it, use purchasing_update_order with mark_sent ($0.01). Costs $0.10 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"order": {"type": "string", "maxLength": 40, "minLength": 1, "description": "The order_id, or the order's number like \"PO-0007\"."}, "to": {"type": "string", "maxLength": 254, "description": "Send to this address instead of the supplier's email."}, "message": {"type": "string", "maxLength": 2000, "description": "A short note in the email, e.g. \"Please deliver to the back door.\""}}, "required": ["order"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_receive": {"post": {"operationId": "purchasing_receive", "summary": "Receive a delivery", "description": "Record what arrived on a sent order: lines [{line, quantity}] (line numbers as the order lists them), or all: true for everything still to come. Lines with a SKU come into Inventory as receive moves at the ordered unit cost, at the order's location (or location); when the order's currency is not the item's, give that line's unit_cost in the item's currency. More than ordered is refused (take the extra in with inventory_move). All lines or none. The order becomes partial, or received when nothing is left to come. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"order": {"type": "string", "maxLength": 40, "minLength": 1, "description": "The order_id, or the order's number like \"PO-0007\"."}, "lines": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["line", "quantity"], "properties": {"line": {"type": "integer", "minimum": 1, "maximum": 200}, "quantity": {"type": ["number", "string"], "maxLength": 24}, "unit_cost": {"type": ["number", "string"], "maxLength": 24, "description": "Only when the item is valued in another currency: the cost of one in that currency."}}}}, "all": {"type": "boolean", "default": false, "description": "Receive everything still to come."}, "location": {"type": "string", "maxLength": 120, "description": "Where the stock goes, instead of the order's location."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "When it arrived. Default today."}}, "required": ["order"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_close_order": {"post": {"operationId": "purchasing_close_order", "summary": "Close or cancel an order", "description": "Close an order that was sent: stop waiting for the rest (what came in stays, and can still be billed). Or cancel it (cancel: true) while nothing came in and it has no bills; a cancelled draft never had a number. Closed and cancelled orders are final. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"order": {"type": "string", "maxLength": 40, "minLength": 1, "description": "The order_id, or the order's number like \"PO-0007\"."}, "cancel": {"type": "boolean", "default": false}, "reason": {"type": "string", "maxLength": 300}}, "required": ["order"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_list_orders": {"post": {"operationId": "purchasing_list_orders", "summary": "List or read purchase orders", "description": "With order: that order in full (lines with what was received and billed, its PDF link, its bills and history). Otherwise orders newest first, filtered by status (draft, sent, partial, received, closed, cancelled; open means sent or partial), supplier, or created from-to. Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"order": {"type": "string", "maxLength": 40, "minLength": 1, "description": "The order_id, or the order's number like \"PO-0007\"."}, "status": {"type": "string", "enum": ["draft", "sent", "partial", "received", "closed", "cancelled", "open"]}, "supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_create_bill": {"post": {"operationId": "purchasing_create_bill", "summary": "Record a supplier bill", "description": "Record a bill a supplier sent, with their reference (their invoice number; the same reference from the same supplier is refused twice). Either its own lines (supplier and lines: each to its book account, default the supplier's; a sku line to the inventory account), or from an order (order, quantities: \"received\" (default) or \"ordered\"): what is not billed yet, at the order's costs. It is due due_date, default the issue date plus the supplier's terms. Attach its PDF from the file store with file_id; reading the PDF is your work. A carrier's or the customs office's bill marks the import VAT it passes on with import_vat on its line. When the account keeps books, it is posted to them. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "order": {"type": "string", "maxLength": 40, "minLength": 1, "description": "The order_id, or the order's number like \"PO-0007\"."}, "quantities": {"type": "string", "enum": ["received", "ordered"], "default": "received"}, "lines": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["unit_cost"], "properties": {"sku": {"type": "string", "maxLength": 64, "description": "An Inventory item's SKU: received stock comes into Inventory. Its name is the default description."}, "description": {"type": "string", "maxLength": 2000, "description": "What is bought. Lines after the first print smaller, underneath."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Default 1. Up to 6 decimals."}, "unit_cost": {"type": ["number", "string"], "maxLength": 24, "description": "The cost of one before tax; negative for a credit line (a discount)."}, "tax_rate": {"type": ["number", "string"], "maxLength": 24, "description": "Tax percent on the line, e.g. 19. Default 0."}, "account": {"type": "string", "maxLength": 20, "description": "The book account the line goes to, e.g. \"6600\". Default: the supplier's. A sku line goes to the inventory account."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "With books: tracking options, e.g. {\"Department\": \"Warehouse\"}."}, "import_vat": {"type": "boolean", "description": "The line is import VAT from the customs notice, passed on by the carrier or billed by the customs office: unit_cost is the VAT itself, reclaimed whole (Germany's box 62, the UK's box 4), never a cost. No sku, account, tax_rate or tracking."}}}}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"EUR\". Default: the supplier's."}, "reference": {"type": "string", "maxLength": 60}, "issue_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "due_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "account": {"type": "string", "maxLength": 20, "description": "With order: the book account for its lines without a SKU. Default: the supplier's."}, "file_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A file_id from the file store."}, "notes": {"type": "string", "maxLength": 5000}, "tax_treatment": {"type": "string", "enum": ["", "reverse_charge", "eu_goods"], "description": "reverse_charge: the supplier's invoice has no VAT because the business owes it (services from abroad, a reverse-charge trade at home); eu_goods: goods bought from another EU country. The lines' tax_rate is the rate owed; the VAT is owed and reclaimed at once."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_update_bill": {"post": {"operationId": "purchasing_update_bill", "summary": "Change a bill's file, notes or due date", "description": "What can change on a recorded bill: its PDF while it has none (file_id), its notes, and its due date while it is owed. The PDF it has stays, as a received invoice is kept as it came, and its amounts never change: for either, void it and record it again. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"bill_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The bill_id purchasing_create_bill returned."}, "file_id": {"type": ["string", "null"], "minLength": 36, "maxLength": 36}, "notes": {"type": "string", "maxLength": 5000}, "due_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}}, "required": ["bill_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_pay_bill": {"post": {"operationId": "purchasing_pay_bill", "summary": "Record a bill payment", "description": "Record money paid on a bill: amount (at most the balance, unless keep_excess keeps the rest as a credit with the supplier for purchasing_use_credit), date, method and reference. It becomes partially_paid, or paid when nothing is left. A negative amount records money back from the supplier. When the account keeps books, the payment is posted (accounts payable against the bank, with any exchange difference). books_match_bank_lines can do this from a bank line too. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"bill_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The bill_id purchasing_create_bill returned."}, "amount": {"type": ["number", "string"], "maxLength": 24, "description": "In the bill's currency, e.g. \"250.00\". Negative for a refund."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "When it was paid. Default today."}, "method": {"type": "string", "enum": ["bank_transfer", "card", "cash", "check", "online", "other"], "default": "bank_transfer"}, "reference": {"type": "string", "maxLength": 120}, "note": {"type": "string", "maxLength": 500}, "keep_excess": {"type": "boolean", "default": false, "description": "Paid more than the balance: keep the rest as a credit with the supplier."}}, "required": ["bill_id", "amount"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_record_prepayment": {"post": {"operationId": "purchasing_record_prepayment", "summary": "Record a prepayment to a supplier", "description": "Record money the business paid a supplier before their bill, like a deposit, as Xero's prepayments: it waits as a credit with the supplier (SC-0001 on) until purchasing_use_credit puts it on their bill or records it coming back. With tax_rate it carries the VAT on the supplier's advance invoice, reclaimable once paid; using it on the bill takes that VAT back off. With books kept it is posted at once: Prepayments to suppliers (1450, made when missing) and the tax to reclaim against the bank. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "amount": {"type": ["number", "string"], "maxLength": 24, "description": "What was paid, tax included."}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"EUR\". Default: the supplier's."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "When it was paid. Default today."}, "method": {"type": "string", "enum": ["bank_transfer", "card", "cash", "check", "online", "other"], "default": "bank_transfer"}, "reference": {"type": "string", "maxLength": 120}, "note": {"type": "string", "maxLength": 500}, "tax_rate": {"type": "number", "minimum": 0, "maximum": 100, "description": "The VAT in it, in percent, e.g. 19. Default none."}}, "required": ["supplier", "amount"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_use_credit": {"post": {"operationId": "purchasing_use_credit", "summary": "Use a supplier credit", "description": "Put a credit with a supplier (a prepayment or an overpayment) on one of their open bills, like Xero's allocate credit: bill_id, and amount (default all it can: what is left on the credit or the bill, the smaller); the bill records it as a payment with method credit, and its share of the credit's VAT comes back off. Or refund: true records what is left (or amount) coming back from the supplier, with date and method; or void: true takes back a prepayment recorded by mistake while none of it is used. Same supplier and currency only. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"credit": {"type": "string", "maxLength": 20, "minLength": 1, "description": "The credit's number, like \"SC-0001\" (purchasing_list_credits)."}, "bill_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The bill_id purchasing_create_bill returned."}, "amount": {"type": ["number", "string"], "maxLength": 24}, "refund": {"type": "boolean", "default": false}, "void": {"type": "boolean", "default": false}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "method": {"type": "string", "enum": ["bank_transfer", "card", "cash", "check", "online", "other"], "default": "bank_transfer"}, "reference": {"type": "string", "maxLength": 120}}, "required": ["credit"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_list_credits": {"post": {"operationId": "purchasing_list_credits", "summary": "List supplier credits", "description": "Credits with suppliers, prepayments and overpayments, newest first: what each was, what is left, its VAT and how it was used or came back. Filter by supplier, or status (open, used, refunded, void, all; default open). Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "status": {"type": "string", "enum": ["open", "used", "refunded", "void", "all"], "default": "open"}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_save_repeating_bill": {"post": {"operationId": "purchasing_save_repeating_bill", "summary": "Repeat a bill", "description": "A supplier's bill recorded again every so many weeks, months or years, like Xero's repeating bills: rent, a lease, a subscription. The supplier and lines as for purchasing_create_bill, every and unit, the start date, and an end_date or a number of times; each bill falls due payment_terms_days after its date (default the supplier's terms). Descriptions, notes and the reference may hold [Month], [Year], [Quarter] or [Week], with an offset like [Month+1]; a reference needs one, as a supplier's reference is recorded once. Conecto's worker records each bill as this key, at what purchasing_create_bill costs, and one an approval rule holds waits for that person. Change one by repeating_id: only what you pass changes; status paused stops it, active resumes it (dates it missed are skipped). Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"repeating_id": {"type": "integer", "minimum": 1, "description": "From purchasing_list_repeating_bills."}, "name": {"type": "string", "maxLength": 120, "description": "Your own label, e.g. \"Warehouse rent\"."}, "supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "lines": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["unit_cost"], "properties": {"sku": {"type": "string", "maxLength": 64, "description": "An Inventory item's SKU: received stock comes into Inventory. Its name is the default description."}, "description": {"type": "string", "maxLength": 2000, "description": "What is bought. Lines after the first print smaller, underneath."}, "quantity": {"type": ["number", "string"], "maxLength": 24, "description": "Default 1. Up to 6 decimals."}, "unit_cost": {"type": ["number", "string"], "maxLength": 24, "description": "The cost of one before tax; negative for a credit line (a discount)."}, "tax_rate": {"type": ["number", "string"], "maxLength": 24, "description": "Tax percent on the line, e.g. 19. Default 0."}, "account": {"type": "string", "maxLength": 20, "description": "The book account the line goes to, e.g. \"6600\". Default: the supplier's. A sku line goes to the inventory account."}, "tracking": {"type": "object", "maxProperties": 2, "additionalProperties": {"type": "string", "maxLength": 60}, "description": "With books: tracking options, e.g. {\"Department\": \"Warehouse\"}."}, "import_vat": {"type": "boolean", "description": "The line is import VAT from the customs notice, passed on by the carrier or billed by the customs office: unit_cost is the VAT itself, reclaimed whole (Germany's box 62, the UK's box 4), never a cost. No sku, account, tax_rate or tracking."}}}}, "currency": {"type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217, e.g. \"EUR\". Default: the supplier's."}, "reference": {"type": "string", "maxLength": 60, "description": "e.g. \"Rent [Month] [Year]\"."}, "notes": {"type": "string", "maxLength": 5000}, "tax_treatment": {"type": "string", "enum": ["", "reverse_charge", "eu_goods"], "description": "reverse_charge: the supplier's invoice has no VAT because the business owes it (services from abroad, a reverse-charge trade at home); eu_goods: goods bought from another EU country. The lines' tax_rate is the rate owed; the VAT is owed and reclaimed at once."}, "payment_terms_days": {"type": "integer", "minimum": 0, "maximum": 365, "description": "Each bill falls due this long after its date. Default: the supplier's terms."}, "every": {"type": "integer", "minimum": 1, "maximum": 52, "description": "Default 1."}, "unit": {"type": "string", "enum": ["week", "month", "year"]}, "start": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The first bill's date, today or later. Monthly and yearly bills keep to its day of the month."}, "end_date": {"type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$", "description": "No bill after this date. \"\" for none."}, "times": {"type": "integer", "minimum": 1, "maximum": 1000, "description": "How many bills in all."}, "status": {"type": "string", "enum": ["active", "paused"]}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_list_repeating_bills": {"post": {"operationId": "purchasing_list_repeating_bills", "summary": "List repeating bills", "description": "The repeating bills: whose, their lines, how often, the next dates, how many were recorded and the last one, and why one waits or is paused. Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["active", "paused", "ended"]}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_delete_repeating_bill": {"post": {"operationId": "purchasing_delete_repeating_bill", "summary": "Stop a repeating bill", "description": "Stop a repeating bill for good. The bills it recorded stay as they are. Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"repeating_id": {"type": "integer", "minimum": 1, "description": "From purchasing_list_repeating_bills."}}, "required": ["repeating_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_pay_bills": {"post": {"operationId": "purchasing_pay_bills", "summary": "Pay bills in a batch", "description": "Pay several bills at once from one bank account, like Xero's batch payments: bills (each with an optional amount, else its balance), or every unpaid bill due on or before due_before (one supplier's with supplier). One payment per bill on date, posted to the books from bank_account (default: where bank transfers land). sepa_file: true adds the SEPA credit transfer file (pain.001) to upload to the bank, paying each supplier's IBAN with the bill's reference; the bank books the batch as one line, which books_bank_lines then suggests matching to all its payments at once. All of it is paid or none. Costs $0.01 per bill paid; nothing if none are found.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"bills": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["bill_id"], "properties": {"bill_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The bill_id purchasing_create_bill returned."}, "amount": {"type": ["number", "string"], "maxLength": 24, "description": "Part of it. Default: what is still owed."}}}}, "due_before": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Every unpaid bill due on or before this day, instead of bills."}, "supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The day it is paid. Default today."}, "bank_account": {"type": "string", "maxLength": 20, "description": "The books' bank account it is paid from, by code."}, "sepa_file": {"type": "boolean", "default": false}, "from_iban": {"type": "string", "maxLength": 42, "description": "The IBAN it is paid from, when not the bank account's own."}, "from_bic": {"type": "string", "maxLength": 11}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_set_planned_date": {"post": {"operationId": "purchasing_set_planned_date", "summary": "Plan when to pay a bill", "description": "The day the business means to pay a bill that is not paid yet, like Xero's planned date: the cash flow forecast (books_report cash_forecast) counts the payment on that day, even for a bill already overdue, which it otherwise leaves out. null clears it. Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"bill_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The bill_id purchasing_create_bill returned."}, "date": {"type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, or null."}}, "required": ["bill_id", "date"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_void_bill": {"post": {"operationId": "purchasing_void_bill", "summary": "Void a bill", "description": "Void a bill entered by mistake (or replaced): refused while money is recorded as paid on it (record the refund first). The quantities it billed on its order can be billed again; the books reverse it. Costs $0.01 per call; nothing if it fails.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"bill_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The bill_id purchasing_create_bill returned."}, "reason": {"type": "string", "maxLength": 500}}, "required": ["bill_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_list_bills": {"post": {"operationId": "purchasing_list_bills", "summary": "List or read bills", "description": "With bill_id: that bill in full (lines, payments, its PDF link, the books entry it posted). Otherwise bills by due date, filtered by status (open, partially_paid, paid, void; unpaid means open or partly paid; overdue means unpaid and past due), supplier, order, due on or before a date, or issued from-to. Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"bill_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The bill_id purchasing_create_bill returned."}, "status": {"type": "string", "enum": ["open", "partially_paid", "paid", "void", "unpaid", "overdue"]}, "supplier": {"type": ["integer", "string"], "minimum": 1, "maximum": 9223372036854775807, "minLength": 1, "maxLength": 200, "description": "A supplier_id, or the supplier's name."}, "order": {"type": "string", "maxLength": 40, "minLength": 1, "description": "The order_id, or the order's number like \"PO-0007\"."}, "due_before": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}, "offset": {"type": "integer", "minimum": 0, "default": 0}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/purchasing_report": {"post": {"operationId": "purchasing_report", "summary": "Run a purchasing report", "description": "aged_payables: what is owed to each supplier on as_of (default today), by how long past due: current (not due yet), 1-30, 31-60, 61-90 and over 90 days, per currency. spend: what each supplier billed from-to (by issue date; default this month) and what was paid to them in it. To show a person, put it in a view (view_show). Free.", "tags": ["purchasing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"report": {"type": "string", "enum": ["aged_payables", "spend"]}, "as_of": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "from": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}, "to": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD"}}, "required": ["report"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_networks": {"post": {"operationId": "social_networks", "summary": "List the social networks", "description": "Every network Conecto can post to and how each connects: link (OAuth: you get a link for the owner to open), login (you pass the account's login or key to social_connect; how says which) or telegram. enabled says whether it is switched on for Conecto yet; the others wait for the network's app review. Telegram, Discord and Slack also connect with the business's own bot or webhook (own: the fields for social_connect and how to get them), which needs no app review, so it works enabled or not. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_connect": {"post": {"operationId": "social_connect", "summary": "Connect a social account", "description": "Connect one of the business's own accounts as a channel. For a link network (LinkedIn, Mastodon, Discord, Slack, Facebook, Instagram...) you get connect_url: hand it to the owner, who approves Conecto on the network and sees \"Channel connected\"; social.channel_connected tells you, and social_channels lists it (the link works for an hour). For a login network pass the login: Bluesky (username and an app password), WordPress (service, username, application password), Medium, Dev.to and Hashnode (api_key), Lemmy (username, password), Nostr (password: the private key); it connects at once and the login is never kept by Conecto. service is a public https:// address. Telegram: call without code to get one; the owner adds Conecto's bot to the channel as an admin and posts \"/connect <code>\" there; then call with code. Only channels (groups can't be), and a channel connected to another Conecto account stays theirs. Or with the business's own bot: Telegram with bot_token (from @BotFather) and chat (@channel or the chat's number), the bot an admin of the channel or a member of the group, and posts come from their bot; Discord or Slack with webhook_url (a channel webhook), and posts carry its name and picture. Those are checked with the network at once, kept encrypted, and their channel_ids start with own_. Connecting again refreshes a channel that needs it. Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"network": {"type": "string", "enum": ["bluesky", "devto", "discord", "dribbble", "facebook", "gmb", "hashnode", "instagram", "instagram-standalone", "kick", "lemmy", "linkedin", "linkedin-page", "mastodon", "medium", "mewe", "nostr", "pinterest", "reddit", "slack", "telegram", "threads", "tiktok", "tiktok-business", "tumblr", "twitch", "vk", "whop", "wordpress", "x", "youtube", "listmonk", "moltbook", "skool", "wrapcast"]}, "service": {"type": "string", "maxLength": 300, "description": "The server or site address, for networks that have one."}, "username": {"type": "string", "maxLength": 200}, "password": {"type": "string", "maxLength": 500, "writeOnly": true}, "api_key": {"type": "string", "maxLength": 500, "writeOnly": true}, "code": {"type": "string", "pattern": "^[0-9a-f]{12}$", "description": "Telegram: the code social_connect gave, once the owner posted it."}, "bot_token": {"type": "string", "maxLength": 100, "description": "Telegram: the business's own bot's token, from @BotFather.", "writeOnly": true}, "chat": {"type": "string", "maxLength": 40, "description": "Telegram, with bot_token: the channel (@name) or the chat's number."}, "webhook_url": {"type": "string", "maxLength": 500, "description": "Discord or Slack: a channel's webhook address.", "writeOnly": true}}, "required": ["network"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_channels": {"post": {"operationId": "social_channels", "summary": "List the connected channels", "description": "The business's connected social accounts (channels), with their network, name and profile. Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_disconnect": {"post": {"operationId": "social_disconnect", "summary": "Disconnect a channel", "description": "Remove a channel from the business's social workspace. Its waiting posts are deleted with it: the ones whose time hadn't come are refunded, posts that went out stay on the network. Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channel_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A channel_id from social_channels."}}, "required": ["channel_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_channel_rules": {"post": {"operationId": "social_channel_rules", "summary": "Read a channel's rules", "description": "What a channel's network accepts: its rules (media counts, lengths), max_length, the settings a post may or must carry (a JSON schema, e.g. Discord's channel, Medium's title) and its lookups (for social_channel_lookup). Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channel_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A channel_id from social_channels."}}, "required": ["channel_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_channel_lookup": {"post": {"operationId": "social_channel_lookup", "summary": "Look something up on a channel", "description": "Run one of a channel's lookups (social_channel_rules lists them), e.g. \"channels\" on Discord and Slack for the channel ids posts need, \"boards\" on Pinterest, \"publications\" on Medium. Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channel_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A channel_id from social_channels."}, "method": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$"}, "data": {"type": "object", "maxProperties": 10, "additionalProperties": {"type": ["string", "number", "boolean"], "maxLength": 300}}}, "required": ["channel_id", "method"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_post": {"post": {"operationId": "social_post", "summary": "Post to social channels", "description": "Post now, or at when (ISO 8601 with its offset, up to a year ahead), to one or several channels. text is the post; thread adds follow-up posts; media are file_ids from the store, uploaded to Postiz by Conecto. per_channel gives one channel its own text, media, thread or settings: some networks need settings (Discord and Slack a channel id, Medium, Dev.to, Hashnode and WordPress a title, Instagram a post_type; social_channel_rules says). Postiz checks every channel first and takes all or none. TikTok (one MP4 video, or pictures; settings.title is a photo post's title) requires its owner to confirm each post: a TikTok channel comes back under waiting_for_owner. Ask them in your chat (social_post_check gives what to show and ask) and pass their answer to social_confirm_post, or give them its confirm_url to do it on a page. Then social.post_confirmed and social.post_published follow, or social.post_declined when they say no or 3 days pass (a day past when, if later); it is refunded. With settings {\"content_posting_method\": \"UPLOAD\"} it goes at once as a draft to their TikTok inbox instead, to finish in TikTok's app within 24 hours. $0.02 per channel, refunded when a post fails or is deleted before it goes out; social.post_published and social.post_failed tell you how each went. Costs $0.02 per channel posted to; nothing if none are found.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channels": {"type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A channel_id from social_channels."}}, "text": {"type": "string", "minLength": 1, "maxLength": 100000}, "media": {"type": "array", "maxItems": 10, "uniqueItems": true, "items": {"type": "string", "minLength": 36, "maxLength": 36}, "description": "file_ids from the store: images (JPEG, PNG, GIF, WebP, AVIF; up to 10 MB) or MP4 videos."}, "thread": {"type": "array", "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 100000}, "description": "Follow-up posts after the first: a thread on X, Bluesky, Mastodon and Threads, comments on the others."}, "when": {"type": "string", "maxLength": 40, "description": "e.g. 2026-10-20T09:00:00-07:00; left out: now."}, "per_channel": {"type": "object", "maxProperties": 20, "propertyNames": {"pattern": "^[A-Za-z0-9_-]{1,64}$"}, "additionalProperties": {"type": "object", "additionalProperties": false, "properties": {"text": {"type": "string", "minLength": 1, "maxLength": 100000}, "media": {"type": "array", "maxItems": 10, "uniqueItems": true, "items": {"type": "string", "minLength": 36, "maxLength": 36}, "description": "file_ids from the store: images (JPEG, PNG, GIF, WebP, AVIF; up to 10 MB) or MP4 videos."}, "thread": {"type": "array", "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 100000}, "description": "Follow-up posts after the first: a thread on X, Bluesky, Mastodon and Threads, comments on the others."}, "settings": {"type": "object", "maxProperties": 30, "additionalProperties": true, "description": "The network's own settings for this post, as social_channel_rules describes them, e.g. {\"channel\": \"<id>\"} on Discord and Slack, {\"title\": \"...\"} on Medium, Dev.to, Hashnode and WordPress, {\"post_type\": \"post\"} on Instagram."}}}}}, "required": ["channels"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_post_check": {"post": {"operationId": "social_post_check", "summary": "Read a post waiting for its owner", "description": "A TikTok post social_post holds for its owner, with what to show them and ask in your chat, read from TikTok just now: the account it goes to, who_can_see (the audiences this account allows), allow (the interactions to ask about, or marked off in their TikTok settings), the disclosure labels, the declaration to show word for word and ask_owner, how to ask. can_post_now false says why it can't go now: TikTok won't take a post from the account, or the video is longer than the account may post. Then social_confirm_post with their answer. Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"check_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A check_id from social_post's waiting_for_owner."}}, "required": ["check_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_confirm_post": {"post": {"operationId": "social_confirm_post", "summary": "Answer for the owner of a post", "description": "The owner's answer from your chat to a TikTok post waiting for them, after you showed them what social_post_check gave. post true sends it with their choices, now or at its time; post false drops it and refunds it. who_can_see is the value they picked from who_can_see; the allow_* switches and the disclosure stay off unless they said yes; caption and title only when they changed them. owner_said is their reply in their own words, kept as the record of their answer. Never choose for them: TikTok requires that they do. Free: social_post paid for it. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"check_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "A check_id from social_post's waiting_for_owner."}, "post": {"type": "boolean", "description": "true: post it with their choices; false: they said no."}, "owner_said": {"type": "string", "minLength": 2, "maxLength": 500, "description": "The owner's reply, in their own words."}, "who_can_see": {"type": "string", "enum": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]}, "allow_comments": {"type": "boolean", "default": false}, "allow_duet": {"type": "boolean", "default": false, "description": "Videos only."}, "allow_stitch": {"type": "boolean", "default": false, "description": "Videos only."}, "promotes_own_brand": {"type": "boolean", "default": false}, "branded_content": {"type": "boolean", "default": false}, "caption": {"type": "string", "maxLength": 2000}, "title": {"type": "string", "maxLength": 90, "description": "Photo posts only."}}, "required": ["check_id", "post", "owner_said"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_posts": {"post": {"operationId": "social_posts", "summary": "List posts", "description": "Posts in a time window (default: the last 7 days and the next 30), newest last, each with its channel, status (scheduled, published, failed), link once published and Postiz's reason when it failed. Up to 92 days at a time. Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"date_from": {"type": "string", "maxLength": 40}, "date_to": {"type": "string", "maxLength": 40}, "channel_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A channel_id from social_channels."}, "status": {"type": "string", "enum": ["scheduled", "published", "failed"]}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_delete_post": {"post": {"operationId": "social_delete_post", "summary": "Delete a post", "description": "Delete a post (with its thread) from the business's social workspace. One still waiting for its time never goes out, and its $0.02 is refunded; one whose time came may have gone out, so it is not; one that went out stays on the network (delete it there). Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"post_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A post_id from social_post or social_posts."}}, "required": ["post_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_analytics": {"post": {"operationId": "social_analytics", "summary": "Read social numbers", "description": "How a channel did over the last 7, 30 or 90 days (channel_id), or one published post (post_id): each metric the network reports (followers, impressions, likes...) by day, with its change. Networks report different things, some nothing. Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channel_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A channel_id from social_channels."}, "post_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A post_id from social_post or social_posts."}, "days": {"type": "integer", "enum": [7, 30, 90], "default": 7}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/social_find_slot": {"post": {"operationId": "social_find_slot", "summary": "Find a free time to post", "description": "The next free time slot of a channel, from the posting times Postiz keeps for it and what is already scheduled: pass it as when to social_post. Free. Free.", "tags": ["social"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"channel_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "A channel_id from social_channels."}}, "required": ["channel_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/whistleblowing_create_channel": {"post": {"operationId": "whistleblowing_create_channel", "summary": "Open a whistleblowing channel", "description": "The channel every employer with 50 or more staff must run (EU Directive 2019/1937): a page where anyone reports a concern, anonymously if they like, and gets a case number and code to follow up. Only the named handlers read reports; you see their case numbers, dates and deadlines only. The handlers get an email now and whenever a report arrives. Only the owner can change the handlers later. $20.00 for the first month, then $20 a month from the balance. Costs $20.00 per call; nothing if it fails.", "tags": ["whistleblowing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 120}, "handlers": {"type": "array", "minItems": 1, "maxItems": 10, "items": {"type": "string", "maxLength": 254}, "description": "The people who read and answer reports: impartial, named, 1 to 10."}, "categories": {"type": "array", "maxItems": 12, "items": {"type": "string", "minLength": 1, "maxLength": 80}}, "intro": {"type": "string", "maxLength": 20000, "description": "Markdown above the form: what can be reported and how it is handled."}, "external_info": {"type": "string", "maxLength": 2000, "description": "Where else people may report: the competent authority."}}, "required": ["name", "handlers"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/whistleblowing_update_channel": {"post": {"operationId": "whistleblowing_update_channel", "summary": "Change the whistleblowing channel", "description": "Change the channel's name, categories, intro or where else people may report. The handlers are the owner's to change, on their account page. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["whistleblowing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 120}, "categories": {"type": "array", "maxItems": 12, "items": {"type": "string", "minLength": 1, "maxLength": 80}}, "intro": {"type": "string", "maxLength": 20000}, "external_info": {"type": "string", "maxLength": 2000}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/whistleblowing_list_reports": {"post": {"operationId": "whistleblowing_list_reports", "summary": "List reports (metadata only)", "description": "The channel's reports, newest first, without what they say or who sent them: case number, category, status, when it came, when feedback is due and whether it is overdue. To remind the handlers, or to report on the channel. Free.", "tags": ["whistleblowing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["received", "in_progress", "closed", "open"]}, "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/whistleblowing_stats": {"post": {"operationId": "whistleblowing_stats", "summary": "Whistleblowing statistics", "description": "Counts of the channel's reports by status and category, how many got feedback in time, and the average days to first feedback, for a year or all time. No content. Free.", "tags": ["whistleblowing"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"year": {"type": "integer", "minimum": 2020, "maximum": 2100}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_connect": {"post": {"operationId": "directory_connect", "summary": "Connect the directory", "description": "Connect the company's Microsoft Entra ID or Okta. Entra ID: tenant_id, client_id and the client secret of an app registration with User.ReadWrite.All and GroupMember.ReadWrite.All (and User.EnableDisableAccount.All), consented by the tenant's admin. Okta: org_url and an admin's API token. The connection is checked by reading one person. Suspensions then wait for the owner's approval by default. Costs $0.001 per call; nothing if it fails.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"provider": {"type": "string", "enum": ["entra", "okta"]}, "tenant_id": {"type": "string", "maxLength": 120}, "client_id": {"type": "string", "maxLength": 120}, "org_url": {"type": "string", "maxLength": 200}, "secret": {"type": "string", "minLength": 8, "maxLength": 2000, "description": "The Entra client secret or the Okta API token. Never shown again.", "writeOnly": true}}, "required": ["provider", "secret"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_disconnect": {"post": {"operationId": "directory_disconnect", "summary": "Disconnect the directory", "description": "Forget the directory's credentials. Nothing in the directory changes. Free.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_list_users": {"post": {"operationId": "directory_list_users", "summary": "List people in the directory", "description": "People in the company's directory, with their id, name, email, title, department and whether they can sign in. query searches names and emails. Free.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "maxLength": 100}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_get_user": {"post": {"operationId": "directory_get_user", "summary": "Get a person from the directory", "description": "One person by id or email: name, email, title, department and whether they can sign in. Free.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "minLength": 1, "maxLength": 200, "description": "The person's id in the directory, or their email."}}, "required": ["person"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_list_groups": {"post": {"operationId": "directory_list_groups", "summary": "List groups", "description": "The directory's groups, with their id, name and description (which apps and teams they open). Free.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "maxLength": 100}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 100}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_create_user": {"post": {"operationId": "directory_create_user", "summary": "Create an account for a joiner", "description": "Open a joiner's account in the directory, with their title, department and groups. Okta emails them their own activation link; in Entra ID they start with the company's usual way in (a Temporary Access Pass or a reset). Conecto never sees a password. Costs $0.25 per call; nothing if it fails.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"first_name": {"type": "string", "minLength": 1, "maxLength": 80}, "last_name": {"type": "string", "minLength": 1, "maxLength": 80}, "email": {"type": "string", "minLength": 3, "maxLength": 200, "description": "Their work address and sign-in name."}, "title": {"type": "string", "maxLength": 120}, "department": {"type": "string", "maxLength": 120}, "groups": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 120}, "description": "Group ids to add them to."}}, "required": ["first_name", "last_name", "email"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_update_user": {"post": {"operationId": "directory_update_user", "summary": "Update a person in the directory", "description": "Change a person's title, department or manager in the directory, as when they move team. Costs $0.01 per call; nothing if it fails.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "minLength": 1, "maxLength": 200, "description": "The person's id in the directory, or their email."}, "title": {"type": "string", "maxLength": 120}, "department": {"type": "string", "maxLength": 120}, "manager": {"type": "string", "maxLength": 200, "description": "The manager's id or email."}}, "required": ["person"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_set_groups": {"post": {"operationId": "directory_set_groups", "summary": "Change a person's groups", "description": "Add a person to groups and take them out of others (the apps and teams those groups open). Costs $0.01 per call; nothing if it fails.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "minLength": 1, "maxLength": 200, "description": "The person's id in the directory, or their email."}, "add": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 120}}, "remove": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 120}}}, "required": ["person"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_suspend_user": {"post": {"operationId": "directory_suspend_user", "summary": "Suspend a leaver", "description": "Block a person's sign-in and end every session they have, as when they leave; their own assistants on this Conecto account stop too. Check who it is with directory_get_user first. On accounts with an owner it waits for the owner's approval by default (an approval rule made on connecting). directory_restore_user undoes it. Costs $0.25 per call; nothing if it fails.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "minLength": 1, "maxLength": 200, "description": "The person's id in the directory, or their email."}}, "required": ["person"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_restore_user": {"post": {"operationId": "directory_restore_user", "summary": "Restore a suspended person", "description": "Let a suspended person sign in again. Costs $0.001 per call; nothing if it fails.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"person": {"type": "string", "minLength": 1, "maxLength": 200, "description": "The person's id in the directory, or their email."}}, "required": ["person"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/directory_sync_from_hr": {"post": {"operationId": "directory_sync_from_hr", "summary": "Bring the directory in line with HR", "description": "Compare HR's people (hr area) with the directory by work email and set titles and departments (and managers, with include_managers) as HR has them. With suspend_leavers, people HR says have left are suspended too. dry_run (the default) only shows the plan. Costs $0.01 per call; nothing if it fails.", "tags": ["directory"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"dry_run": {"type": "boolean", "default": true}, "suspend_leavers": {"type": "boolean", "default": false}, "include_managers": {"type": "boolean", "default": false}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/connect_add": {"post": {"operationId": "connect_add", "summary": "Connect a system", "description": "Connect one of the company's own systems (an ERP, a ticketing tool, any REST API): its https base address, its credential and the calls the agent may make. The credential is kept encrypted and never shown again. A system behind the company's firewall goes through one of its bridges instead: give `bridge` and `system` (connect_list shows the bridges and the systems each serves) in place of base_url and a credential, which the bridge adds inside the network. On accounts with an owner, writes (POST, PUT, PATCH, DELETE) and changing the allowed calls wait for the owner's approval by default, which shows the exact request. Free. Free.", "tags": ["connect"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 2, "maxLength": 40, "description": "Lowercase letters, digits and dashes, like \"netsuite\" or \"zendesk\"."}, "base_url": {"type": "string", "maxLength": 500}, "auth": {"type": "string", "enum": ["bearer", "header", "basic", "none"], "default": "bearer", "description": "bearer (Authorization: Bearer <secret>), header (the secret in `header`), basic (secret is \"user:password\") or none."}, "header": {"type": "string", "maxLength": 60, "description": "For auth header, like X-API-Key."}, "secret": {"type": "string", "maxLength": 4000, "writeOnly": true}, "allow": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "string", "maxLength": 310}, "description": "The calls it may make: a method and a path pattern each, like \"GET /v1/customers*\" or \"POST /v1/tickets\". * matches anything."}, "description": {"type": "string", "maxLength": 300}, "bridge": {"type": "string", "maxLength": 40, "description": "For a system behind the firewall: the bridge it goes through."}, "system": {"type": "string", "maxLength": 40, "description": "With bridge: the system's name in the bridge's config, like \"sap\"."}}, "required": ["name", "allow"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/connect_list": {"post": {"operationId": "connect_list", "summary": "List connected systems", "description": "The company's connected systems: name, base address, kind of auth and the calls each may make. The credentials are never shown. Free.", "tags": ["connect"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/connect_preview": {"post": {"operationId": "connect_preview", "summary": "Preview a call to a connected system", "description": "Exactly what connect_call would send, without sending it: the method, the full address with its query, the headers (the credential hidden) and the body. It runs every check a call does, so a refused call is refused here too. Show it to a person before a change. Free. Free.", "tags": ["connect"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"connection": {"type": "string", "minLength": 2, "maxLength": 40, "description": "The connection's name."}, "method": {"type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]}, "path": {"type": "string", "minLength": 1, "maxLength": 500}, "query": {"type": "object", "maxProperties": 30, "additionalProperties": {"type": ["string", "number", "boolean"]}}, "body": {"description": "A JSON body for POST, PUT and PATCH."}}, "required": ["connection", "method", "path"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/connect_call": {"post": {"operationId": "connect_call", "summary": "Call a connected system", "description": "Send one request to a connected system, inside its allowed calls: method, path (after the base address), query and a JSON body. Answers with the status, the content type and the body (JSON when it is JSON), up to 1 MB. Writes wait for the owner's approval by default (connect_preview shows what would be sent). A call to a system behind the firewall goes to the company's bridge: it answers 202 with a call_id, and account_get_call has the answer once the bridge sends it, usually within seconds. The first 10,000 calls a month are free, then $0.0003 for each started 10 seconds the system takes to answer, at most $0.0012; a call through a bridge is $0.0003. Costs $0.0003 for each started 10 seconds the system takes to answer ($0.0003 when it answers within 10 seconds; at most $0.0012 a call); nothing if it fails.", "tags": ["connect"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"connection": {"type": "string", "minLength": 2, "maxLength": 40, "description": "The connection's name."}, "method": {"type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]}, "path": {"type": "string", "minLength": 1, "maxLength": 500}, "query": {"type": "object", "maxProperties": 30, "additionalProperties": {"type": ["string", "number", "boolean"]}}, "body": {"description": "A JSON body for POST, PUT and PATCH."}}, "required": ["connection", "method", "path"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/connect_set_rules": {"post": {"operationId": "connect_set_rules", "summary": "Change a system's allowed calls", "description": "Replace the calls a connection may make. On accounts with an owner it waits for the owner's approval by default, so a key can't widen its own reach. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["connect"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"connection": {"type": "string", "minLength": 2, "maxLength": 40, "description": "The connection's name."}, "allow": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "string", "maxLength": 310}, "description": "The calls it may make: a method and a path pattern each, like \"GET /v1/customers*\" or \"POST /v1/tickets\". * matches anything."}}, "required": ["connection", "allow"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/connect_remove": {"post": {"operationId": "connect_remove", "summary": "Remove a connection", "description": "Forget a connected system and its credential. Nothing changes in the system itself. Free.", "tags": ["connect"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"connection": {"type": "string", "minLength": 2, "maxLength": 40, "description": "The connection's name."}}, "required": ["connection"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hubspot_connect": {"post": {"operationId": "hubspot_connect", "summary": "Connect HubSpot", "description": "Connect the company's own HubSpot, which stays the source of truth: the agent finds, reads and changes contacts, companies, deals and tickets there. The company makes a private app in HubSpot (Settings, Integrations, Private apps) with the CRM scopes the agent may use, and gives its access token, which is checked before anything is kept. On accounts with an owner, changing an existing record waits for the owner's approval by default. Free. Free.", "tags": ["hubspot"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"token": {"type": "string", "minLength": 10, "maxLength": 500, "description": "The private app's access token. Never shown again.", "writeOnly": true}}, "required": ["token"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hubspot_disconnect": {"post": {"operationId": "hubspot_disconnect", "summary": "Disconnect HubSpot", "description": "Forget the private app's token. Nothing in HubSpot changes. Free.", "tags": ["hubspot"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hubspot_search": {"post": {"operationId": "hubspot_search", "summary": "Search HubSpot", "description": "Contacts, companies, deals or tickets in the company's HubSpot matching words (a name, an email, a deal's name), with their usual properties or the ones named. Free. Free.", "tags": ["hubspot"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contacts", "companies", "deals", "tickets"], "description": "contacts, companies, deals or tickets."}, "query": {"type": "string", "maxLength": 200}, "properties": {"type": "array", "maxItems": 50, "items": {"type": "string", "pattern": "^[a-z0-9_]{1,100}$"}, "description": "The properties to show; the usual ones when left out."}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}, "required": ["object"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hubspot_get": {"post": {"operationId": "hubspot_get", "summary": "Get a HubSpot record", "description": "One contact, company, deal or ticket by its HubSpot id, with its usual properties or the ones named. Free. Free.", "tags": ["hubspot"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contacts", "companies", "deals", "tickets"], "description": "contacts, companies, deals or tickets."}, "id": {"type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[0-9]+$", "description": "The record's HubSpot id."}, "properties": {"type": "array", "maxItems": 50, "items": {"type": "string", "pattern": "^[a-z0-9_]{1,100}$"}, "description": "The properties to show; the usual ones when left out."}}, "required": ["object", "id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hubspot_create": {"post": {"operationId": "hubspot_create", "summary": "Create a HubSpot record", "description": "Make a contact, company, deal or ticket in the company's HubSpot with the properties given. HubSpot refuses a second contact with the same email. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["hubspot"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contacts", "companies", "deals", "tickets"], "description": "contacts, companies, deals or tickets."}, "properties": {"type": "object", "minProperties": 1, "maxProperties": 50, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 5000}, "description": "HubSpot property names and values, like {\"dealstage\": \"closedwon\", \"amount\": 18400}."}}, "required": ["object", "properties"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hubspot_update": {"post": {"operationId": "hubspot_update", "summary": "Change a HubSpot record", "description": "Change properties of a contact, company, deal or ticket in the company's HubSpot. On accounts with an owner it waits for the owner's approval by default, showing each property's value now and after. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["hubspot"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contacts", "companies", "deals", "tickets"], "description": "contacts, companies, deals or tickets."}, "id": {"type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[0-9]+$", "description": "The record's HubSpot id."}, "properties": {"type": "object", "minProperties": 1, "maxProperties": 50, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 5000}, "description": "HubSpot property names and values, like {\"dealstage\": \"closedwon\", \"amount\": 18400}."}}, "required": ["object", "id", "properties"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/hubspot_add_note": {"post": {"operationId": "hubspot_add_note", "summary": "Add a note in HubSpot", "description": "A note on a contact, company, deal or ticket's timeline in HubSpot, where the team sees it: what a customer said on the phone, what was agreed. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["hubspot"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "enum": ["contacts", "companies", "deals", "tickets"], "description": "contacts, companies, deals or tickets."}, "id": {"type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[0-9]+$", "description": "The record's HubSpot id."}, "body": {"type": "string", "minLength": 1, "maxLength": 10000}}, "required": ["object", "id", "body"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/salesforce_connect": {"post": {"operationId": "salesforce_connect", "summary": "Connect Salesforce", "description": "Connect the company's own Salesforce org, which stays the source of truth: the agent queries, reads and changes its records. The company makes a connected app with the OAuth client credentials flow switched on and a run-as user whose profile limits what the agent may touch, and gives the org's My Domain and the app's consumer key and secret, which are checked before anything is kept. On accounts with an owner, changing an existing record waits for the owner's approval by default. Free. Free.", "tags": ["salesforce"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"my_domain": {"type": "string", "minLength": 10, "maxLength": 200, "description": "Like hansen-voss.my.salesforce.com."}, "client_id": {"type": "string", "minLength": 10, "maxLength": 300}, "secret": {"type": "string", "minLength": 8, "maxLength": 500, "description": "The connected app's consumer secret. Never shown again.", "writeOnly": true}}, "required": ["my_domain", "client_id", "secret"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/salesforce_disconnect": {"post": {"operationId": "salesforce_disconnect", "summary": "Disconnect Salesforce", "description": "Forget the connected app's secret. Nothing in Salesforce changes. Free.", "tags": ["salesforce"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/salesforce_query": {"post": {"operationId": "salesforce_query", "summary": "Query Salesforce", "description": "Run one SOQL SELECT statement in the company's org and get its records, up to 200; more says when there are others. Only reading. Free. Free.", "tags": ["salesforce"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"soql": {"type": "string", "minLength": 10, "maxLength": 4000}}, "required": ["soql"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/salesforce_get": {"post": {"operationId": "salesforce_get", "summary": "Get a Salesforce record", "description": "One record by its object and id, with all its fields or the ones named. Free. Free.", "tags": ["salesforce"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,79}$", "description": "The object's API name, like Account, Contact, Opportunity or Case."}, "id": {"type": "string", "pattern": "^[A-Za-z0-9]{15}([A-Za-z0-9]{3})?$", "description": "The record's id."}, "fields": {"type": "array", "maxItems": 50, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,79}$"}, "description": "The fields to show; all of them when left out."}}, "required": ["object", "id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/salesforce_create": {"post": {"operationId": "salesforce_create", "summary": "Create a Salesforce record", "description": "Make a record of any object the run-as user may create, with the fields given. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["salesforce"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,79}$", "description": "The object's API name, like Account, Contact, Opportunity or Case."}, "fields": {"type": "object", "minProperties": 1, "maxProperties": 50, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 5000}, "description": "Field API names and values, like {\"StageName\": \"Closed Won\", \"Amount\": 18400}."}}, "required": ["object", "fields"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/salesforce_update": {"post": {"operationId": "salesforce_update", "summary": "Change a Salesforce record", "description": "Change fields of a record. On accounts with an owner it waits for the owner's approval by default, showing each field's value now and after. $0.001. Costs $0.001 per call; nothing if it fails.", "tags": ["salesforce"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"object": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,79}$", "description": "The object's API name, like Account, Contact, Opportunity or Case."}, "id": {"type": "string", "pattern": "^[A-Za-z0-9]{15}([A-Za-z0-9]{3})?$", "description": "The record's id."}, "fields": {"type": "object", "minProperties": 1, "maxProperties": 50, "additionalProperties": {"type": ["string", "number", "boolean", "null"], "maxLength": 5000}, "description": "Field API names and values, like {\"StageName\": \"Closed Won\", \"Amount\": 18400}."}}, "required": ["object", "id", "fields"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_overview": {"post": {"operationId": "admin_overview", "summary": "Read the account page's Home", "description": "What the account page shows on its Home, in one read: the balance and what calls hold, today's and this month's spending, auto-reload, the limits, teams, people, keys, the systems connected, rentals, the first questions' answers and who made the account. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_save_setup": {"post": {"operationId": "admin_save_setup", "summary": "Answer the first questions", "description": "The answers the account page asks a person who makes an account: which AI they use (ai), the jobs to hand over (jobs), the systems they already run (uses) and the business's size (size). The page and the other agents read them to set things up. Only the questions you send change; done marks the setup finished. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"answers": {"type": "object", "additionalProperties": false, "properties": {"ai": {"type": "array", "items": {"type": "string", "enum": ["chatgpt", "claude", "grok", "grok_bot", "copilot", "claude_code", "cursor", "codex", "gemini_cli", "openclaw", "hermes", "opencode", "own_agent", "not_sure"]}}, "jobs": {"type": "array", "items": {"type": "string", "enum": ["phone", "email", "chat", "invoices", "books", "bookings", "customers", "support", "marketing", "staff"]}}, "uses": {"type": "array", "items": {"type": "string", "enum": ["googleworkspace", "microsoft365", "hubspot", "salesforce", "shopify", "other_api", "none"]}}, "size": {"type": "string", "enum": ["solo", "small", "company"]}}}, "done": {"type": "boolean"}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_list_people": {"post": {"operationId": "admin_list_people", "summary": "List the people on the account", "description": "Who besides the owner can open the account, with their role, teams, areas and when their access ends, and the requests to join waiting for a decision. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_save_person": {"post": {"operationId": "admin_save_person", "summary": "Add or change a person", "description": "Add someone to the account as a member (their own assistant works in their teams) or an auditor (reads everything, changes nothing), or change one: their name, teams, areas and the day their access ends. They are told by email when added. Making someone an owner, admin or billing person is the owner's. Costs $0.001 per call; nothing if it fails.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "minLength": 3, "maxLength": 254}, "name": {"type": "string", "maxLength": 120}, "role": {"type": "string", "enum": ["member", "auditor", "admin", "billing", "owner"], "default": "member"}, "teams": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 80}, "description": "Their teams, replacing the ones they are in."}, "areas": {"type": "array", "items": {"type": "string"}, "description": "For an account without teams: the areas their assistant works in."}, "access_until": {"type": "string", "maxLength": 10, "description": "The last day of their access, like 2027-03-31."}}, "required": ["email"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_remove_person": {"post": {"operationId": "admin_remove_person", "summary": "Remove a person", "description": "Take someone's access away. It ends at once on every browser they signed in on, and their own assistants stop working. Removing an owner, admin or billing person is the owner's. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "minLength": 3, "maxLength": 254}}, "required": ["email"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_list_join_codes": {"post": {"operationId": "admin_list_join_codes", "summary": "List join codes", "description": "The one-time codes made for other bots to join this account, newest first: their team, areas, whether they only read or only draft, when they expire and which bot used them. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_make_join_code": {"post": {"operationId": "admin_make_join_code", "summary": "Make a join code for another bot", "description": "A one-time code another bot uses to join this account instead of signing up alone: the key it gets works for the code's team, within its areas, and only reads or only drafts when the code says so. Shown once; it works for days (1 to 30, 7 by default). Hand the bot the sentence in give_your_bot. Costs $0.001 per call; nothing if it fails.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"label": {"type": "string", "maxLength": 80, "description": "What the bot is for."}, "team": {"type": "string", "maxLength": 80}, "areas": {"type": "array", "items": {"type": "string"}}, "read_only": {"type": "boolean"}, "drafts_only": {"type": "boolean"}, "days": {"type": "integer", "minimum": 1, "maximum": 30, "default": 7}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_revoke_join_code": {"post": {"operationId": "admin_revoke_join_code", "summary": "Withdraw a join code", "description": "Withdraw a join code no bot used yet, by the last four characters it ends with (or its id). Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"code": {"type": "string", "minLength": 1, "maxLength": 20}}, "required": ["code"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_list_domains": {"post": {"operationId": "admin_list_domains", "summary": "List the email domains", "description": "The company's email domains on the account: whether each is proved, how people on it join (off, request or open), their team and areas, and the TXT record that proves it. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_save_domain": {"post": {"operationId": "admin_save_domain", "summary": "Let colleagues join by email domain", "description": "Add the company's email domain, prove it, and choose how people on it join. Added, it comes back with a TXT record for its DNS; once the record is up, verify: true proves it. joining: request lets people with an address there ask to join (an owner, admin or this agent approves with admin_decide_join_request); open lets them join right away as members, which only the owner turns on; off stops both. People who join get the domain's team and areas. Costs $0.001 per call; nothing if it fails.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The part of the company's addresses after the @, like hansenvoss.example."}, "verify": {"type": "boolean"}, "joining": {"type": "string", "enum": ["off", "request", "open"]}, "team": {"type": "string", "maxLength": 80}, "areas": {"type": "array", "items": {"type": "string"}}}, "required": ["domain"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_remove_domain": {"post": {"operationId": "admin_remove_domain", "summary": "Remove an email domain", "description": "Take a domain off the account: nobody joins or asks to join with it any more. People who joined stay. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "minLength": 4, "maxLength": 253, "description": "The part of the company's addresses after the @, like hansenvoss.example."}}, "required": ["domain"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_decide_join_request": {"post": {"operationId": "admin_decide_join_request", "summary": "Approve or decline a request to join", "description": "Approve someone who asked to join with their work address: they become a member at once, in their domain's team and areas, and are told by email. Or decline: they can ask again in 30 days. admin_list_people lists the requests waiting. Costs $0.001 per call; nothing if it fails.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"request_id": {"type": "integer", "minimum": 1}, "approve": {"type": "boolean"}}, "required": ["request_id", "approve"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_list_bridges": {"post": {"operationId": "admin_list_bridges", "summary": "List the bridges", "description": "The bridges running inside the company's network, which reach systems behind its firewall: each online or not, when it last checked in, its version, and the systems it serves with the calls its own config allows. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_make_bridge": {"post": {"operationId": "admin_make_bridge", "summary": "Make a bridge to a system behind the firewall", "description": "A new bridge for systems inside the company's network, like an ERP or an internal API. Its token comes back once, with the program for IT to run and the steps. The bridge connects out to Conecto, so nothing opens inbound, and makes only the calls its own config allows. Then connect_add with bridge and system reaches a system through it. Costs $0.001 per call; nothing if it fails.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 2, "maxLength": 40, "description": "Lowercase letters, digits and dashes, like office-hamburg."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/admin_revoke_bridge": {"post": {"operationId": "admin_revoke_bridge", "summary": "Stop a bridge", "description": "Stop a bridge at once: its token stops working, and calls waiting for it fail at no cost. Free.", "tags": ["admin"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "minLength": 2, "maxLength": 40, "description": "Lowercase letters, digits and dashes, like office-hamburg."}}, "required": ["name"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/prospects_prepare": {"post": {"operationId": "prospects_prepare", "summary": "Prepare a prospect search", "description": "The interview before a prospect search. From what the person asked for and what you know about the business, Conecto either asks up to three questions with choices, about the market and the kind of customer (never job titles), or writes a ready brief. Ask the questions in your own chat, then call again with the same request and about_us and every answer so far, by question id. When the status is ready, show the person the summary, the count and what it can cost (count x $0.05), and start it with prospects_find once they agree. Only accounts that have topped up search. Free.", "tags": ["prospects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"request": {"type": "string", "minLength": 3, "maxLength": 4000, "description": "What the person asked for, in their words: who, how many, where."}, "about_us": {"type": "string", "minLength": 20, "maxLength": 4000, "description": "What the business sells, to whom and where, and what it wants from these prospects, from what you know about it. The interview never asks the person this."}, "website": {"type": "string", "maxLength": 500, "description": "The business's website; the account's own when left out."}, "answers": {"type": "object", "maxProperties": 12, "additionalProperties": {"anyOf": [{"type": "string", "maxLength": 300}, {"type": "array", "maxItems": 8, "items": {"type": "string", "maxLength": 300}}]}, "description": "The answers so far, by question id: a choice's value, several values for a multiple choice, or the person's own words."}}, "required": ["request", "about_us"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/prospects_find": {"post": {"operationId": "prospects_find", "summary": "Find prospects", "description": "Start a prospect search from a brief prospects_prepare made: businesses that fit and the people to reach there, with their work email checked, from public business pages. About two minutes for 50. The reply is 202 with a call_id, which is the search's id: follow it with prospects_get, or wait for the prospects.found event. The price of every prospect asked for is held; when the search ends, only the prospects found with a working email are charged and the rest of the hold comes back. Two searches at a time, and 1,000 prospects a month. The business's Conecto inboxes never write first to the people found: write to them from the business's own mailbox, with an outreach campaign (outreach_save_campaign with the search_id as prospect_search_id). Costs $0.05 per prospect found with a working email; nothing if none are found.", "tags": ["prospects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"brief_token": {"type": "string", "minLength": 20, "maxLength": 12000, "description": "The brief_token of a ready prospects_prepare."}, "count": {"type": "integer", "minimum": 10, "maximum": 100, "description": "How many prospects to find: the count prospects_prepare proposed, or the one the person chose."}}, "required": ["brief_token", "count"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/prospects_get": {"post": {"operationId": "prospects_get", "summary": "Get a prospect search", "description": "A prospect search by id: running, needs_input (it stopped finding new prospects and asks whether to widen it), completed, stopped or failed; its progress, its question when it asks one, and the prospects found so far, named people first: the company, the person and their title, the work email and how it was checked, phone, and whether they are saved to the CRM. Free.", "tags": ["prospects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"search_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The call_id prospects_find answered with."}, "offset": {"type": "integer", "minimum": 0, "default": 0}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, "required": ["search_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/prospects_list": {"post": {"operationId": "prospects_list", "summary": "List prospect searches", "description": "The account's prospect searches, newest first: status, what each asked for and how many it found. Free.", "tags": ["prospects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 10}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/prospects_answer": {"post": {"operationId": "prospects_answer", "summary": "Answer a prospect search", "description": "Answer the question of a search whose status is needs_input, in the person's words or with a choice's value; it carries on with the answer, under the same hold. A search left waiting a day ends with what it found. Free.", "tags": ["prospects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"search_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The call_id prospects_find answered with."}, "answer": {"type": "string", "minLength": 1, "maxLength": 2000}}, "required": ["search_id", "answer"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/prospects_stop": {"post": {"operationId": "prospects_stop", "summary": "Stop a prospect search", "description": "Stop a search. It ends with the prospects it found, and only those with a working email are charged (within a minute). Free.", "tags": ["prospects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"search_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The call_id prospects_find answered with."}}, "required": ["search_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/prospects_save": {"post": {"operationId": "prospects_save", "summary": "Keep prospects in the CRM", "description": "Add prospects the person keeps to the CRM: each one's company, and a contact (lead) with the person's name, title, work email and phone, tagged prospect, with why they fit in its notes. Leave prospect_ids out to keep all a search found. Prospects kept before are left as they are. Free.", "tags": ["prospects"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"search_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The call_id prospects_find answered with."}, "prospect_ids": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "integer", "minimum": 1}}}, "required": ["search_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_connect_mailbox": {"post": {"operationId": "outreach_connect_mailbox", "summary": "Connect a mailbox for outreach", "description": "A link for the owner to connect one of the business's own mailboxes, which outreach campaigns send from and read replies in. The owner opens it and types the mailbox's settings and password on a Conecto page naming the business; you never see the password. Gmail and Outlook connect the same way with an app password (name the provider and their servers are filled in); any other mailbox with its SMTP and IMAP settings. The link works once and for an hour. outreach.mailbox_connected tells you when it is done, and outreach_mailboxes lists it. Conecto's own inboxes never send cold email. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"provider": {"type": "string", "enum": ["gmail", "other", "outlook"], "default": "other", "description": "Whose mailbox it is, to fill in its servers: gmail, outlook, or other."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_mailboxes": {"post": {"operationId": "outreach_mailboxes", "summary": "List outreach mailboxes", "description": "The business's mailboxes connected for outreach: each one's mailbox_id, address, the name people see, its state (ready, daily_limit_reached, waiting_for_check, reply_check_failed, paused, paused_for_bounces, paused_for_failures, over_limit or disconnected) and what went wrong, its daily limit and what it sent in the last 24 hours, its bounce rate, and its servers. Never a password. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_save_campaign": {"post": {"operationId": "outreach_save_campaign", "summary": "Save an outreach campaign", "description": "Create an outreach campaign, or change one (pass campaign_id): its name, the mailboxes it sends from (they share the load, each within its own daily limit), the emails (a first email and up to four follow-ups, each with delay_days), the audience, a first line for each person, the sending days and hours in a time zone, and its own daily limit. The audience is one of: a prospect search's people with a working email (prospect_search_id), a CRM segment, or everyone with a tag; people who unsubscribed, bounced, said no, replied before or are in another campaign are left out, and the reply says who. You write every email; Conecto writes nothing. Placeholders: {first_name} (the person's first name), {name} (the person's full name), {company} (their company), {first_line} (the first line you wrote for them in first_lines), {sender_name} (the name of the mailbox that sends it), {sender_first_name} (that name's first word). Every step passes Conecto's writing check before a campaign can start, and a refusal names each fix: no em dashes; no stock openers (\"I hope this email finds you well\", \"I'm reaching out\") or closers (\"Best regards\", \"Looking forward to hearing from you\"); no \"not X, but Y\" contrasts or slogans; no hype or filler words (\"seamless\", \"game-changer\", \"I'd love to\"); at most 120 words an email and 60 characters a subject; one link and one ask at most; no \"Re:\" on a first email; no unsubscribe line of your own (Conecto adds one); and every placeholder filled for every person. The reply has the writing check's fixes; show the person outreach_preview, then start it with outreach_start. While it is a draft everything can change; once it started, only its name, mailboxes, schedule and daily limit, while it is paused. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"campaign_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The campaign_id outreach_save_campaign answered with."}, "name": {"type": "string", "minLength": 1, "maxLength": 160}, "mailbox_ids": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "integer", "minimum": 1}, "description": "Mailboxes from outreach_mailboxes, in the order they take turns."}, "steps": {"type": "array", "minItems": 1, "maxItems": 5, "items": {"type": "object", "additionalProperties": false, "required": ["text"], "properties": {"subject": {"type": "string", "maxLength": 200, "description": "One line. A follow-up without one goes as \"Re:\" the first email's subject, in the same thread."}, "text": {"type": "string", "minLength": 1, "maxLength": 5000, "description": "Plain text. Conecto adds the unsubscribe line at the end."}, "delay_days": {"type": "integer", "minimum": 1, "maximum": 60, "description": "A follow-up: days after the step before it, when nobody replied (3 if left out)."}}}}, "audience": {"type": "object", "additionalProperties": false, "properties": {"tag": {"type": "string", "minLength": 1, "maxLength": 60}, "segment": {"type": "string", "minLength": 1, "maxLength": 80, "description": "A saved contact segment, by name or id."}, "prospect_search_id": {"type": "string", "minLength": 36, "maxLength": 36}}, "description": "One of tag, segment or prospect_search_id."}, "first_lines": {"type": "object", "maxProperties": 2000, "additionalProperties": {"type": "string", "maxLength": 300}, "description": "A first line you wrote for each person, by their email: {first_line} in an email."}, "schedule": {"type": "object", "additionalProperties": false, "properties": {"days": {"type": "array", "minItems": 1, "maxItems": 7, "items": {"enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]}}, "start_hour": {"type": "integer", "minimum": 0, "maximum": 23}, "end_hour": {"type": "integer", "minimum": 1, "maximum": 24}, "time_zone": {"type": "string", "minLength": 1, "maxLength": 64}}, "description": "When emails go: Monday to Friday, 9 to 17, in the account's time zone unless given."}, "daily_limit": {"type": "integer", "minimum": 1, "maximum": 1000, "description": "Emails a day for this campaign; its mailboxes' own limits still hold."}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_preview": {"post": {"operationId": "outreach_preview", "summary": "Preview an outreach campaign", "description": "The emails of one step as they will go, for real people of the campaign: who it goes to, from which mailbox, the subject and the text with every placeholder filled and the unsubscribe line Conecto adds (each person gets their own link, so the preview shows where it goes). Show the person the first emails before you start a campaign. Also the writing check's fixes, if any. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"campaign_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The campaign_id outreach_save_campaign answered with."}, "step": {"type": "integer", "minimum": 1, "maximum": 5, "default": 1}, "limit": {"type": "integer", "minimum": 1, "maximum": 25, "default": 3}, "email": {"type": "string", "maxLength": 254, "description": "One person of the campaign."}}, "required": ["campaign_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_start": {"post": {"operationId": "outreach_start", "summary": "Start an outreach campaign", "description": "Start sending a campaign the person approved. Emails go within its days and hours, spread across the day and across its mailboxes, each mailbox within its daily limit; follow-ups thread under the first email and stop for anyone who replies; every email carries an unsubscribe line, and anyone who unsubscribes is never emailed again by any campaign. Each person costs $0.01 when their first email leaves, for their whole sequence and reply tracking; nobody who is never emailed costs anything. Refused until the writing check passes, with each fix named. Some countries, Germany among them, need a person's prior consent even for business email: the business answers for whom it writes to, so check with the person before you write to people there. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"campaign_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The campaign_id outreach_save_campaign answered with."}}, "required": ["campaign_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_get_campaign": {"post": {"operationId": "outreach_get_campaign", "summary": "Get an outreach campaign", "description": "One campaign: its settings, its numbers (people queued, messaged, replied, interested, not interested, bounced, unsubscribed, stopped; emails sent, the reply rate, what it cost, and each step's emails and the replies after it) and its people page by page, each with their status (queued, messaged, replied, interested, not_interested, bounced, unsubscribed, stopped, unconfirmed or failed), the emails sent to them, when the next one goes and their CRM contact_id. waiting says why a running campaign sends nothing right now, when the account is paused or its balance can't pay. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"campaign_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The campaign_id outreach_save_campaign answered with."}, "status": {"type": "string", "enum": ["queued", "messaged", "replied", "interested", "not_interested", "bounced", "unsubscribed", "stopped", "unconfirmed", "failed", "erased"], "description": "Only the people in this state."}, "offset": {"type": "integer", "minimum": 0, "default": 0}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}}, "required": ["campaign_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_replies": {"post": {"operationId": "outreach_replies", "summary": "Read outreach replies", "description": "The replies to the business's outreach campaigns, newest first: who wrote (email, name, company and their CRM contact_id), to which campaign, the subject, the text, when it came and their status now. Replies are read from each mailbox every few minutes; a reply stops the person's follow-ups. Answer them from the business's own mailbox, and keep whether they are interested with outreach_set_status. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"campaign_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The campaign_id outreach_save_campaign answered with."}, "since": {"type": "string", "format": "date-time", "description": "Only replies received after this time (ISO 8601)."}, "offset": {"type": "integer", "minimum": 0, "default": 0}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_campaigns": {"post": {"operationId": "outreach_campaigns", "summary": "List outreach campaigns", "description": "The business's outreach campaigns, newest first, each with its status (draft, running, paused, completed or stopped), why it paused, its mailboxes and its numbers: people, queued, messaged, replied, the reply rate, interested, not interested, bounced, unsubscribed, emails sent and what it cost. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["draft", "running", "paused", "completed", "stopped"]}, "offset": {"type": "integer", "minimum": 0, "default": 0}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25}}, "required": [], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_pause": {"post": {"operationId": "outreach_pause", "summary": "Pause an outreach campaign", "description": "Stop sending a running campaign for now. Replies are still read; resume it with outreach_resume and it carries on where it left, follow-ups included. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"campaign_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The campaign_id outreach_save_campaign answered with."}}, "required": ["campaign_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_resume": {"post": {"operationId": "outreach_resume", "summary": "Resume an outreach campaign", "description": "Send again from a paused campaign, once what paused it is fixed (paused_reason says what). When the key that paid for it was revoked, the key that resumes it pays for new people from then on; the campaign still names the key that made it. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"campaign_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The campaign_id outreach_save_campaign answered with."}}, "required": ["campaign_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_stop": {"post": {"operationId": "outreach_stop", "summary": "Stop an outreach campaign", "description": "End a campaign for good: nobody it hasn't emailed yet is emailed or charged, and no follow-up goes. Replies to what it sent are still read. It can't start again; save a new campaign instead. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"campaign_id": {"type": "string", "minLength": 36, "maxLength": 36, "description": "The campaign_id outreach_save_campaign answered with."}}, "required": ["campaign_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_set_status": {"post": {"operationId": "outreach_set_status", "summary": "Mark someone interested or not", "description": "Keep in the CRM whether someone your outreach reached is interested or not interested (their contact's outreach_status), by contact_id or email. Their pending outreach emails stop either way; not interested also puts them on the do-not-email list, so no campaign writes to them again. Their lifecycle stage stays as it is: change it with crm_update_contact when the person moves on. Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["interested", "not_interested"]}, "contact_id": {"type": "integer", "minimum": 1}, "email": {"type": "string", "maxLength": 254}}, "required": ["status"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}, "/v1/tools/outreach_update_mailbox": {"post": {"operationId": "outreach_update_mailbox", "summary": "Change an outreach mailbox", "description": "Change a connected mailbox: the name people see (sender_name), its daily limit (1 to 200 emails in any 24 hours, shared by every campaign that sends from it), pause or resume its sending, or disconnect it (Conecto forgets its password). A campaign none of whose mailboxes can send pauses and tells you; resume it once a mailbox can send again. Its settings and password change only on a new connect link (outreach_connect_mailbox). Free.", "tags": ["outreach"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mailbox_id": {"type": "integer", "minimum": 1}, "sender_name": {"type": "string", "minLength": 1, "maxLength": 120}, "daily_limit": {"type": "integer", "minimum": 1, "maximum": 200}, "paused": {"type": "boolean"}, "disconnect": {"type": "boolean", "description": "true disconnects it for good."}}, "required": ["mailbox_id"], "additionalProperties": false}}}}, "responses": {"200": {"description": "Done; cost_usd is what it cost.", "content": {"application/json": {"schema": {"type": "object", "properties": {"call_id": {"type": "string"}, "tool": {"type": "string"}, "status": {"type": "string"}, "replayed": {"type": "boolean"}, "cost_usd": {"type": "string"}, "balance_usd": {"type": "string"}, "result": {"type": "object"}}}}}}, "4XX": {"description": "Refused or failed; nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "cost_usd": {"type": "string"}, "details": {"type": "object"}}}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 120}}]}}}}