{"openapi":"3.1.0","info":{"title":"Analytical Insider Agent API","version":"2026-11-15","summary":"Preview. Routes for a software agent that acts for a person or company.","description":"Generated from the discovery document. What is available now and what is not is stated by the preview block of that document and by https://analyticalinsider.ai/agents.","termsOfService":"https://analyticalinsider.ai/terms/agents"},"servers":[{"url":"https://analyticalinsider.ai"}],"paths":{"/api/public/agent/v1":{"get":{"operationId":"getPublicDiscovery","summary":"This discovery document.","security":[],"responses":{"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/public/agent/v1/openapi":{"get":{"operationId":"getPublicOpenapi","summary":"The OpenAPI 3.1 description of every route in this document, generated from it.","security":[],"responses":{"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/public/agent/v1/signup":{"post":{"operationId":"postPublicSignup","summary":"Start a signup for a verified principal; returns a hosted checkout URL and states the plan, the monthly amount and the one-time setup amount the checkout was created for. The setup is charged once, with the first month.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"principal":{"type":"object","properties":{"legalName":{"type":"string","description":"Legal name of the person or company the agent acts for (max 200)."},"email":{"type":"string","description":"The principal's real email address."},"website":{"type":"string","description":"The principal's website, an https URL."},"postalAddress":{"type":"object","properties":{"line1":{"type":"string","description":"Street address line 1."},"line2":{"type":"string","description":"Street address line 2."},"city":{"type":"string","description":"City."},"region":{"type":"string","description":"State, province or region."},"postalCode":{"type":"string","description":"Postal code."},"country":{"type":"string","description":"Two-letter ISO 3166-1 country code, e.g. US."}},"required":["line1","city","region","postalCode","country"]}},"required":["legalName","email","postalAddress"]},"agent":{"type":"object","properties":{"name":{"type":"string","description":"A name for the agent (max 120)."},"operator":{"type":"string","description":"Who operates the agent (max 200)."}},"required":["name","operator"]},"plan":{"type":"string","description":"The plan to buy, one of: phone, email, bundle. phone covers calls and texts from a dedicated number, email covers a sending domain with one mailbox, bundle covers both. Defaults to bundle. What each includes and costs is in pricing.plans of the discovery document."},"termsVersion":{"type":"string","description":"Must be exactly \"agent-v2\"."},"acceptTerms":{"type":"boolean","description":"Must be exactly true: the principal accepts the agent terms."},"successUrl":{"type":"string","description":"Where checkout sends the payer after payment, an https URL."},"cancelUrl":{"type":"string","description":"Where checkout sends the payer on cancel, an https URL."}},"required":["principal","agent","termsVersion","acceptTerms"]},"example":{"principal":{"legalName":"Example Widgets LLC","email":"owner@example.com","website":"https://www.example.com","postalAddress":{"line1":"100 Example Street","line2":"Suite 200","city":"Springfield","region":"IL","postalCode":"62701","country":"US"}},"agent":{"name":"example-sales-agent","operator":"Example Widgets LLC"},"plan":"bundle","termsVersion":"agent-v2","acceptTerms":true}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/public/agent/v1/claim":{"post":{"operationId":"postPublicClaim","summary":"Exchange a paid checkout session id (JSON body { \"checkoutSessionId\" }) for the API key, once.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checkoutSessionId":{"type":"string","description":"The checkoutSessionId the signup response returned, used after the principal has paid."}},"required":["checkoutSessionId"]},"example":{"checkoutSessionId":"cs_live_a1B2c3D4e5F6g7H8i9J0"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/me":{"get":{"operationId":"getMe","summary":"The organization this key acts for. plan is the package key; planValue is the plan as this API names it (phone, email or bundle) and includes lists its channels (phone, email).","security":[{"bearerAuth":[]}],"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/status":{"get":{"operationId":"getStatus","summary":"Plan (the package key, with planValue and includes), restriction state, allowances, the prepaid lead balance (leadBalance: available and reserved), lead counts and the preview block (what is available now and what is not).","security":[{"bearerAuth":[]}],"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/subscription":{"get":{"operationId":"getSubscription","summary":"Subscription status, current period end and the date a scheduled cancellation takes effect (null when none).","security":[{"bearerAuth":[]}],"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/subscription/cancel":{"post":{"operationId":"postSubscriptionCancel","summary":"Schedule cancellation 30 days from now. No body needed. A repeat request changes nothing and returns the same date.","security":[{"bearerAuth":[]}],"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/subscription/plan":{"post":{"operationId":"postSubscriptionPlan","summary":"Upgrade a phone or email plan to the bundle. The difference for the rest of the current period is charged at once, and moving from phone adds the one-time domain registration and security setup to that charge (an email plan paid it at signup). 200 { plan, packageKey, includes, changed }: changed is false when the plan was already the bundle. 402 PAYMENT_FAILED with updatePaymentUrl when the charge does not go through or there is no card on file, and then nothing changes: not the plan, not the allowances, not the subscription. updatePaymentUrl opens a page that only adds a card. 422 UPGRADE_REFUSED when the payment processor refuses the change itself (a retry will not help). 409 CANCELLATION_SCHEDULED, 404 NOT_FOUND. Every answer is stored against the idempotencyKey and a replay returns it; send a new key to try again. 500 SUBSCRIPTION_UNAVAILABLE with a Retry-After header is temporary and not stored: retry the same key after that many seconds. There is no downgrade by API: cancel and sign up again.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","description":"Must be \"bundle\"."},"idempotencyKey":{"type":"string","description":"A key you choose for this request, 8 to 128 characters: letters, digits, dot, underscore or hyphen."}},"required":["plan","idempotencyKey"]},"example":{"plan":"bundle","idempotencyKey":"upgrade-to-bundle-0001"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/key/rotate":{"post":{"operationId":"postKeyRotate","summary":"Replace the API key while the account is active, authenticated with the current key (a restricted account is refused with 403). 201 with the new key, shown once; the key you sent stops working at once. If the response is lost, send the same request again within one hour, with the same old key and the same idempotencyKey: you get a working key, and the one you never received is retired. 409 ROTATION_IN_PROGRESS means another request replaced this key at the same moment; if you did not receive its new key, send the same request again. 409 ROTATION_ALREADY_DELIVERED means the key from that rotation was already used. 500 INTERNAL means that request changed nothing; send the same request again.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"type":"string","description":"At least 32 random characters that you generate for this rotation (up to 128: letters, digits, dot, underscore or hyphen). It is the secret that lets you recover a lost response, so never reuse one and never send the example value, which is refused. Keep it until you have stored the new key; a retry must send the same one."}},"required":["idempotencyKey"]},"example":{"idempotencyKey":"rotate-example-generate-your-own-32-plus-random-chars"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/icp":{"get":{"operationId":"getIcp","summary":"Read the ideal customer profile.","security":[{"bearerAuth":[]}],"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}},"put":{"operationId":"putIcp","summary":"Replace the ideal customer profile.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetMarket":{"type":"string","description":"Who the best customers are, in one short specific sentence (max 200 characters)."},"geos":{"type":"array","items":{"type":"string"},"description":"Regions to target: 1 to 8 sub-country regions such as US states. A whole country or \"Global\" is refused."},"titles":{"type":"array","items":{"type":"string"},"description":"Job titles to reach: 1 to 6."},"industries":{"type":"array","items":{"type":"string"},"description":"Specific industries: 1 to 8. Generic values such as \"General\" or \"B2B\" are refused."},"secondaryMarket":{"type":"string","description":"A secondary market."},"companySizeOrLocationsMin":{"type":"integer","description":"Minimum employee or location count."},"companySizeMax":{"type":"integer","description":"Maximum employee or location count."},"qualifiers":{"type":"array","items":{"type":"string"},"description":"Positive signals that mark a good fit: up to 5."},"triggerSignals":{"type":"array","items":{"type":"string"},"description":"Events that make a company worth contacting now: up to 5."},"revenueMin":{"type":"integer","description":"Minimum annual revenue in USD millions."},"revenueMax":{"type":"integer","description":"Maximum annual revenue in USD millions."},"ownershipType":{"type":"string","description":"One of \"any\", \"private_only\", \"public_only\"."}},"required":["targetMarket","geos","titles","industries"]},"example":{"targetMarket":"Regional commercial HVAC contractors that service multi-site property managers","geos":["Illinois","Indiana","Wisconsin"],"titles":["Owner","Operations Manager","General Manager"],"industries":["HVAC Contracting","Commercial Building Services"],"companySizeOrLocationsMin":10,"companySizeMax":200,"qualifiers":["Serves commercial properties","Runs a service fleet"],"triggerSignals":["Hiring service technicians","Opened a new branch"],"revenueMin":2,"revenueMax":50,"ownershipType":"private_only"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/leads":{"get":{"operationId":"getLeads","summary":"List leads (?stage=&cursor=&limit=) or fetch one (?id=<leadId>). Lead pulls are not yet available, so the list is empty and carries note lead_pulls_not_yet_available.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":false,"description":"Fetch one lead by id.","schema":{"type":"string","description":"Fetch one lead by id."}},{"name":"stage","in":"query","required":false,"description":"Filter by stage, one of: pending_qualification, qualified, active_in_cadence, engaged, meeting_booked, handed_to_ae, disqualified, nurture, stale, contact_bad.","schema":{"type":"string","description":"Filter by stage, one of: pending_qualification, qualified, active_in_cadence, engaged, meeting_booked, handed_to_ae, disqualified, nurture, stale, contact_bad."}},{"name":"cursor","in":"query","required":false,"description":"The nextCursor from the previous page.","schema":{"type":"string","description":"The nextCursor from the previous page."}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100 (default 25).","schema":{"type":"integer","description":"Page size, 1 to 100 (default 25)."}}],"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/number":{"get":{"operationId":"getNumber","summary":"The organization's dedicated number as { number: { e164, status, assignedAt } }, or { number: null } before one is bought. Callers who ring it reach a voicemail, and texts sent to it are readable on the messages route.","security":[{"bearerAuth":[]}],"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}},"post":{"operationId":"postNumber","summary":"Buy the dedicated number the plan includes, once. 201 with the number; if the organization already has one, 200 with that same number. 409 CAP_EXCEEDED when the plan's one number is already used, 409 NUMBER_UNAVAILABLE when that area code has no number to give (choose another area code; a retry with the same one cannot work), 500 INTERNAL with a Retry-After header when the purchase fails for another reason (nothing is kept, retry with a new idempotencyKey). A replayed idempotencyKey returns the first outcome, so use a new key to try another area code.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"areaCode":{"type":"string","description":"A US area code for one of the 50 states or DC, such as 312. Toll-free, Canadian, Caribbean, territory and unassigned codes are refused."},"idempotencyKey":{"type":"string","description":"A key you choose for this purchase, 8 to 128 characters: letters, digits, dot, underscore or hyphen."}},"required":["areaCode","idempotencyKey"]},"example":{"areaCode":"312","idempotencyKey":"buy-number-0001"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/calls":{"get":{"operationId":"getCalls","summary":"The organization's calls and voicemails as { calls, nextCursor }, oldest first: id, direction, from, to, startedAt, durationSeconds, voicemail and transcript (null until the voicemail is transcribed). Keep the last id you saw and pass it as cursor to read only what is new. A call is listed as soon as it exists, before its transcript does, and a cursor never returns a row it has already passed: to read a voicemail's transcript, fetch the call by id (?id=<callId>, answers { call }, or 404 NOT_FOUND) once it has been transcribed. id cannot be combined with cursor or limit.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":false,"description":"Fetch one call by id, including its transcript once it exists. Cannot be combined with cursor or limit.","schema":{"type":"string","description":"Fetch one call by id, including its transcript once it exists. Cannot be combined with cursor or limit."}},{"name":"cursor","in":"query","required":false,"description":"Return rows after this id: the nextCursor from the previous page, or the last id you saw.","schema":{"type":"string","description":"Return rows after this id: the nextCursor from the previous page, or the last id you saw."}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100 (default 25).","schema":{"type":"integer","description":"Page size, 1 to 100 (default 25)."}}],"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}},"post":{"operationId":"postCalls","summary":"Place one automated-voice call from your number to a contact with recorded written call consent. The call says it is an automated call from your principal's legal name and that pressing 9 stops further calls, then speaks say, then says \"To reach <legal name>, call <callbackNumber>.\", then hangs up. Calls are not recorded, last at most 120 seconds once answered, run one at a time, and are limited to 25 per UTC day and 30 per UTC calendar month. 201 { id, status }; the call then appears on GET calls. Refusals, in order: 400 VALIDATION_FAILED, 422 INVALID_CHARACTERS, 422 CALLBACK_NUMBER_INVALID, 409 NO_NUMBER, 404 NOT_FOUND, 422 NOT_DIALABLE, 422 PHONE_NOT_US (United States geographic numbers only: no other country, toll-free or premium-rate), 403 LEAD_DO_NOT_CALL / BAD_NUMBER_REGISTERED / OUTSIDE_CONTACT_HOURS / CONTACT_ZONE_UNKNOWN / DIAL_GATE_UNAVAILABLE, 422 CALL_CONSENT_REQUIRED, 409 CAP_EXCEEDED, 409 CALL_IN_PROGRESS, 422 INTERNAL (refused, not placed, will not succeed as sent), 500 INTERNAL with a Retry-After header (a temporary limit, not placed), 409 CALL_OUTCOME_UNKNOWN (the call may have been placed: do not place it again; GET calls shows what happened). A replayed idempotencyKey returns the first outcome and places nothing; every retry needs a new idempotencyKey.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","description":"The id of one of your contacts."},"say":{"type":"string","description":"The message to speak after the opening: 1 to 1,000 characters, no control characters."},"callbackNumber":{"type":"string","description":"A telephone number for your principal's business, spoken at the end of the call: a United States geographic or toll-free number, and not your own agent number."},"idempotencyKey":{"type":"string","description":"A key you choose for this call, 8 to 128 characters: letters, digits, dot, underscore or hyphen."}},"required":["contactId","say","callbackNumber","idempotencyKey"]},"example":{"contactId":"cm0examplecontact00000001","say":"Hello, this is a reminder that your service visit is booked for Tuesday at 10 in the morning.","callbackNumber":"+18005550199","idempotencyKey":"call-0001-reminder"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/messages":{"get":{"operationId":"getMessages","summary":"The organization's text messages as { messages, nextCursor }, oldest first: id, direction, from, to, body, status and createdAt. Keep the last id you saw and pass it as cursor to read only what is new.","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"description":"Return rows after this id: the nextCursor from the previous page, or the last id you saw.","schema":{"type":"string","description":"Return rows after this id: the nextCursor from the previous page, or the last id you saw."}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100 (default 25).","schema":{"type":"integer","description":"Page size, 1 to 100 (default 25)."}}],"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}},"post":{"operationId":"postMessages","summary":"Send one text message to a contact from your own number. The first message to a number needs recorded consent (422 CONSENT_REQUIRED) and carries an opt-out notice; a STOP reply blocks every later one. Text messages draw on one monthly budget of billed segments per organization, by UTC calendar month. A message of up to 160 basic Latin characters is one segment; a longer one, or one containing an emoji or a non-Latin character, uses more than one. The opt-out notice on a first message and the one-time opt-in confirmation count too. The budget is 100 segments; a message that would pass it is 409 CAP_EXCEEDED. Reusing an idempotencyKey sends nothing and returns the first answer, refusals included: use a new key to try again.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","description":"The contact id."},"body":{"type":"string","description":"The message, 1 to 480 characters after trimming, including the opt-out notice added to a first message; longer is 422 BODY_TOO_LONG."},"idempotencyKey":{"type":"string","description":"A unique key for this send, 8 to 128 characters: letters, digits, dot, underscore or hyphen."}},"required":["contactId","body","idempotencyKey"]},"example":{"contactId":"clx0example0contact0000001","body":"Hi Jordan, thanks for the quote request. Is Tuesday at 10am a good time for a 15 minute call?","idempotencyKey":"msg-2026-11-14-0001"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/contacts":{"post":{"operationId":"postContacts","summary":"Add one of your own contacts. United States numbers only: any other country, toll-free and premium-rate numbers are 422 PHONE_NOT_US. Answers 201 { contact } in the same shape as GET leads, or 200 with the existing contact when the number is already on file. A number that is not real and dialable is 422 PHONE_NOT_DIALABLE.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The contact's name (max 200)."},"phone":{"type":"string","description":"The contact's direct line: a United States number, E.164 or 10 digits. Fictional shapes such as the 555 exchange in the example are refused."},"company":{"type":"string","description":"Company name (max 200)."},"title":{"type":"string","description":"Job title (max 200)."},"email":{"type":"string","description":"Email address."}},"required":["name","phone"]},"example":{"name":"Jordan Example","phone":"+13125550100","company":"Example Widgets LLC","title":"Operations Manager","email":"jordan@example.com"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/contacts/sms-consent":{"post":{"operationId":"postContactsSms-consent","summary":"Attest that a contact agreed to receive text messages, for the contact's current number. Required before the first message to that number; a changed number needs a new attestation. Repeating it for the same number changes nothing.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","description":"The contact id from POST contacts or GET leads."},"obtainedAt":{"type":"string","description":"When the contact agreed: ISO 8601 with a time zone offset, not in the future."},"method":{"type":"string","description":"How the contact agreed, one of: web_form, written_form, verbal, text_keyword."},"evidence":{"type":"string","description":"What proves it (20 to 2000 characters), stored exactly as given."}},"required":["contactId","obtainedAt","method","evidence"]},"example":{"contactId":"clx0example0contact0000001","obtainedAt":"2026-11-14T15:30:00Z","method":"web_form","evidence":"Checked the SMS opt-in box on the quote request form at https://www.example.com/quote on 2026-11-14."}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/lead-packs":{"post":{"operationId":"postLead-packs","summary":"Not yet available: answers 403 NOT_YET_AVAILABLE until lead pulls open. Buy a prepaid pack of 5 or 10 leads at the per-lead price given in this document's pricing.leadPull; returns a hosted checkout URL and a checkoutSessionId. Leads are not part of the plan fee.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"size":{"type":"integer","description":"Leads in the pack: 5 or 10."},"idempotencyKey":{"type":"string","description":"Your key for this purchase, 8 to 128 characters. A repeat with the same key returns the same checkout."}},"required":["size","idempotencyKey"]},"example":{"size":5,"idempotencyKey":"pack-2026-11-16-0001"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/lead-packs/confirm":{"post":{"operationId":"postLead-packsConfirm","summary":"Not yet available: answers 403 NOT_YET_AVAILABLE until lead pulls open. After paying, credit the pack to the lead balance. Credits once however often it is called; a pack already paid is always credited.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checkoutSessionId":{"type":"string","description":"The checkoutSessionId the lead-packs response returned."}},"required":["checkoutSessionId"]},"example":{"checkoutSessionId":"cs_live_k9L8m7N6o5P4q3R2s1T0"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/lead-pulls":{"post":{"operationId":"postLead-pulls","summary":"Not yet available: answers 403 NOT_YET_AVAILABLE until lead pulls open. Reserve 1 to 10 leads from the prepaid balance for your stored ideal customer profile. 409 ICP_REQUIRED without a profile, 402 PAYMENT_REQUIRED when the balance is short. A lead is charged only when delivered; a reservation not delivered within 24 hours is returned to the balance.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","description":"Leads to reserve, 1 to 10."},"idempotencyKey":{"type":"string","description":"Your key for this pull, 8 to 128 characters. A repeat with the same key returns the first outcome and reserves nothing new."}},"required":["count","idempotencyKey"]},"example":{"count":5,"idempotencyKey":"pull-2026-11-16-0001"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}},"get":{"operationId":"getLead-pulls","summary":"Not yet available: there is no pull to read until lead pulls open. Report one pull (?id=<pullId>): state (queued, delivered or expired), requested, pending, delivered, released and when its reservation expires.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"description":"The pull id the lead-pulls POST returned.","schema":{"type":"string","description":"The pull id the lead-pulls POST returned."}}],"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/contacts/call-consent":{"post":{"operationId":"postContactsCall-consent","summary":"Record that a contact consented IN WRITING to automated-voice calls from your principal. The consent is tied to the contact's current number: a changed number needs a new attestation. Consent to texts does not count. 200 { consent: { contactId, consentAt, source, form, phoneLast4 } }. 422 WRITTEN_CONSENT_REQUIRED when form is not \"written\", 404 NOT_FOUND, 422 NOT_DIALABLE, 422 PHONE_NOT_US (calls go only to United States geographic numbers).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","description":"The id of one of your contacts."},"obtainedAt":{"type":"string","description":"When the consent was given: ISO 8601 with a time zone offset, not in the future."},"form":{"type":"string","description":"Must be \"written\". Automated-voice calls need written consent; any other value is refused."},"evidence":{"type":"string","description":"Where the written consent can be found (form, document, submission id): 20 to 2,000 characters, stored as given."}},"required":["contactId","obtainedAt","form","evidence"]},"example":{"contactId":"cm0examplecontact00000001","obtainedAt":"2026-11-16T15:04:05Z","form":"written","evidence":"Signed web form at example.com/consent, submission 1042, checkbox agreeing to automated calls from Example Widgets LLC."}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/email/domain":{"post":{"operationId":"postEmailDomain","summary":"Request the organization's one sending domain (.com, registered by us in our own account) and one mailbox, named for a person (not a shared role such as sales). A second request returns the first. Refused with 409 CANCELLATION_SCHEDULED once a cancellation is scheduled. 201 created, 200 already requested, 202 written but the registration is not confirmed yet. Setup then waits on steps our staff complete; GET /email names the step.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"A registrable .com name that is not already in use, e.g. example-mail.com."},"mailbox":{"type":"object","properties":{"localPart":{"type":"string","description":"The part of the mailbox address before the @: letters, digits and . - _ ' only."},"displayName":{"type":"string","description":"The sender name: a first and a last name."}},"required":["localPart","displayName"]},"rootRedirectTarget":{"type":"string","description":"Where the bare domain forwards a browser, an http(s) URL. Defaults to the website given at signup."},"idempotencyKey":{"type":"string","description":"A key you choose for this request, 8 to 128 characters: letters, digits, dot, underscore or hyphen. A key that finished answers its first outcome."}},"required":["domain","mailbox","idempotencyKey"]},"example":{"domain":"example-widgets-mail.com","mailbox":{"localPart":"sam","displayName":"Sam Example"},"idempotencyKey":"email-domain-request-0001"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/email":{"get":{"operationId":"getEmail","summary":"The email setup: { domain: { name, status } | null, mailbox: { address, status, dailyCap, sentToday } | null, waitingOn }. waitingOn is one of registration, dns, mail_setup, signing_key, mailbox_connection, suspended, paused, reconnect_required, daily_cap, or null. Registration and DNS are ours to finish; mail setup, the signing key and the mailbox connection are done by our staff; suspended, paused and reconnect_required mean every send is refused until our staff act; daily_cap means today's warm-up limit is spent and comes back the next day. null with a domain means a send can go out now.","security":[{"bearerAuth":[]}],"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}},"/api/agent/v1/emails":{"post":{"operationId":"postEmails","summary":"Send one email from the organization's mailbox to a contact (a lead in this organization with an email address). Refused with 409 MAILBOX_NOT_READY until the mailbox is connected; every other refusal carries the send rule's own code. A replayed idempotencyKey returns the first outcome, so use a new key to try again. Uses one email_send from the allowance; the binding daily limit is the mailbox warm-up. Today a recipient is accepted only when the contact has a United States direct phone on record (its own line, not a company switchboard); every other recipient is refused with 422 CONSENT_BASIS_MISSING before anything is spent. A contact whose address is not yet verified is verified on its first send, using one screening_lookup: an unusable address is refused with 422 UNVERIFIED_RECIPIENT, and 500 VERIFICATION_UNAVAILABLE with a Retry-After header means retry later.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","description":"The id of a lead in this organization that has an email address."},"subject":{"type":"string","description":"Subject line, 1 to 200 characters."},"body":{"type":"string","description":"Plain text body, 1 to 20000 characters. The postal footer and an unsubscribe link are added."},"idempotencyKey":{"type":"string","description":"8 to 128 characters. A replayed key returns the first outcome and sends nothing."}},"required":["contactId","subject","body","idempotencyKey"]},"example":{"contactId":"clx0contact0example0001","subject":"Quick question about your service fleet","body":"Hi Pat,\n\nDo you schedule maintenance for more than ten vehicles a month?\n\nSam","idempotencyKey":"email-send-0001-pat"}}}},"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}},"get":{"operationId":"getEmails","summary":"List the organization's email messages, sent and received (replies included): direction, from, to, subject, text, time and thread, oldest first, paged on id.","security":[{"bearerAuth":[]}],"parameters":[{"name":"direction","in":"query","required":false,"description":"inbound or outbound.","schema":{"type":"string","description":"inbound or outbound."}},{"name":"contactId","in":"query","required":false,"description":"Only messages with this contact.","schema":{"type":"string","description":"Only messages with this contact."}},{"name":"cursor","in":"query","required":false,"description":"The nextCursor from the previous page.","schema":{"type":"string","description":"The nextCursor from the previous page."}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100 (default 25).","schema":{"type":"integer","description":"Page size, 1 to 100 (default 25)."}}],"responses":{"400":{"$ref":"#/components/responses/Refused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"2XX":{"description":"Success. A JSON document.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/OtherRefusal"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ai_<key>","description":"The API key returned once by the claim route, sent as Authorization: Bearer ai_<key>."}},"schemas":{"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"A plain sentence saying what went wrong."},"code":{"type":"string","description":"A stable machine-readable code."}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"OtherRefusal":{"description":"Any other refusal. The body is { error, code }; the code is stable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Refused":{"description":"The request body or parameters were refused (code VALIDATION_FAILED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}