SDK/REST API

REST API

Direct REST API access for any language or platform. Build custom integrations with the Vouchstone API.

Base URL

All API requests should be made to:

https://www.vouchstone.ai/api/v1

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header:

curl -X GET "https://www.vouchstone.ai/api/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Agents

List Agents

GET/agents

curl -X GET "https://www.vouchstone.ai/api/v1/agents?tenant_id=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "agents": [
    {
      "id": "agent-123",
      "name": "Support Agent",
      "type": "support",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Create Agent

POST/agents

curl -X POST "https://www.vouchstone.ai/api/v1/agents?tenant_id=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "type": "assistant",
    "description": "A helpful assistant",
    "memory_types": ["semantic", "episodic"],
    "config": {
      "model": "claude-sonnet-4-6",
      "temperature": 0.7
    }
  }'

# Response
{
  "id": "agent-456",
  "name": "My Agent",
  "type": "assistant",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Chat with Agent

POST/agents/{agent_id}/chat

curl -X POST "https://www.vouchstone.ai/api/v1/agents/agent-456/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How can I help you today?",
    "session_id": "session-123"
  }'

# Response
{
  "id": "msg-789",
  "content": "I am here to assist you. What would you like to know?",
  "role": "assistant",
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 15,
    "total_tokens": 40
  },
  "created_at": "2024-01-15T10:31:00Z"
}

Memory

Add Memory

POST/memory-stores/entries?tenant_id=...

curl -X POST "https://www.vouchstone.ai/api/v1/memory-stores/entries?tenant_id=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_type": "semantic",
    "key": "customer-preference-agent-456",
    "content": "Important information to remember",
    "source": "manual",
    "metadata": {
      "category": "knowledge"
    },
    "tags": ["agent-456"]
  }'

# Response
{
  "id": "mem-001",
  "tenant_id": "YOUR_TENANT_ID",
  "memory_type": "semantic",
  "key": "customer-preference-agent-456",
  "content": "Important information to remember",
  "source": "manual",
  "metadata": {"category": "knowledge"},
  "tags": ["agent-456"],
  "importance_score": 0.5,
  "access_count": 0,
  "created_at": "2024-01-15T10:31:00Z",
  "updated_at": "2024-01-15T10:31:00Z"
}

Search Memory

POST/memory-stores/entries/search?tenant_id=...

curl -X POST "https://www.vouchstone.ai/api/v1/memory-stores/entries/search?tenant_id=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_type": "semantic",
    "query": "important information",
    "limit": 5
  }'

# Response
{
  "entries": [
    {
      "id": "mem-001",
      "content": "Important information to remember",
      "key": "customer-preference-agent-456",
      "metadata": {"category": "knowledge"}
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 5
}

Workflows

Execute Workflow

POST/workflows/{workflow_id}/execute

curl -X POST "https://www.vouchstone.ai/api/v1/workflows/wf-123/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "message": "Process this data",
      "data": {"key": "value"}
    }
  }'

# Response
{
  "execution_id": "exec-789",
  "status": "running",
  "started_at": "2024-01-15T10:32:00Z"
}

Error Responses

The API uses standard HTTP status codes. Error responses include a JSON body with details:

# 400 Bad Request
{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    {"field": "name", "message": "Name is required"}
  ]
}

# 401 Unauthorized
{
  "error": "unauthorized",
  "message": "Invalid or expired API key"
}

# 404 Not Found
{
  "error": "not_found",
  "message": "Agent not found"
}

# 429 Rate Limited
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 60
}

# 500 Internal Server Error
{
  "error": "internal_error",
  "message": "An unexpected error occurred"
}

Rate Limits

API requests are rate limited based on your plan:

Plan	Requests/min	Requests/day
Starter	60	10,000
Pro	300	100,000
Enterprise	Unlimited	Unlimited

Need an SDK?

We recommend using our official Python SDK for easier integration.

Python SDK