# AgentForge API — Full Reference

> Programmatically create and configure AI agents. Every endpoint returns next_steps to guide you through the setup flow.

Base URL: `https://agents.algomax.fr/api`
Auth: `Authorization: Bearer af_xxx`

## Quick Start

```bash
# 1. Create an agent
curl -X POST https://agents.algomax.fr/api/v1/agents \
  -H "Authorization: Bearer af_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Bot", "model": "openai/gpt-5.3-chat-latest"}'

# 2. Configure its prompt
curl -X PUT https://agents.algomax.fr/api/v1/agents/{id}/prompt \
  -H "Authorization: Bearer af_xxx" \
  -H "Content-Type: application/json" \
  -d '{"systemPrompt": "You are a helpful assistant."}'

# 3. Chat with it
curl -X POST https://agents.algomax.fr/api/v1/chat \
  -H "Authorization: Bearer af_xxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "{id}", "message": "Hello!"}'
```

## Response Format

**Mutations** return `next_steps` guiding you to the next action:
```json
{
  "data": { "id": "...", "name": "My Bot", "status": "draft" },
  "next_steps": [
    { "description": "Configure the system prompt", "method": "PUT", "path": "/api/v1/agents/{id}/prompt" }
  ]
}
```

**Errors** include a fix hint:
```json
{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with ID 'abc' not found",
    "fix": "List your agents with GET /api/v1/agents to find valid IDs",
    "request_id": "req_xxx"
  }
}
```

## Agents

### `GET /v1/agents`

**List all agents in your workspace**

---

### `POST /v1/agents`

**Create a new agent**

Creates a new agent in draft status. Follow the next_steps to configure it.

**Request body:**
```json
{
  "name": "Customer Support Bot",
  "model": "openai/gpt-4o",
  "systemPrompt": "You are a helpful customer support agent."
}
```

---

### `GET /v1/agents/{id}`

**Get an agent with its full configuration**

**Parameters:**
- `id` (path) — string

---

### `PATCH /v1/agents/{id}`

**Update an agent**

Update agent name, status, or other top-level fields. Use dedicated sub-resource endpoints for prompt, tools, etc.

**Request body:**
```json
{
  "name": "",
  "status": "draft"
}
```

**Parameters:**
- `id` (path) — string

---

### `DELETE /v1/agents/{id}`

**Delete an agent**

Permanently deletes an agent and all its associated data (knowledge bases, logs, conversations).

**Parameters:**
- `id` (path) — string

---

### `POST /v1/agents/{id}/clone`

**Clone an agent**

Creates a copy of the agent with all its configuration. The clone starts in draft status.

**Parameters:**
- `id` (path) — string

---

## Agent Configuration

### `GET /v1/agents/{id}/prompt`

**Get agent prompt config**

**Parameters:**
- `id` (path) — string

---

### `PUT /v1/agents/{id}/prompt`

**Update agent prompt config**

**Request body:**
```json
{
  "promptConfig": null,
  "systemPrompt": ""
}
```

**Parameters:**
- `id` (path) — string

---

### `GET /v1/agents/{id}/model`

**Get agent model config**

**Parameters:**
- `id` (path) — string

---

### `PUT /v1/agents/{id}/model`

**Update agent model config**

**Request body:**
```json
{
  "model": ""
}
```

**Parameters:**
- `id` (path) — string

---

### `GET /v1/agents/{id}/tools`

**Get agent tools config**

**Parameters:**
- `id` (path) — string

---

### `PUT /v1/agents/{id}/tools`

**Update agent tools config**

**Request body:**
```json
[]
```

**Parameters:**
- `id` (path) — string

---

### `GET /v1/agents/{id}/channels`

**Get agent channels config**

**Parameters:**
- `id` (path) — string

---

### `PUT /v1/agents/{id}/channels`

**Update agent channels config**

**Request body:**
```json
{
  "discord": null,
  "telegram": null,
  "whatsapp": null,
  "slack": null
}
```

**Parameters:**
- `id` (path) — string

---

### `GET /v1/agents/{id}/guardrails`

**Get agent guardrails config**

**Parameters:**
- `id` (path) — string

---

### `PUT /v1/agents/{id}/guardrails`

