Agent API

Setup — API key required

1. 1Go to EvoStudio → Instance and scroll to External API Keys.
2. 2Click Create Key — copy the sk-oc-… key immediately (it is shown only once).
3. 3Install the agent package, then in the first message provide your key and base URL:

My API key is sk-oc-abc123... and my app URL is https://chraft.ai

The agent saves both to session memory and reuses them for every subsequent call.

What the agent can do

Prerequisites

Authentication

Include your API key as a Bearer token in every request:

Authorization: Bearer sk-oc-<your-key>

POST /api/evostudio/chat — single response

Send a message and receive the complete reply in one JSON response. Best for scripts and server-side calls.

Request body

{
  "message":    "string (required)",
  "sessionKey": "string (optional) — omit to start a fresh session",
  "history": [
    { "role": "user" | "assistant" | "system", "content": "string" }
  ]
}

Success response 200

{
  "success":    true,
  "reply":      "The agent's text response",
  "sessionKey": "your-session-key-or-null",
  "usage": {
    "prompt_tokens":     120,
    "completion_tokens": 45,
    "total_tokens":      165
  }
}

Error responses

Example — curl

curl -X POST https://your-app.com/api/evostudio/chat \
  -H "Authorization: Bearer sk-oc-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?", "sessionKey": "sess-001"}'

Example — Node.js

const res = await fetch('/api/evostudio/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-oc-abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: 'Hello!', sessionKey: 'sess-001' }),
});
const { reply } = await res.json();

Example — Python

import requests

resp = requests.post(
    "https://your-app.com/api/evostudio/chat",
    headers={"Authorization": "Bearer sk-oc-abc123..."},
    json={"message": "Hello!", "sessionKey": "sess-001"},
)
print(resp.json()["reply"])

POST /api/evostudio/chat/stream — SSE streaming

Same request body as above. Returns a text/event-stream response that streams tokens as they arrive.

Event types

Example — curl

curl -N -X POST https://your-app.com/api/evostudio/chat/stream \
  -H "Authorization: Bearer sk-oc-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Write a haiku about AI"}'

Example — browser fetch

const res = await fetch('/api/evostudio/chat/stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-oc-abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: 'Tell me a story' }),
});

const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop() ?? '';
  let event = '';
  for (const line of lines) {
    if (line.startsWith('event:')) event = line.slice(6).trim();
    else if (line.startsWith('data:')) {
      const payload = JSON.parse(line.slice(5).trim());
      if (event === 'delta') process.stdout.write(payload.text);
    }
  }
}

Session management

Pass the same sessionKey across multiple requests to maintain conversation context. Omit it (or use a new value) to start a fresh session. Sessions are scoped to the workspace that owns the API key.

Which endpoint to use?