{ "info": { "name": "Saperly — mcp.ai", "description": "REST API for the Saperly MCP. Set {{apiKey}} to a workspace key (sk_live_…) created at https://mcp.ai/settings/api-keys.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://api.mcp.ai/api/saperly", "type": "string" }, { "key": "apiKey", "value": "sk_live_...", "type": "string" } ], "item": [ { "name": "saperly_assign_number_connection", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/assign/number/connection", "host": [ "{{baseUrl}}" ], "path": [ "assign", "number", "connection" ] }, "description": "Attach a connection (the AI persona / answering brain from SAPERLY_CREATE_CONNECTION) to a phone number, so inbound calls and SMS to that number — and outbound calls placed from it — are handled by th", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"connectionId\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_check_consent", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/check/consent", "host": [ "{{baseUrl}}" ], "path": [ "check", "consent" ] }, "description": "Check whether a contact currently has active TCPA consent for one of your Saperly numbers, given numberId (your number) and peerNumber (the contact's E.164 number) as query params. Returns {hasConsent", "body": { "mode": "raw", "raw": "{\n \"numberId\": \"\",\n \"peerNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_create_connection", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/create/connection", "host": [ "{{baseUrl}}" ], "path": [ "create", "connection" ] }, "description": "Create a connection: the AI 'brain' that answers calls and (optionally) SMS on a Saperly phone number. A phone number binds to a connection via SAPERLY_ASSIGN_NUMBER_CONNECTION in order to answer call", "body": { "mode": "raw", "raw": "{\n \"llm\": {},\n \"tts\": {},\n \"mode\": \"\",\n \"name\": \"\",\n \"language\": \"\",\n \"disclosure\": \"\",\n \"mcpServers\": \"\",\n \"callControl\": {},\n \"instructions\": \"\",\n \"smsAutoReply\": false,\n \"idempotency_key\": \"\",\n \"manualWebhookUrl\": \"\",\n \"complianceEnabled\": false\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_delete_connection", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/delete/connection", "host": [ "{{baseUrl}}" ], "path": [ "delete", "connection" ] }, "description": "PERMANENTLY AND IRREVERSIBLY delete a connection (the AI answering brain / persona that handles calls and SMS) by its id. THIS CANNOT BE UNDONE — there is no restore. WARNING: any phone number current", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_end_call", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/end/call", "host": [ "{{baseUrl}}" ], "path": [ "end", "call" ] }, "description": "End an in-progress call by its id, hanging up and settling the metered cost. This is the safe, cheap, RECOMMENDED companion to SAPERLY_PLACE_CALL: placing a call starts per-minute billing, and this to", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_get_call", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/get/call", "host": [ "{{baseUrl}}" ], "path": [ "get", "call" ] }, "description": "Fetch a single call by its id, returning its status, per-minute rate, final duration (durationSec) and cost (costCents), and the hasRecording / hasTranscript flags. costCents and durationSec are NULL ", "body": { "mode": "raw", "raw": "{\n \"id\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_get_call_recording", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/get/call/recording", "host": [ "{{baseUrl}}" ], "path": [ "get", "call", "recording" ] }, "description": "Get the audio recording for a call and return it as a downloadable file. The API answers with a 302 redirect to a signed download URL when a recording exists; the recording is fetched and returned as ", "body": { "mode": "raw", "raw": "{\n \"id\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_get_call_transcript", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/get/call/transcript", "host": [ "{{baseUrl}}" ], "path": [ "get", "call", "transcript" ] }, "description": "Fetch the transcript (conversation turns/segments) of a completed call by its id. Transcripts only exist AFTER a call connects, ends, and is processed. The endpoint uses the same 404 for an unknown ca", "body": { "mode": "raw", "raw": "{\n \"id\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_get_connection", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/get/connection", "host": [ "{{baseUrl}}" ], "path": [ "get", "connection" ] }, "description": "Fetch a single connection (the AI answering brain / persona that handles calls and SMS) by its id, returning its full config: name, mode, backend, instructions, tts voice, language, compliance/disclos", "body": { "mode": "raw", "raw": "{\n \"id\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_get_number", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/get/number", "host": [ "{{baseUrl}}" ], "path": [ "get", "number" ] }, "description": "Fetch a single phone number by its id, returning its E.164 phoneNumber, bound connectionId, webhookUrl, country, numberType, pricing and lifecycle fields. Use after SAPERLY_LIST_NUMBERS to inspect one", "body": { "mode": "raw", "raw": "{\n \"id\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_get_usage", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/get/usage", "host": [ "{{baseUrl}}" ], "path": [ "get", "usage" ] }, "description": "Return the workspace usage summary and prepaid balance: calls {count, totalCostCents, totalDurationSec}, messages {count}, and balanceCents (the prepaid balance, in cents). ALWAYS call this before any", "body": { "mode": "raw", "raw": "{\n \"since\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_list_calls", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/list/calls", "host": [ "{{baseUrl}}" ], "path": [ "list", "calls" ] }, "description": "Return the full voice-call history (inbound + outbound) for the connected Saperly workspace. Each call carries its id, numberId, direction, to and from_number (E.164), status, rateCentsPerMin, duratio", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_list_connections", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/list/connections", "host": [ "{{baseUrl}}" ], "path": [ "list", "connections" ] }, "description": "Return every connection (the AI persona / answering 'brain' that handles calls and SMS) in the connected Saperly workspace. Each carries id, name, mode (hosted|manual), backend, instructions, llm, tts", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_list_consent", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/list/consent", "host": [ "{{baseUrl}}" ], "path": [ "list", "consent" ] }, "description": "Return every TCPA consent record in the connected Saperly workspace, with each record's id, numberId (the Saperly number contact is authorized FROM), peerNumber (the contact's E.164 number), consentTy", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_list_languages", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/list/languages", "host": [ "{{baseUrl}}" ], "path": [ "list", "languages" ] }, "description": "Return the spoken languages Saperly supports for voice connections, each as a {code, name} pair (about 42 entries, e.g. {'code':'en','name':'English'}). A language `code` is what you pass as a connect", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_list_messages", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/list/messages", "host": [ "{{baseUrl}}" ], "path": [ "list", "messages" ] }, "description": "Return SMS messages in the connected Saperly workspace (both inbound and outbound). Each message has id, numberId, direction, to, from_number, body, segments, status and createdAt. Pass `numberId` to ", "body": { "mode": "raw", "raw": "{\n \"numberId\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_list_numbers", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/list/numbers", "host": [ "{{baseUrl}}" ], "path": [ "list", "numbers" ] }, "description": "Return every phone number provisioned in the connected Saperly workspace, with each number's id, phoneNumber (E.164), the connectionId (answering brain) bound to it, webhookUrl, country, numberType, m", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_list_voices", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/list/voices", "host": [ "{{baseUrl}}" ], "path": [ "list", "voices" ] }, "description": "List the text-to-speech voices available for Saperly connections. Each voice has an id, name, gender and language; a voice id is what you pass as tts.voiceId when creating or updating a connection (SA", "body": { "mode": "raw", "raw": "{\n \"language\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_place_call", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/place/call", "host": [ "{{baseUrl}}" ], "path": [ "place", "call" ] }, "description": "PAID / METERED — places a REAL outbound voice call that RINGS A REAL PHONE and BILLS PER MINUTE (~26¢/min); it keeps billing until hung up — end it with SAPERLY_END_CALL to stop the meter. Calls FROM ", "body": { "mode": "raw", "raw": "{\n \"to\": \"\",\n \"connectionId\": \"\",\n \"fromNumberId\": \"\",\n \"instructions\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_provision_number", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/provision/number", "host": [ "{{baseUrl}}" ], "path": [ "provision", "number" ] }, "description": "PAID / METERED: provision (buy) a new phone number in a country. This SPENDS MONEY — it charges the workspace prepaid balance an upfront fee plus a RECURRING MONTHLY rent (US local ~ $1.79/mo, varies ", "body": { "mode": "raw", "raw": "{\n \"country\": \"\",\n \"areaCode\": \"\",\n \"numberType\": \"\",\n \"idempotency_key\": \"\",\n \"approveHigherPrice\": false,\n \"expectedMonthlyPriceCents\": 0,\n \"expectedUpfrontPriceCents\": 0\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_quote_number_price", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/quote/number/price", "host": [ "{{baseUrl}}" ], "path": [ "quote", "number", "price" ] }, "description": "READ-ONLY and FREE: quote the price to provision a phone number in a country/type, returning { customerMonthlyCents, customerUpfrontCents }. This DOES NOT provision, reserve, or charge anything — desp", "body": { "mode": "raw", "raw": "{\n \"country\": \"\",\n \"numberType\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_record_consent", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/record/consent", "host": [ "{{baseUrl}}" ], "path": [ "record", "consent" ] }, "description": "Record TCPA consent for a contact so outbound SMS (SAPERLY_SEND_SMS) and calls (SAPERLY_PLACE_CALL) from your number are permitted. Saperly's compliance gate: for a cold contact call this BEFORE sendi", "body": { "mode": "raw", "raw": "{\n \"source\": \"\",\n \"numberId\": \"\",\n \"peerNumber\": \"\",\n \"consentType\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_release_number", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/release/number", "host": [ "{{baseUrl}}" ], "path": [ "release", "number" ] }, "description": "PERMANENTLY AND IRREVERSIBLY release a phone number back to the carrier. THIS CANNOT BE UNDONE: the number leaves the workspace, is returned to the carrier pool, and CANNOT be recovered or reclaimed. ", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_revoke_consent", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/revoke/consent", "host": [ "{{baseUrl}}" ], "path": [ "revoke", "consent" ] }, "description": "Revoke a contact's TCPA consent for a given Saperly number, blocking further outbound contact to them. CALL THIS WHEN A RECIPIENT SAYS 'STOP' / 'UNSUBSCRIBE' / 'do not contact me' — honoring an opt-ou", "body": { "mode": "raw", "raw": "{\n \"numberId\": \"\",\n \"peerNumber\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_send_sms", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/send/sms", "host": [ "{{baseUrl}}" ], "path": [ "send", "sms" ] }, "description": "PAID / METERED: send a single SMS from one of your Saperly numbers to an E.164 destination. This SPENDS REAL MONEY and sends a REAL text message to a REAL phone (~2 cents per 160-character segment; a ", "body": { "mode": "raw", "raw": "{\n \"to\": \"\",\n \"body\": \"\",\n \"fromNumberId\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_set_number_caller_id", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/set/number/caller/id", "host": [ "{{baseUrl}}" ], "path": [ "set", "number", "caller", "id" ] }, "description": "Set the outbound caller ID name / CNAM (1-15 characters: letters, digits, spaces) presented to recipients on outbound calls from a Saperly phone number, or pass callerIdName=null to CLEAR it. callerId", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"callerIdName\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_set_number_sms_sender", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/set/number/sms/sender", "host": [ "{{baseUrl}}" ], "path": [ "set", "number", "sms", "sender" ] }, "description": "Set the alphanumeric SMS sender id (1-11 alphanumeric chars, e.g. a brand name) shown as the 'from' on outbound SMS from this number, or pass smsSenderId=null to CLEAR it. Returns the updated number o", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"smsSenderId\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_set_number_webhook", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/set/number/webhook", "host": [ "{{baseUrl}}" ], "path": [ "set", "number", "webhook" ] }, "description": "Set the HTTPS webhook URL that Saperly POSTs this number's events (inbound SMS/calls, status) to. The url is required and must be https://. Returns the updated number object. NOTE: this endpoint has n", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"url\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_transfer_call", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/transfer/call", "host": [ "{{baseUrl}}" ], "path": [ "transfer", "call" ] }, "description": "PAID / METERED — BLIND-transfers a LIVE, in-progress voice call to another destination `to` (an E.164 number like +15551230000, or a `sip:` URI). BLIND means the call is handed off UNCONDITIONALLY: th", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"to\": \"\",\n \"idempotency_key\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "saperly_update_connection", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/update/connection", "host": [ "{{baseUrl}}" ], "path": [ "update", "connection" ] }, "description": "Partially update a connection (the AI answering brain bound to a number). Send only the fields you want to change (name, mode, instructions, llm, tts, language, mcpServers, callControl, complianceEnab", "body": { "mode": "raw", "raw": "{\n \"id\": \"\",\n \"llm\": {},\n \"tts\": {},\n \"mode\": \"\",\n \"name\": \"\",\n \"language\": \"\",\n \"disclosure\": \"\",\n \"mcpServers\": \"\",\n \"callControl\": {},\n \"instructions\": \"\",\n \"smsAutoReply\": false,\n \"idempotency_key\": \"\",\n \"manualWebhookUrl\": \"\",\n \"complianceEnabled\": false\n}", "options": { "raw": { "language": "json" } } } } } ] }