Agent API Overview

Talk to any deployed DataGen agent over an Anthropic-compatible streaming endpoint

Every DataGen agent exposes an Anthropic Messages-compatible endpoint. Point the official Anthropic SDK — or plain curl — at your agent and it answers as a streaming chat completion.

POST {base-url}/api/agents/{agent-name}/v1/messages
GET  {base-url}/api/agents/{agent-name}/v1/models

{base-url} is https://api.datagen.dev on DataGen Cloud, or http://<your-server-ip>:3001 if you self-host — see Base URL.

What runs behind it is a full agent session, not a bare model call: your agent’s files and repo, its skills, its MCP tools, and its secrets are all live inside a sandbox for the duration of the turn.

{agent-name} is the agent’s slug as shown on its detail page. Repo-backed agents use owner-repo (lowercase, / replaced by -), e.g. datagendev-executive-assistant. Storage-backed agents use the name you gave them, e.g. data-agent.

---

Base URL

Every example in this section uses the DataGen Cloud host. If you self-host, swap that host for your own server — the paths are identical.

Deployment	Base URL
DataGen Cloud	https://api.datagen.dev
Self-hosted	http://<server-ip>:3001
Self-hosted with TLS	https://<your-domain>

So the same endpoint, on each:

# DataGen Cloud
https://api.datagen.dev/api/agents/invoice-agent/v1/messages

# Self-hosted — your server's IP or hostname, port 3001
http://10.0.0.42:3001/api/agents/invoice-agent/v1/messages

# Self-hosted with TLS — same domain as the web UI, no port
https://datagen.example.com/api/agents/invoice-agent/v1/messages

Port 3001 is the API server, not the web UI. Your team opens DataGen on port 3000; integrations call 3001. Both are on the same machine. If your operator changed WASP_BACKEND_PORT in .env, use that port instead — it is whatever WASP_SERVER_URL in your .env points at.

With the TLS deployment profile, a reverse proxy serves the web UI and the API on one domain and forwards /api/* to the API server, so port 3001 is closed to the network and your base URL is simply your DataGen domain with no port.

Make the base URL a config value in your integration, not a literal. Moving between cloud and self-hosted, or putting TLS in front of an existing install, then changes one environment variable instead of every call site.

---

Your first call

1. Get an API key

   In DataGen, open Workspace Settings → API Keys and create a key. Create it in the same workspace as the agent you want to call — the key can only reach that workspace’s agents.

2. Send a message

   curl -N -X POST "https://api.datagen.dev/api/agents/data-agent/v1/messages" \
     -H "X-Api-Key: $DATAGEN_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "claude-haiku-4-5",
       "stream": true,
       "messages": [{"role": "user", "content": "What data sources can you reach?"}]
     }'
   
3. Keep the conversation id

   The response carries an X-Conversation-Id header. Send it back as metadata.conversation_id on the next call and the agent picks up exactly where it left off. See Conversations.

Two turns, end to end

The whole contract in one copy-pasteable script — ask something, then follow up in the same conversation:

cURL

BASE=https://api.datagen.dev
AGENT=data-agent

turn() {  # turn "<message>" [conversation-id]
  curl -sN -D /tmp/h -X POST "$BASE/api/agents/$AGENT/v1/messages" \
    -H "X-Api-Key: $DATAGEN_API_KEY" -H "Content-Type: application/json" \
    -d "$(jq -n --arg m "$1" --arg c "${2:-}" '{
          stream: true,
          messages: [{role: "user", content: $m}],
          metadata: (if $c == "" then {} else {conversation_id: $c} end)
        }')" |
  # Print the assistant text as it arrives.
  sed -n 's/^data: //p' | jq -rj 'select(.delta.type == "text_delta") | .delta.text'
}

turn "List the tables you can reach."
CONV=$(grep -i '^x-conversation-id' /tmp/h | tr -d '\r' | awk '{print $2}')

turn "Now show me the row count of the first one." "$CONV"

Three things in that script carry the whole contract: stream: true on every request, one user message per call (history comes from the conversation, not the array), and the conversation id read from the response header and sent back.

Sending turns back to back from a script — as above — can outrun the server’s bookkeeping and lose the previous turn’s context. Add a short wait between automated turns; see Resuming.

---

Three differences from the Anthropic API

The wire format matches Anthropic’s, so existing clients connect without changes. The semantics differ in three ways that matter.

Only the last user message is sent to the agent. The server reads the newest role: "user" text from messages[] and discards the rest. Conversation history lives on the server — pass metadata.conversation_id, don’t replay the array. A three-message array whose first message states a fact and whose last asks about it will get “I don’t know.”

Always stream. stream: false still returns text/event-stream. The official SDKs’ non-streaming call (messages.create() / client.messages.create) does not raise on the mismatch — it returns a Message object filled with misparsed text. Use messages.stream() and its equivalents.

Sampling parameters are ignored. The server reads messages, stream, model, system, and metadata. max_tokens, temperature, top_p, stop_sequences, tools, and tool_choice are accepted and dropped — max_tokens is not required. The agent uses its own configured tools; you cannot inject client-side tool definitions.

And one that has nothing to do with Anthropic’s API: an agent can write.

API-key calls are read-only by default. An agent backed by a connected repository reads it but never commits or pushes, unless you send metadata.read_only: false — in which case a turn that changes files pushes a commit to the repository’s default branch. See Writing to a connected repository.

---

Authentication

One header, on every request:

X-Api-Key: <your-api-key>

Create a key in the DataGen app under Workspace Settings → API Keys (/workspace/settings?tab=apikeys) — the same page on a self-hosted install.

The key decides the workspace. Keys are created inside a workspace and belong to it, so a key reaches only that workspace’s agents — an agent in another workspace returns 404, even if you can see it in the web UI. To call an agent in a team workspace, create the key while that workspace is selected. There is no header for choosing a workspace per-request.

The key decides what you may do. Running a turn requires an Admin, Builder, or Operator key; a Viewer key can read conversations but gets 403 when it tries to send a message.

A missing or unrecognized key returns 401; a revoked key returns 401 {"message": "API key has been revoked"}.

---

Models

curl "https://api.datagen.dev/api/agents/data-agent/v1/models" \
  -H "X-Api-Key: $DATAGEN_API_KEY"

Returns the model ids the agent can run on, with the agent’s configured default first:

{
  "data": [
    {"type": "model", "id": "claude-opus-4-7",   "display_name": "Claude Opus 4.7"},
    {"type": "model", "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6"},
    {"type": "model", "id": "claude-haiku-4-5",  "display_name": "Claude Haiku 4.5"}
  ],
  "has_more": false
}

Same auth and error semantics as /v1/messages, which makes it a cheap way to check that an agent name and key work together before sending a real turn.

When you omit model, resolution falls back to the automation’s model (if you passed metadata.automation), then the agent’s default model.

---

Where to go next

Send a Message

Full request body, SSE event stream, and SDK examples.

Conversations

Resume, fork, list, share, and delete conversations.

Errors & Limits

Status codes, timeouts, and concurrency guidance.