Skip to main content

Getting started

Base URL​

https://convostack.ai/api

Authentication​

If you're integrating from outside Meldcore's own infrastructure, use an API key, not a login token. Generate one from the dashboard:

Settings → API Keys → Generate new key.

The raw key is shown exactly once — copy it somewhere safe (a secrets manager, an env var). If you lose it, revoke it and generate a new one; there is no way to retrieve a lost key.

Send it as a bearer token on every request:

curl https://convostack.ai/api/agents \
  -H "Authorization: Bearer cak_live_..."

An API key is scoped to the organization that created it. Every call you make with it sees and affects only that organization's data — agents, calls, credits, everything — the same as if you'd logged into the dashboard as that org.

Revoking a key

Settings → API Keys → Revoke on the key you no longer trust. Revocation is immediate — the very next request with that key returns 401.

Internal Meldcore auth (not for external integrations)​

ConvoStack also accepts the standard Meldcore session bearer token (the same one the dashboard uses):

curl https://convostack.ai/api/agents \
  -H "Authorization: Bearer $ACCESS_TOKEN"
warning

This session token is for the dashboard, not external integrations — use an API key instead.

Your first call​

A minimal, complete round trip: create an agent, then place a call through it.

# 1. Create an agent
curl -X POST https://convostack.ai/api/agents \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "firstMessage": "Hi, thanks for calling — how can I help?",
    "systemPrompt": "You are a friendly support agent for Acme Inc."
  }'
# → { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "draftVersionNumber": 1, ... }

# 2. Publish it — the draft becomes the live version
curl -X POST https://convostack.ai/api/agents/a1b2c3d4-5678-90ab-cdef-1234567890ab/publish \
  -H "Authorization: Bearer cak_live_..."

# 3. Place an outbound call through it
curl -X POST https://convostack.ai/api/phone/call \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }'
# → { "callSid": "CA...", "status": "call_initiated", "fromNumber": "+1...", "callId": "..." }

Agents are created as a draft — see Agents for the draft/publish lifecycle and why it exists.

Trying the API interactively​

The API Reference is interactive — every endpoint has a Test Request button that issues a real call from your browser. Paste your API key into the auth panel first (the lock icon on any endpoint).

What's next​

  • Authentication — API key scopes, rotation, and what a key can and can't do
  • Agents — the draft/publish model, presets, and tool binding
  • Calls & campaigns — placing one call vs. running a campaign against many numbers
  • Errors — the error response shape and how to handle it
  • Rate limits — per-org throttling, especially on call-placing endpoints