{ "openapi": "3.1.0", "info": { "title": "SIPCraft API", "version": "0.1.0", "description": "Phone numbers and calls for AI agents. Errors are RFC 9457 application/problem+json. Send Idempotency-Key on writes." }, "servers": [ { "url": "https://sipcraft.dev" } ], "security": [ { "bearer": [] } ], "paths": { "/v0/signup": { "post": { "summary": "Agent self sign-up (no auth). Body {email, agent_name?, use_case?}. Returns api_key once; account is pending_email until verified. 409 if the email has an account, 429 when rate-limited, 422 for disposable domains.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "agent_name": { "type": "string" }, "use_case": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/v0/email/verify": { "post": { "summary": "Verify the account email with the 6-digit code {code}; activates free on-net calling", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/email/resend": { "post": { "summary": "Send a new email verification code", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/account": { "get": { "summary": "Account overview: balance, KYC, limits", "x-scopes": [ "account:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/billing": { "get": { "summary": "Prepaid credit balance, packs, auto top-up and hard-cap settings", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/billing/ledger": { "get": { "summary": "Credit ledger entries (grants, purchases, usage, number fees)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/billing/settings": { "put": { "summary": "Update auto top-up (enabled, threshold_usd, pack_usd) and stop_outbound_at_zero", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/billing/checkout": { "post": { "summary": "Start Stripe Checkout for a credit pack {pack_usd: 5|10|20|50|100}; 503 while payments are not enabled", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/usage": { "get": { "summary": "Usage by SKU", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer" } } ] } }, "/v0/numbers/search": { "get": { "summary": "Search available numbers", "x-scopes": [ "numbers:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "area_code", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "toll_free", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ] } }, "/v0/numbers": { "get": { "summary": "List numbers", "x-scopes": [ "numbers:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "post": { "summary": "Buy a number (confirm:true required)", "x-scopes": [ "numbers:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "e164" ], "properties": { "e164": { "type": "string" }, "confirm": { "type": "boolean" } } } } } } } }, "/v0/numbers/{id}": { "patch": { "summary": "Configure routing / CNAM", "x-scopes": [ "numbers:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberConfig" } } } } }, "delete": { "summary": "Release a number", "x-scopes": [ "numbers:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "confirm", "in": "query", "schema": { "type": "boolean" } } ] } }, "/v0/numbers/{id}/e911": { "put": { "summary": "Set E911 address", "x-scopes": [ "numbers:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } } } }, "/v0/calls": { "get": { "summary": "List calls", "x-scopes": [ "calls:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "post": { "summary": "Place an outbound call (KYC + consent required)", "x-scopes": [ "calls:outbound" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceCall" } } } } } }, "/v0/calls/{id}": { "get": { "summary": "Get a call", "x-scopes": [ "calls:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v0/calls/{id}/hangup": { "post": { "summary": "Hang up", "x-scopes": [ "calls:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v0/calls/{id}/transfer": { "post": { "summary": "Transfer (SIP REFER)", "x-scopes": [ "calls:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" } } } } } } } }, "/v0/calls/{id}/dtmf": { "post": { "summary": "Send DTMF", "x-scopes": [ "calls:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "digits": { "type": "string" } } } } } } } }, "/v0/calls/{id}/recording/start": { "post": { "summary": "Start recording", "x-scopes": [ "calls:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v0/calls/{id}/recording/stop": { "post": { "summary": "Stop recording", "x-scopes": [ "calls:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v0/recordings/{id}/url": { "get": { "summary": "Signed recording URL (15 min)", "x-scopes": [ "calls:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v0/events": { "get": { "summary": "Event log", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "since", "in": "query", "schema": { "type": "string" } } ] } }, "/v0/webhooks": { "get": { "summary": "List webhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "post": { "summary": "Create webhook (secret returned once)", "x-scopes": [ "webhooks:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "events": { "type": "string" } } } } } } } }, "/v0/webhooks/test": { "post": { "summary": "Send webhook.test", "x-scopes": [ "webhooks:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/webhooks/deliveries": { "get": { "summary": "Delivery log", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/trunks": { "post": { "summary": "Create SIP trunk credentials", "x-scopes": [ "numbers:write" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/verification": { "get": { "summary": "Get Verified status (powered by Didit)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "post": { "summary": "Start Get Verified (powered by Didit). Pass owner_email to invite your human owner; returns verify_url, message_for_human and instructions. notify_human:true also emails them.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_email": { "type": "string", "format": "email" }, "notify_human": { "type": "boolean" }, "kind": { "enum": [ "individual", "business" ] } } } } } } } }, "/v0/kyc": { "get": { "summary": "Alias of GET /v0/verification", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "post": { "summary": "Alias of POST /v0/verification", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/endpoints": { "get": { "summary": "List on-net endpoints", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "post": { "summary": "Create on-net endpoint (free)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "type": { "enum": [ "agent", "human_app", "sip_device" ] }, "name": { "type": "string" }, "display_name": { "type": "string" }, "route_type": { "enum": [ "websocket", "sip", "webhook" ] }, "route_target": { "type": "string" }, "accept_from": { "enum": [ "account", "anyone" ] } } } } } } } }, "/v0/endpoints/{id}": { "patch": { "summary": "Update endpoint", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "delete": { "summary": "Delete endpoint", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/onnet/limits": { "get": { "summary": "On-net fair-use usage and limits", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } }, "/v0/keys": { "get": { "summary": "List API keys", "x-scopes": [ "account:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } }, "post": { "summary": "Create scoped key", "x-scopes": [ "account:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/v0/keys/{id}": { "delete": { "summary": "Revoke key", "x-scopes": [ "account:read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/mcp": { "post": { "summary": "MCP Streamable HTTP endpoint (JSON-RPC 2.0)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } }, "responses": { "Problem": { "description": "RFC 9457 problem", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } } } } } } }, "schemas": { "NumberConfig": { "type": "object", "properties": { "route_type": { "enum": [ "webhook", "websocket", "sip", "callcraft" ] }, "route_target": { "type": "string" }, "cnam": { "type": "string", "maxLength": 15 } } }, "Address": { "type": "object", "required": [ "street", "city", "state", "zip" ], "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } } }, "PlaceCall": { "type": "object", "required": [ "from", "to", "consent_attestation" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "stream_url": { "type": "string", "format": "uri" }, "max_seconds": { "type": "integer" }, "consent_attestation": { "type": "object", "required": [ "has_consent", "basis" ], "properties": { "has_consent": { "const": true }, "basis": { "enum": [ "prior_express_consent", "existing_relationship", "callee_requested", "internal" ] }, "note": { "type": "string" } } } } } } } }