Build with Samvaad Agents.
A look at the developer experience we're building: how agents are configured, how conversations flow, and how your systems plug in. The API is in development; examples here are proposals, not live endpoints.
conversation.started
turn.completed
Repeated per exchange
tool.called
With inputs and result
conversation.escalated or conversation.completed
The API described on this page is a proposal under development. Endpoints, fields and behavior may change before release. Nothing here is a working endpoint.
Create an agent
An agent is declared as data: what it may say, what it may use, and when it must hand over.
POST /v1/agents
Authorization: Bearer <api key>
Content-Type: application/json
{
"name": "Customer Support Agent",
"channel": "voice",
"instructions": "Answer questions using approved company information. Transfer to a person if asked.",
"knowledge_sources": ["ks_help_center"],
"tools": ["lookup_order", "create_ticket"],
"escalation": { "on_request": true, "on_low_confidence": true }
}Receive a webhook
Your endpoint gets a signed event when something happens. Verify the signature before trusting the body.
POST https://example.com/webhooks/samvaad
X-Samvaad-Signature: sha256=<hmac of body>
{
"type": "conversation.completed",
"conversation_id": "conv_8f2a",
"agent_id": "agt_support",
"channel": "voice",
"outcome": "resolved",
"summary": "Caller rescheduled appointment to Wednesday 14:00.",
"tool_calls": [{ "tool": "reschedule_appointment", "status": "ok" }]
}Define a tool
A tool is a documented capability with a schema. Credentials are referenced, never inlined.
{
"name": "lookup_order",
"description": "Fetch the status of an order by order number.",
"input_schema": {
"type": "object",
"properties": { "order_number": { "type": "string" } },
"required": ["order_number"]
},
"endpoint": "https://api.example.com/orders/{order_number}",
"auth": "secret_ref:orders_api_key",
"requires_approval": false
}Concepts
The vocabulary of the platform, in the order you'd meet it.
Authentication
Requests are authenticated with per-environment API keys sent as a bearer token. Keys are created and revoked in a dashboard and never embedded in client-side code.
Agent configuration
An agent is a named configuration: channel, instructions, knowledge sources, tools and escalation rules. Versioned, so changes can be reviewed and rolled back.
Conversation lifecycle
A conversation starts when a channel delivers a message or call, moves through turns and tool calls, and ends as resolved, escalated or abandoned. Each state change can emit a webhook.
Webhooks
Signed HTTPS callbacks for conversation events. Verify the signature, respond quickly, and process asynchronously. Retries use exponential backoff.
Tool integrations
A tool is a documented capability with a JSON schema for inputs and a secret reference for authentication. Tools can require human approval before they run.
Error handling
Standard HTTP status codes with a machine-readable error body: a stable code, a human message, and a request ID for support.
Rate limits
Per-key limits with headers that report remaining quota. Limits will be documented once the API is generally available.
Security practices
Least-privilege keys, secret references instead of inline credentials, signed webhooks, and audit logs for every tool call.
Want early access to the API?
Tell us what you'd build. Early-access partners help shape the endpoints before they're fixed.