Agent API

Overview

The Sulta AI Agent API lets you list agents in your account and send messages to any agent by ID. All requests are authenticated with your account API key. Responses can be returned as a single JSON payload or streamed back as plain text using HTTP chunked transfer encoding.

Authentication

Pass your API key in the X-API-Key header. Keys are prefixed sulta_sk_ and can be generated or rotated from Settings → API keys.

Keep keys secret. Do not expose them in client-side code or public repositories.

Returns all agents owned by the account tied to the supplied API key.

curl https://ai.sultatech.com/api/agents \
  -H "X-API-Key: sulta_sk_..."

[
  {
    "id": "agent_abc123",
    "name": "Support Bot",
    "type": "customer_support",
    "description": "Handles tier-1 support queries.",
    "isPublic": false
  },
  { ... }
]

Send a message to a specific agent. The agent's configured system prompt, context, guardrails, and enabled tools are applied automatically. Set stream: true to receive a streamed plain-text response.

curl -X POST https://ai.sultatech.com/api/agents/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sulta_sk_..." \
  -d '{
    "agentId": "agent_abc123",
    "message": "What is your return policy?",
    "stream": false
  }'

{
  "agentId": "agent_abc123",
  "message": "What is your return policy?",
  "stream": false,
  "newChat": true
}

{
  "content": "Our return policy allows returns within 30 days...",
  "model": "gemini-3-flash-preview",
  "usage": {
    "inputTokens": 241,
    "outputTokens": 73,
    "totalTokens": 314
  }
}

Streaming

Pass "stream": true to receive the response as an HTTP chunked stream. Each chunk is a plain-text fragment — concatenate them in order to reconstruct the full reply. There is no wrapper envelope or SSE framing.

const res = await fetch("https://ai.sultatech.com/api/agents/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "sulta_sk_..."
  },
  body: JSON.stringify({
    agentId: "agent_abc123",
    message: "Summarise this month's KPIs.",
    stream: true
  })
});

if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);

const reader = res.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Error codes

The API returns standard HTTP status codes. Error bodies are plain text.