API Reference

Aktilot's backend is a FastAPI application. When running locally, interactive OpenAPI docs are always available at http://localhost:8000/docs. The endpoints below are grouped by resource.

Projects

POST/projectsCreate a project

GET/projectsList projects

GET/projects/{project_id}Get a project

DELETE/projects/{project_id}Delete a project

Files

POST/projects/{project_id}/filesUpload a file for ingestion

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

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

Agents

POST/projects/{project_id}/agentsCreate an agent

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

GET/agents/{agent_id}Get an agent

PUT/agents/{agent_id}Update an agent

DELETE/agents/{agent_id}Delete an agent

Chat

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

GET/agents/{agent_id}/messagesGet message history

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

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

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

System

GET/api/healthHealth check

Chat request & response schema

Every chat response includes the retrieved chunks it was built from — filename, chunk position, and both the hybrid and component (vector / BM25) scores — so answers are always traceable back to a source.

backend/models/schemas.py

class ChatRequest(BaseModel):
    question: str
    session_id: uuid.UUID
 
class ChatResponse(BaseModel):
    answer: str
    tool_steps: list[ToolStep]
    retrieved_chunks: list[RetrievedChunk]
    keywords: list[str] = []
 
class RetrievedChunk(BaseModel):
    chunk_id: str
    filename: str
    chunk_index: int
    content: str
    score: float           # final hybrid score
    vec_score: float = 0.0  # cosine similarity component
    bm25_score: float = 0.0 # BM25 component
    kw_hits: int = 0
    keywords_matched: list[str] = []
 
class AgentCreate(BaseModel):
    name: str
    description: str | None = None
    system_prompt: str = ""
    top_k: int = 2