Reference

API Reference

Aktilot's backend is a FastAPI application. Interactive OpenAPI docs are always available locally at http://localhost:8000/docs.

Base URL

/api

Content type

application/json*

Auth

None (admin routes)

*except file upload, which is multipart/form-data. There is no authentication layer on the admin routes in this open-source build — put them behind your own auth/proxy before exposing the API publicly. The Public group below is the one exception: it's designed to be exposed directly, scoped per-visitor by cookie, and rate-limited.

Projects

4 endpoints

A project is a knowledge base: a collection of uploaded files and the agents that query them.

POST/api/projectsCreate a project

Request body

name	string	Required.
description	string \| null	Optional.

Response

201 Created

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Support Docs",
  "description": "Internal support knowledge base",
  "created_at": "2026-07-17T10:15:00Z"
}

GET/api/projectsList all projects

Response

200 OK

[
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Support Docs",
  "description": "Internal support knowledge base",
  "created_at": "2026-07-17T10:15:00Z"
}
]

GET/api/projects/{project_id}Get a project

Path parameters

project_id

UUID

Response

200 OK

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Support Docs",
  "description": "Internal support knowledge base",
  "created_at": "2026-07-17T10:15:00Z"
}

Errors

404"Project not found"

DELETE/api/projects/{project_id}Delete a project

Path parameters

project_id

UUID

Response

204 No Content

No response body.

Errors

404"Project not found"

Files

3 endpoints

Uploading a file only writes the record and enqueues ingestion — chunking and embedding happen asynchronously in a Temporal workflow. Poll GET /files or check chunk_status to see when a file is ready to be queried.

POST/api/projects/{project_id}/files/uploadUpload a file for ingestion

Path parameters

project_id

UUID

Request body

multipart/form-data, field name "file". Allowed extensions: .pdf, .txt, .doc, .docx.

Response

201 Created

Returned immediately with chunk_status = "pending" — a Temporal DocumentWorkflow is started in the background and moves it through "chunking" → "chunked" (or "error").

{
  "id": "9c858901-8a57-4791-81fe-4c455b099bc9",
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "filename": "handbook.pdf",
  "size": 482913,
  "chunk_status": "pending",
  "chunk_count": 0,
  "uploaded_at": "2026-07-17T10:16:42Z"
}

Errors

400Missing filename, or extension not in the allowed list
404"Project not found"

GET/api/projects/{project_id}/filesList files in a project

Path parameters

project_id

UUID

Response

200 OK

[
  {
    "id": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "filename": "handbook.pdf",
    "size": 482913,
    "chunk_status": "chunked",
    "chunk_count": 42,
    "uploaded_at": "2026-07-17T10:16:42Z"
  }
]

Errors

404"Project not found"

DELETE/api/projects/{project_id}/files/{file_id}Delete a file

Path parameters

project_id	UUID
file_id	UUID

Response

204 No Content

No response body.

Errors

404"File not found"

Agents

5 endpoints

An agent is a configured chat persona scoped to one project: a system prompt plus a top_k that controls how many chunks are retrieved per question.

POST/api/projects/{project_id}/agentsCreate an agent

Path parameters

project_id

UUID

Request body

name	string	Required.
description	string \| null	Optional.
system_prompt	string	Optional, defaults to "".
top_k	int	Optional, defaults to 2.

Response

201 Created

{
  "id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Support Bot",
  "description": "Answers questions from the support handbook",
  "system_prompt": "You are a helpful support assistant.",
  "top_k": 4,
  "created_at": "2026-07-17T10:20:00Z",
  "share_slug": null,
  "share_daily_message_cap": null
}

Errors

404"Project not found"

GET/api/projects/{project_id}/agentsList agents for a project

Path parameters

project_id

UUID

Response

200 OK

[
{
  "id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Support Bot",
  "description": "Answers questions from the support handbook",
  "system_prompt": "You are a helpful support assistant.",
  "top_k": 4,
  "created_at": "2026-07-17T10:20:00Z",
  "share_slug": null,
  "share_daily_message_cap": null
}
]

Errors

404"Project not found"

GET/api/agents/{agent_id}Get an agent

Path parameters

agent_id

UUID

Response

200 OK

{
  "id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Support Bot",
  "description": "Answers questions from the support handbook",
  "system_prompt": "You are a helpful support assistant.",
  "top_k": 4,
  "created_at": "2026-07-17T10:20:00Z",
  "share_slug": null,
  "share_daily_message_cap": null
}

