Voicetta.
    Sign InGet Started

    Voicetta API

    Read API Reference

    Read Voicetta calls, messages, and completed conversations through the REST API. Includes authentication, pagination, filters, errors, rate limits, and backfills.

    On this page

    The REST API gives your product access to the same data that Voicetta sends through webhooks.

    Use it when you need:

    • conversation history
    • backfills
    • recovery after downtime
    • individual records
    • reports
    • an integration without webhooks

    Paths, parameters, and response bodies live in the API Reference. This page covers the rules that apply to every endpoint.

    Base URL

    text
    https://api.voicetta.com/v1

    Collections

    CollectionContainsWebhook event
    /v1/callsVoice callscall.started, call.completed
    /v1/messagesSMS and WhatsApp messagesmessage.received, message.sent
    /v1/threadsCompleted SMS and WhatsApp conversationsthread.completed
    /v1/assistantsAgents in this workspace—

    The same underlying objects are available through the API and webhooks.

    To start a call rather than read one, see Outbound Calls API. This page covers reading.

    Authentication

    Every request requires an API key.

    Create one in Settings → Developers.

    Send it as a bearer token:

    text
    Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxx

    Keys are shown once.

    If you lose a key, revoke it and create another one.

    Each key belongs to one workspace.

    Choosing what you can read

    API keys have their own field permissions.

    BlockContainsDefaultCollections
    callRecord id, workspace, assistant, timestampsAlwaysAll
    customerName, phone, email, language, countryOnAll
    costsCost breakdownOffAll
    transcriptTurn-by-turn transcriptOnCalls, threads
    analysisSummary, intent, outcome, sentimentOnCalls, threads
    evaluationsEvaluation resultsOnCalls, threads
    follow_upsFollow-up stateOffCalls, threads
    recordingRecording status and linkOnCalls
    performance_metricsSpeech, model, and voice latencyOffCalls
    config_snapshotAssistant configurationOffCalls

    You can further narrow a request with fields.

    For example:

    text
    ?fields=transcript

    Requesting a field your key is not allowed to read returns 403.

    Choosing what you can do

    Field permissions say how much of a call a key may see. Placing calls is a separate, opt-in permission.

    PermissionGrantsDefault
    Place outbound callsPOST /v1/callsOff

    Reading more of a call is a privacy decision; ringing a phone is a spending decision. The second is never implied by the first, so every key is read-only until you tick the box in Settings → Developers.

    Endpoints

    Request samples, parameters, and response codes for each path are in the API Reference.

    Pagination

    Use cursor pagination.

    Do not use offsets.

    bash
    cursor="" while :; do page=$(curl -sH "Authorization: Bearer $KEY" \ "https://api.voicetta.com/v1/calls?limit=100&cursor=$cursor") echo "$page" | jq -c '.calls[]' [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || break cursor=$(echo "$page" | jq -r '.next_cursor') done

    Three rules:

    1. Stop when has_more is false.
    2. Treat cursors as opaque strings.
    3. Do not construct or modify cursors.

    Errors

    The API uses standard HTTP status codes.

    StatusMeaning
    400Invalid request
    401Missing or invalid API key
    403Your key does not have access to the requested data
    404Record does not exist
    429Rate limit exceeded
    500Server error

    Error responses include a JSON body explaining the problem.

    Rate limits

    LimitScope
    1,000 requests per hourPer endpoint, per caller
    100 requests per secondBurst protection
    200 calls per hourPOST /v1/calls, per workspace
    10 requests per secondPOST /v1/calls burst protection

    If you are regularly hitting the hourly limit, use webhooks instead of polling.

    Backfilling history

    The REST API is also how you load data from before your webhook was enabled.

    For example:

    bash
    curl -H "Authorization: Bearer $KEY" \ "https://api.voicetta.com/v1/calls?limit=100&from=2026-08-01T00:00:00Z"

    Feed the results through the same processing logic as your webhook.

    The objects are the same.

    Make your handler idempotent so running a backfill more than once is safe.

    For a specific recovery window, use both from and to.

    Versioning

    All API paths use /v1.

    Within version 1, existing fields are stable.

    We add fields without breaking existing integrations.

    Breaking changes get a new version.

    The OpenAPI specification is available at:

    text
    /open-api

    Related pages