**Update agent guardrails config**

**Request body:**
```json
{
  "blockedTopics": [],
  "piiDetection": false,
  "maxInputLength": 0,
  "maxOutputLength": 0
}
```

**Parameters:**
- `id` (path) — string

---

### `GET /v1/agents/{id}/memory`

**Get agent memory config**

**Parameters:**
- `id` (path) — string

---

### `PUT /v1/agents/{id}/memory`

**Update agent memory config**

**Request body:**
```json
{
  "strategy": "sliding_window",
  "windowSize": 0
}
```

**Parameters:**
- `id` (path) — string

---

### `GET /v1/agents/{id}/escalation`

**Get agent escalation config**

**Parameters:**
- `id` (path) — string

---

### `PUT /v1/agents/{id}/escalation`

**Update agent escalation config**

**Request body:**
```json
{
  "webhookUrl": "",
  "autoEscalateKeywords": [],
  "assignedTo": [],
  "enabled": false
}
```

**Parameters:**
- `id` (path) — string

---

## Knowledge Bases

### `GET /v1/agents/{id}/knowledge-bases`

**List knowledge bases for an agent**

**Parameters:**
- `id` (path) — string

---

### `POST /v1/agents/{id}/knowledge-bases`

**Create a knowledge base**

Creates a knowledge base for RAG. After creating, upload documents to it.

**Request body:**
```json
{
  "name": "Product Documentation",
  "description": "All product docs and FAQs"
}
```

**Parameters:**
- `id` (path) — string

---

### `GET /v1/agents/{id}/knowledge-bases/{kbId}/documents`

**List documents in a knowledge base**

**Parameters:**
- `id` (path) — string
- `kbId` (path) — string

---

### `POST /v1/agents/{id}/knowledge-bases/{kbId}/documents`

**Upload a document**

Upload a document as plain text or base64-encoded file. Supported formats: PDF, DOCX, CSV, TXT, Markdown. The document will be chunked and embedded automatically.

**Request body:**
```json
{
  "filename": "product-guide.md",
  "content": "",
  "base64": ""
}
```

**Parameters:**
- `id` (path) — string
- `kbId` (path) — string

---

## Evals

### `GET /v1/agents/{id}/evals`

**List eval suites for an agent**

**Parameters:**
- `id` (path) — string

---

### `POST /v1/agents/{id}/evals`

**Create an eval suite**

Creates an eval suite with test cases. After creating, run it to evaluate the agent.

**Request body:**
```json
{
  "name": "Core Q&A Tests",
  "testCases": [
    {
      "input": "What is your return policy?",
      "expectedOutput": null,
      "criteria": "Mentions 30-day return window",
      "scorer": "llm-judge"
    }
  ]
}
```

**Parameters:**
- `id` (path) — string

---

### `POST /v1/agents/{id}/evals/{suiteId}/run`

**Run an eval suite**

Executes all test cases in the eval suite against the agent and returns scored results.

**Parameters:**
- `id` (path) — string
- `suiteId` (path) — string

---

## Logs & Stats

### `GET /v1/agents/{id}/logs`

**List request logs for an agent**

**Parameters:**
- `id` (path) — string
- `limit` (query) — number
- `offset` (query) — number

---

### `GET /v1/agents/{id}/stats`

**Get aggregated stats for an agent**

**Parameters:**
- `id` (path) — string
- `from` (query) — string
- `to` (query) — string

---

## Conversations

### `DELETE /v1/agents/{id}/conversations/{conversationId}`

**Delete a single conversation**

**Parameters:**
- `id` (path) — string
- `conversationId` (path) — string

---

### `DELETE /v1/agents/{id}/conversations`

**Delete all conversations for an agent**

**Parameters:**
- `id` (path) — string

---

## Chat

### `POST /v1/chat`

**Send a message to an agent**

Send a message and receive a complete response. Use /chat-stream for streaming.

**Request body:**
```json
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Hello, how can you help me?",
  "conversation_id": ""
}
```

---

### `POST /v1/chat-stream`

**Send a message to an agent (streaming)**

Send a message and receive a streaming SSE response.

**Request body:**
```json
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Hello, how can you help me?",
  "conversation_id": ""
}
```

---