{"openapi":"3.1.0","info":{"title":"Agentline API","version":"1.1.0","description":"Real New Zealand phone numbers and email inboxes for AI agents.","contact":{"email":"support@agentline.nz"}},"servers":[{"url":"https://agentline.nz/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key (al_live_…)"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"paths":{"/me":{"get":{"summary":"Account, numbers, inboxes and usage","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"}}}},"/sms":{"get":{"summary":"List SMS","parameters":[{"name":"direction","in":"query","schema":{"type":"string"}},{"name":"contact","in":"query","schema":{"type":"string"}},{"name":"unread_only","in":"query","schema":{"type":"string"}},{"name":"since_seconds","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Send SMS","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","body"],"properties":{"to":{"type":"string"},"body":{"type":"string","maxLength":1600},"from":{"type":"string"}}}}}},"responses":{"201":{"description":"Sent"},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/sms/{id}":{"get":{"summary":"Read SMS","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/Error"}}}},"/emails":{"get":{"summary":"List emails","parameters":[{"name":"direction","in":"query","schema":{"type":"string"}},{"name":"unread_only","in":"query","schema":{"type":"string"}},{"name":"since_seconds","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Send email","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","subject","text"],"properties":{"to":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"maxItems":5}]},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"from":{"type":"string"},"reply_to_id":{"type":"string"}}}}}},"responses":{"201":{"description":"Sent"},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/emails/{id}":{"get":{"summary":"Read email (doesn't change read state)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/Error"}}}},"/mark-read":{"post":{"summary":"Mark SMS and emails read, or unread","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100},"read":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"updated and notFound ids"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/emails/{id}/raw":{"get":{"summary":"Original RFC 822 message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"message/rfc822"}}}},"/wait-for-code":{"post":{"summary":"Wait for a one-time code by SMS or email","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"enum":["sms","email","any"]},"timeout_seconds":{"type":"integer","maximum":55},"from_contains":{"type":"string"},"since_seconds":{"type":"integer"}}}}}},"responses":{"200":{"description":"{found:boolean, code?, channel?, from?, receivedAt?}"}}}},"/calls":{"get":{"summary":"List calls","responses":{"200":{"description":"OK"}}},"post":{"summary":"Place a call that speaks a message (Pro, feature-flagged)","responses":{"201":{"description":"Queued"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/signup":{"post":{"summary":"Agent self-signup (no auth, one call). Returns a working account straight away and emails the owner a verification link. Opening that link gives the key full use of the account. Until then it can only read GET /me and message the owner's verified email or mobile; every other endpoint returns 403 key_not_confirmed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"owner_email":{"type":"string","format":"email"},"owner_mobile":{"type":"string","description":"NZ mobile, e.g. 021 123 4567"},"agent_name":{"type":"string","maxLength":60}},"required":["owner_email"]}}}},"responses":{"201":{"description":"{account_id, api_key, inbox, plan, owner, verification, restrictions, mcp_url, mcp: {url, headers, config}, upgrade, timings_ms}"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/voice":{"get":{"summary":"Voice settings for each number","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"}}}},"/voice/{number_id}":{"patch":{"summary":"Update call handling for a number","parameters":[{"name":"number_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["message","forward_sip","stream","forward_phone"]},"target":{"type":"string"},"greeting":{"type":"string"},"voicemail_enabled":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/keys":{"get":{"summary":"List API keys","responses":{"200":{"description":"OK"}}},"post":{"summary":"Create an API key (secret returned once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":60}},"required":["name"]}}}},"responses":{"201":{"description":"Created"},"400":{"$ref":"#/components/responses/Error"}}}},"/keys/{id}":{"delete":{"summary":"Revoke an API key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked"},"404":{"$ref":"#/components/responses/Error"}}}},"/owner/verify":{"post":{"summary":"Confirm the owner's mobile with the 6-digit code Agentline texted them at signup (only the emailed link verifies the account)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"]}}}},"responses":{"200":{"description":"{phoneVerified, ownerVerified, phone}"},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/owner/phone":{"post":{"summary":"Start owner mobile verification: returns a code the owner texts from their phone to the agent's number","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string"}},"required":["phone"]}}}},"responses":{"200":{"description":"{phone, code, textTo, expiresAt, instructions}"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/audit":{"get":{"summary":"Recent audit log entries","responses":{"200":{"description":"OK"}}}},"/billing":{"get":{"summary":"Plan, status, trial and allowances","responses":{"200":{"description":"OK"}}}},"/billing/checkout":{"post":{"summary":"Emails the owner a Stripe Checkout link to start a paid plan, and returns it","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","pro"]}},"required":["plan"]}}}},"responses":{"200":{"description":"{url, sent_to}"},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/billing/portal":{"post":{"summary":"Stripe Customer Portal URL, also emailed to the owner. Plan changes or cancellation in the next 24 hours are emailed to the owner.","responses":{"200":{"description":"{url, sent_to}"},"400":{"$ref":"#/components/responses/Error"}}}}}}