Agents

Agents use the same public Docspeed tool catalog exposed in the customer API. Discover tools first, then create an agent with a focused instruction set and selected tool names.

Tool discovery

GET /v1/agents/tools returns the public tool registry. It does not take a request body.

Agent creation

POST /v1/agents stores an agent definition:

{
  "name": "invoice-review-agent",
  "description": "Reviews invoice packets and prepares grounded extraction outputs.",
  "instructions": "Use parse and extract tools to produce reviewable invoice fields. Preserve source evidence.",
  "tool_names": ["parse", "extract", "tables"]
}

cURL

curl -sS "https://api.docspeed.ai/v1/agents/tools" \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}"

Python

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

tools = requests.get(
    "https://api.docspeed.ai/v1/agents/tools",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=60,
)
tools.raise_for_status()

agent = requests.post(
    "https://api.docspeed.ai/v1/agents",
    headers=headers,
    json={
        "name": "invoice-review-agent",
        "description": "Reviews invoice packets and prepares grounded extraction outputs.",
        "instructions": "Use parse and extract tools to produce reviewable invoice fields. Preserve source evidence.",
        "tool_names": ["parse", "extract", "tables"],
    },
    timeout=120,
)
agent.raise_for_status()
print(agent.json())

TypeScript

const tools = await fetch("https://api.docspeed.ai/v1/agents/tools", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
console.log(await tools.json());

const agent = await fetch("https://api.docspeed.ai/v1/agents", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "invoice-review-agent",
    description: "Reviews invoice packets and prepares grounded extraction outputs.",
    instructions: "Use parse and extract tools to produce reviewable invoice fields. Preserve source evidence.",
    tool_names: ["parse", "extract", "tables"],
  }),
});
console.log(await agent.json());

Example tools response

{
  "tools": [
    {
      "name": "parse",
      "description": "Parse a document into markdown, regions, and chunks.",
      "endpoint": "/api/v1/parse"
    },
    {
      "name": "extract",
      "description": "Run grounded extraction with a Schema V2 contract.",
      "endpoint": "/v1/extract"
    }
  ]
}

Example create response

{
  "agent_id": "agent_123",
  "name": "invoice-review-agent",
  "description": "Reviews invoice packets and prepares grounded extraction outputs.",
  "instructions": "Use parse and extract tools to produce reviewable invoice fields. Preserve source evidence.",
  "created_at": 1776054000.0,
  "tools": []
}

Production notes

Tool discovery is GET /v1/agents/tools, not POST.
Keep agent instructions narrow enough that every allowed tool is useful.
Use the generated API Reference for the exact persisted agent schema.