> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Overview
> Getting started with the FIM One REST API
API reference documentation is currently available in **English only**. If you are viewing this page in another language, please switch to the English version — the full API endpoint list will appear in the left sidebar.
FIM One provides a REST API for programmatic access to AI agents, conversations, knowledge bases, and more.
## Base URL
```
https://your-domain.com/api
```
## Authentication
All API requests require authentication via an API key or JWT token.
### Using API Key
Include your API key in the `Authorization` header:
```bash theme={null}
curl -H "Authorization: Bearer fim_your_api_key_here" \
https://your-domain.com/api/agents
```
### Using JWT Token
For SSE streaming endpoints (`/api/react` and `/api/dag`), you can pass the token in the request body instead:
```json theme={null}
{
"q": "What's the weather today?",
"token": "your_jwt_token_here"
}
```
See [Authentication](/api/authentication) for detailed setup instructions.
## Response Format
### Success Response
All successful API responses follow this structure:
```json theme={null}
{
"success": true,
"data": {
"id": "conv_123abc",
"title": "My Conversation",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### Error Response
Error responses include an error code and human-readable message:
```json theme={null}
{
"success": false,
"error": "conversation_not_found",
"message": "The conversation does not exist or has been deleted"
}
```
### Paginated Responses
List endpoints return paginated results:
```json theme={null}
{
"items": [
{ "id": "item_1", "name": "First Item" },
{ "id": "item_2", "name": "Second Item" }
],
"total": 42,
"page": 1,
"size": 20,
"pages": 3
}
```
## Streaming (Server-Sent Events)
Chat endpoints (`POST /api/react` and `POST /api/dag`) return Server-Sent Events for real-time streaming. Each event has a `type` field indicating its content:
| Event Type | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `step` | ReAct reasoning step (tool calls, thinking). For models with extended thinking (Claude, o-series, DeepSeek-R1), includes real-time `thinking_delta` content during tool-decision phases |
| `step_progress` | DAG step progress (started/iteration/completed). May include `thinking_delta` content when the underlying agent streams reasoning tokens |
| `phase` | Pipeline phase transition (planning/executing/analyzing) |
| `compact` | Context compaction occurred |
| `answer` | Streamed answer text (start/delta/done) |
| `done` | Final result payload |
| `suggestions` | Suggested follow-up questions |
| `title` | Auto-generated conversation title |
| `end` | Stream terminator (always last) |
### Example SSE Stream
```
event: step
data: {"type": "tool_call", "tool": "search", "input": "Paris weather"}
event: answer
data: {"type": "delta", "text": "Based on current data, "}
event: answer
data: {"type": "delta", "text": "Paris has pleasant weather."}
event: done
data: {"answer": "Based on current data, Paris has pleasant weather.", "tokens": 128}
event: suggestions
data: ["What about tomorrow's forecast?", "Compare with other European cities"]
event: end
data: {}
```
### Cursor-based resume
Every SSE event carries a monotonic `cursor` integer scoped to the conversation. Clients should track the highest cursor seen. When the connection drops mid-turn (network error, proxy timeout, server restart), the client can re-subscribe without re-running the agent:
```http theme={null}
POST /api/chat/resume
Content-Type: application/json
Authorization: Bearer
{
"conversation_id": "",
"cursor": 42
}
```
The response is an SSE stream that replays cached events with `cursor > 42` and ends with a terminal `event: resume_done` frame. Pass `cursor: -1` to request a full replay from the beginning.
Error responses:
* `404 conversation_not_found` — conversation id is invalid or not owned by the authenticated user
* `404 no_recent_assistant_message` — conversation has no persisted assistant turn to resume from (e.g., a brand-new conversation with no user messages yet)
* `400 invalid_cursor` — cursor is not a non-negative integer or `-1`
The reference frontend implementation (`useSseResume` hook in the playground) auto-retries network disconnects with exponential backoff (300ms → 1s → 3s, max 3 attempts) and distinguishes user-initiated abort from network error to avoid unintended reconnects. See the `playground-page.tsx` integration for the full pattern.
Resume is stateless — it replays from the assistant message's stored `sse_events` array. If the agent's turn was interrupted before any assistant message was persisted (e.g., a crash before `done`), the dangling `tool_use` block is auto-repaired by `DbMemory._repair_dangling_tool_calls` on the next turn. Synthetic `tool_result` rows are persisted with `metadata_.synthetic=true` and `metadata_.reason="interrupted"` for audit.
## Rate Limiting
Per-key rate limiting is planned for a future release. Currently there are no enforced per-key request limits, but please use the API responsibly.
## Pagination
List endpoints support pagination via query parameters:
```bash theme={null}
curl "https://your-domain.com/api/conversations?page=2&size=50" \
-H "Authorization: Bearer fim_your_api_key_here"
```
Parameters:
* `page` (default: 1) — page number, starting from 1
* `size` (default: 20) — items per page, max 100
## Timestamps
All timestamps are in ISO 8601 format with UTC timezone:
```json theme={null}
{
"created_at": "2024-01-15T10:30:45.123456Z",
"updated_at": "2024-01-15T14:22:10.654321Z"
}
```
## Error Codes
Common error codes and their meanings:
| Error Code | HTTP Status | Meaning |
| --------------------- | ----------- | --------------------------------------- |
| `unauthorized` | 401 | Invalid or missing authentication |
| `forbidden` | 403 | User lacks permission for this resource |
| `not_found` | 404 | Resource does not exist |
| `bad_request` | 400 | Invalid request parameters |
| `rate_limit_exceeded` | 429 | Too many requests (planned) |
| `internal_error` | 500 | Server error |
## API Playground
Each endpoint page includes an interactive API Playground where you can:
* Test requests directly from your browser
* View real responses
* Copy request code in multiple languages
* Authenticate with your API key
The API Playground runs requests from your browser, so ensure your API key has appropriate CORS permissions (usually enabled by default for same-origin requests).
## SDK Availability
While FIM One API is fully REST-based, SDKs are available (or coming soon) in popular languages:
* **Python**: Coming soon
* **JavaScript/TypeScript**: Coming soon
* **Go**: Coming soon
## Versioning
The current API version is `v0.8.0`. Version is not included in the URL path; breaking changes will be signaled through major version bumps and a migration period.
## Support
For API issues or questions:
* **Documentation**: See detailed guides on each endpoint
* **GitHub Issues**: Report bugs at [https://github.com/fim-ai/fim-one/issues](https://github.com/fim-ai/fim-one/issues)
* **Discord Community**: Join our community for discussion