Errors

404"Agent not found"

PUT/api/agents/{agent_id}Update an agent

Path parameters

agent_id

UUID

Request body

All fields optional — only the ones supplied are changed.

name	string \| null
description	string \| null
system_prompt	string \| null
top_k	int \| null

Response

200 OK

{
  "id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Support Bot",
  "description": "Answers questions from the support handbook",
  "system_prompt": "You are a helpful support assistant.",
  "top_k": 4,
  "created_at": "2026-07-17T10:20:00Z",
  "share_slug": null,
  "share_daily_message_cap": null
}

Errors

404"Agent not found"

DELETE/api/agents/{agent_id}Delete an agent

Path parameters

agent_id

UUID

Response

204 No Content

No response body.

Errors

404"Agent not found"

Chat

2 endpoints

Chatting runs the durable RAG pipeline synchronously: the request blocks (up to a 2-minute execution timeout) while a Temporal ChatWorkflow retrieves chunks, calls the LLM, and persists the exchange, then returns the full result.

POST/api/agents/{agent_id}/chatChat with an agent

Path parameters

agent_id

UUID

Request body

question	string	Required.
session_id	UUID	Required — create one first via POST /api/agents/{agent_id}/sessions.

Response

200 OK

{
  "answer": "Full-time employees accrue 15 PTO days per year.",
  "tool_steps": [
    {
      "name": "retrieve_chunks",
      "start_time": "2026-07-17T10:22:01.120Z",
      "end_time": "2026-07-17T10:22:01.340Z",
      "duration_ms": 220.4,
      "input_summary": "query='PTO policy', top_k=4",
      "output_summary": "3 chunks retrieved"
    }
  ],
  "retrieved_chunks": [
    {
      "chunk_id": "c1a2b3c4-d5e6-4f80-9a1b-2c3d4e5f6789",
      "filename": "handbook.pdf",
      "chunk_index": 12,
      "content": "Full-time employees accrue 15 PTO days per year, accrued monthly...",
      "score": 0.87,
      "vec_score": 0.81,
      "bm25_score": 4.2,
      "kw_hits": 2,
      "keywords_matched": ["PTO", "policy"]
    }
  ],
  "keywords": ["PTO", "policy"]
}

Errors

404"Agent not found", or the session does not belong to this agent (or belongs to a public visitor)
401Invalid OpenAI API key
429OpenAI rate limit exceeded
500Chat pipeline failed

GET/api/agents/{agent_id}/messagesGet full message history for an agent

Path parameters

agent_id

UUID

Response

200 OK

[
  {
    "id": "1b2c3d4e-5f60-4182-93a4-b5c6d7e8f901",
    "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
    "role": "user",
    "content": "How many PTO days do I get?",
    "created_at": "2026-07-17T10:22:00Z"
  },
  {
    "id": "2c3d4e5f-6071-4293-a4b5-c6d7e8f90123",
    "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
    "role": "assistant",
    "content": "Full-time employees accrue 15 PTO days per year.",
    "created_at": "2026-07-17T10:22:01Z"
  }
]

Errors

404"Agent not found"

Chat Sessions

3 endpoints

Sessions group messages into a conversation thread. A session must exist before you can POST a chat message.

POST/api/agents/{agent_id}/sessionsCreate a chat session

Path parameters

agent_id

UUID

Response

201 Created

{
  "id": "7a1b2c3d-4e5f-4071-8293-a4b5c6d7e8f9",
  "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
  "title": null,
  "created_at": "2026-07-17T10:21:50Z",
  "updated_at": "2026-07-17T10:21:50Z"
}

Errors

404"Agent not found"

GET/api/agents/{agent_id}/sessionsList sessions for an agent

Path parameters

agent_id

UUID

Response

200 OK

[
  {
    "id": "7a1b2c3d-4e5f-4071-8293-a4b5c6d7e8f9",
    "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
    "title": null,
    "created_at": "2026-07-17T10:21:50Z",
    "updated_at": "2026-07-17T10:21:50Z"
  }
]

Errors

404"Agent not found"

GET/api/sessions/{session_id}/messagesGet messages in a session

Path parameters

session_id

UUID

Response

200 OK

