API Reference

The Simple Agent REST API lets you manage agents, sources, and conversations programmatically.

Base URL: https://simple-agent.me/api/v1

---

Authentication

All requests use a Bearer token in the Authorization header:

curl https://simple-agent.me/api/v1/agents \
  -H "Authorization: Bearer af_live_xxxxxxxxxxxxxxxxxxxx"

Create your API key in Settings → API → Generate key.

Available scopes:

• agents:read — list and read agents
• agents:write — create and edit agents
• sources:write — add and remove sources
• conversations:read — read conversation history
• webhooks:write — manage webhooks

---

Agents

List agents

GET /v1/agents

Response:

{
  "data": [
    {
      "id": "ag_01HXxxxxxx",
      "name": "Main Support",
      "status": "active",
      "sources_count": 12,
      "messages_this_month": 1847,
      "created_at": "2026-05-01T10:00:00Z"
    }
  ],
  "total": 1,
  "has_more": false
}

Create agent

POST /v1/agents
Content-Type: application/json

{
  "name": "Sales Support",
  "welcome_message": "Hi! How can I help with your purchase?",
  "tone": "balanced",
  "fallback_message": "Let me connect you with our team."
}

---

Sources

Add URL source

POST /v1/agents/{agent_id}/sources
Content-Type: application/json

{
  "type": "url",
  "url": "https://yoursite.com/faq",
  "crawl_depth": 2,
  "refresh_every_days": 7
}

Response:

{
  "id": "src_01HXxxxxxx",
  "status": "processing",
  "estimated_chunks": 340,
  "webhook_on_complete": null
}

Upload PDF

POST /v1/agents/{agent_id}/sources
Content-Type: multipart/form-data

file=@manual.pdf
type=pdf

Source status

GET /v1/agents/{agent_id}/sources/{source_id}

{
  "id": "src_01HXxxxxxx",
  "status": "ready",
  "chunks_count": 342,
  "last_crawled_at": "2026-05-10T14:22:00Z"
}

---

Conversations

List conversations

GET /v1/agents/{agent_id}/conversations?limit=20&cursor=xxx

Get conversation

GET /v1/agents/{agent_id}/conversations/{conversation_id}

Response:

{
  "id": "conv_01HXxxxxxx",
  "messages": [
    {
      "role": "user",
      "content": "What is the delivery time?",
      "created_at": "2026-05-10T15:00:00Z"
    },
    {
      "role": "assistant",
      "content": "The delivery time is 3–5 business days...",
      "citations": [
        {
          "source_id": "src_01HXxxxxxx",
          "chunk_offset": 847,
          "text": "...delivery time is 3–5 business days...",
          "url": "https://yoursite.com/faq#delivery",
          "confidence": 0.94
        }
      ],
      "fcs_score": 0.94,
      "latency_ms": 823
    }
  ]
}

---

Webhooks

Configure webhooks to receive real-time events.

Create webhook

POST /v1/webhooks
Content-Type: application/json

{
  "url": "https://yoursite.com/webhooks/simple-agent",
  "events": ["conversation.created", "source.ready", "source.failed"],
  "secret": "your-hmac-secret"
}

Verify signature

Each request includes the X-Simple Agent-Signature header:

X-Simple Agent-Signature: t=1715000000,v1=abc123def456...

Verify with HMAC SHA-256:

import crypto from "crypto";

function verifySignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const [, timestamp] = signature.split(",t=").at(0)?.split("t=") ?? [];
  const [, v1] = signature.split(",v1=");

  const signed = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(v1, "hex"),
    Buffer.from(expected, "hex")
  );
}

---

Rate limits

Plan	Requests/min	Burst
Free	10	20
Starter	60	100
Growth	300	500
Agency	1,000	2,000
Scale	5,000	10,000

Rate limit headers returned with every response:

• X-RateLimit-Limit: plan limit
• X-RateLimit-Remaining: remaining requests in the current minute
• X-RateLimit-Reset: Unix timestamp when the limit resets

---

Errors

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 30 seconds.",
    "retry_after": 30
  }
}

HTTP code	Meaning
400	Invalid parameter
401	Invalid or expired API key
403	Insufficient permissions (scope)
404	Resource not found
429	Rate limit exceeded
500	Internal error