---
title: API overview
description: Public VaniAgent API resources, conventions, and machine-readable schema.
---

import Endpoint from '../../../components/Endpoint.astro';

The Developer API controls supported VaniAgent resources programmatically.

**Base URL:** `https://api.vaniagent.com`  
**Authentication:** `X-API-Key`  
**Schema:** [/openapi-public.yaml](/openapi-public.yaml)

The published schema is curated from the deployed FastAPI contract. Dashboard, admin, OAuth, provider credential, and private integration routes are excluded.

## Resources

<Endpoint method="GET" path="/api/developer/v1/agents" title="Agents">
  Create and configure conversation agents.
</Endpoint>
<Endpoint method="POST" path="/api/developer/v1/calls" title="Calls">
  Initiate and inspect direct calls; bulk initiation is also supported.
</Endpoint>
<Endpoint method="POST" path="/api/developer/v1/contacts" title="Contacts">
  Upsert Contacts individually or in batches of up to 100.
</Endpoint>
<Endpoint method="POST" path="/api/developer/v1/campaigns" title="Campaigns">
  Create uploaded-audience campaigns and control their lifecycle.
</Endpoint>
<Endpoint method="GET" path="/api/developer/v1/knowledge" title="Knowledge">
  Maintain text knowledge sources used by agents.
</Endpoint>
<Endpoint method="POST" path="/api/developer/v1/widget/session" title="Web widget">
  Create short-lived voice-widget sessions.
</Endpoint>

## Conventions

- IDs are opaque strings; never derive meaning from their format.
- Timestamps are returned in the API's documented ISO format.
- List endpoints may evolve with pagination or filters; preserve unknown fields.
- A successful request does not guarantee a phone provider later connects the call.
- Use idempotent application logic around contacts and webhook processing.