[
  {
    "id": "1b2c3d4e-5f60-4182-93a4-b5c6d7e8f901",
    "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
    "role": "user",
    "content": "How many PTO days do I get?",
    "created_at": "2026-07-17T10:22:00Z"
  },
  {
    "id": "2c3d4e5f-6071-4293-a4b5-c6d7e8f90123",
    "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
    "role": "assistant",
    "content": "Full-time employees accrue 15 PTO days per year.",
    "created_at": "2026-07-17T10:22:01Z"
  }
]

Errors

404"Chat session not found"

Agent Share Links

2 endpoints

Lets an agent owner publish a public, unauthenticated chat link for an agent. These endpoints manage the link itself; visitors interact with it through the Public endpoints below.

POST/api/agents/{agent_id}/shareCreate or regenerate the share link

Path parameters

agent_id

UUID

Request body

daily_message_cap

int | null

Optional, must be > 0. Overrides the server-wide default daily cap for this agent.

Response

200 OK

Regenerating immediately invalidates the previous slug — visitors holding the old link get a 404.

{
  "share_slug": "support-bot-x7q2",
  "share_path": "/share/support-bot-x7q2",
  "daily_message_cap": 200
}

DELETE/api/agents/{agent_id}/shareRevoke the share link

Path parameters

agent_id

UUID

Response

204 No Content

No response body.

Public (share-link visitors)

5 endpoints

Unauthenticated routes reached through a share link, resolved by share_slug rather than the internal agent id. On first request, an httpOnly, samesite=lax cookie ("aktilot_vid" by default) is issued with a random visitor UUID; every session and message a visitor creates is scoped to that cookie, so one visitor can never see another's conversation. Responses deliberately omit internal fields (project id, system prompt, top_k, retrieved chunks, tool steps) that would leak how the agent or its knowledge base is built.

GET/api/public/agents/{slug}Get public agent info

Path parameters

slug

string

The agent's share_slug.

Response

200 OK

{
  "name": "Support Bot",
  "description": "Answers questions from the support handbook"
}

POST/api/public/agents/{slug}/sessionsCreate a session as this visitor

Path parameters

slug

string

Response

201 Created

{
  "id": "7a1b2c3d-4e5f-4071-8293-a4b5c6d7e8f9",
  "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
  "title": null,
  "created_at": "2026-07-17T10:21:50Z",
  "updated_at": "2026-07-17T10:21:50Z"
}

GET/api/public/agents/{slug}/sessionsList this visitor's own sessions for the agent

Path parameters

slug

string

Response

200 OK

[
  {
    "id": "7a1b2c3d-4e5f-4071-8293-a4b5c6d7e8f9",
    "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
    "title": null,
    "created_at": "2026-07-17T10:21:50Z",
    "updated_at": "2026-07-17T10:21:50Z"
  }
]

GET/api/public/agents/{slug}/sessions/{session_id}/messagesGet messages in one of this visitor's sessions

Path parameters

slug	string
session_id	UUID

Response

200 OK

[
  {
    "id": "1b2c3d4e-5f60-4182-93a4-b5c6d7e8f901",
    "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
    "role": "user",
    "content": "How many PTO days do I get?",
    "created_at": "2026-07-17T10:22:00Z"
  },
  {
    "id": "2c3d4e5f-6071-4293-a4b5-c6d7e8f90123",
    "agent_id": "5e9d5a1b-8b8b-4f2d-9a9e-6b2c3f9a7d10",
    "role": "assistant",
    "content": "Full-time employees accrue 15 PTO days per year.",
    "created_at": "2026-07-17T10:22:01Z"
  }
]

Errors

404Session does not belong to this visitor/agent

POST/api/public/agents/{slug}/chatChat as this visitor

Path parameters

slug

string

Request body

question	string	Required.
session_id	UUID	Required.

Response

200 OK

Only { answer }. tool_steps and retrieved_chunks are stripped before this response leaves the server.

{
  "answer": "Full-time employees accrue 15 PTO days per year."
}

Errors

429Hourly visitor cap hit — "You've reached the message limit for this chat. Please try again in a bit." (default 20 messages/visitor/agent/hour)
429Daily agent-wide cap hit — "This agent has reached its usage limit for today. Please try again later." (default 200/day, or the agent's own daily_message_cap)

System

1 endpoint

GET/api/healthHealth check

Response

200 OK

{
  "status": "ok"
}