API Route & Endpoint Index
Relevant source files
The following files were used as context for generating this wiki page:
The Flow API provides a structured interface for managing a personal "second brain" and agent platform. It facilitates document ingestion, knowledge retrieval via RAG (Retrieval-Augmented Generation), agent lifecycle management, and continuous evaluation through golden sets and automated loops.
The system is built on FastAPI and utilizes a LangGraph pipeline for agent execution. It supports asynchronous background tasks via Redis/ARQ and persistent storage using PostgreSQL with pgvector for semantic search.
Sources: README.md:1-10, services/api/flow/interfaces/http/routes/knowledge.py:1-15
Knowledge Management
The Knowledge API handles the ingestion and retrieval of unstructured data. It supports multiple formats including PDF, Markdown, and plain text, as well as direct URL crawling.
Data Ingestion Flow
When a document is uploaded or a URL is crawled, the system extracts raw text, chunks it, and generates embeddings for vector search.
The ingestion process supports files up to 20MB and requires an OpenAI API key for generating embeddings.
Sources: services/api/flow/interfaces/http/routes/knowledge.py:23-110, README.md:145-155
Knowledge Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/knowledge | POST | Manually ingest text into the knowledge base. |
/api/v1/knowledge/upload | POST | Upload and process files (.pdf, .docx, .md, .txt). |
/api/v1/knowledge/crawl | POST | Extract and index content from a web URL. |
/api/v1/knowledge | GET | List all indexed knowledge sources for a workspace. |
/api/v1/knowledge/{source_id}/chunks | GET | Retrieve the specific text chunks for a source. |
/api/v1/knowledge/{source_id} | DELETE | Remove a knowledge source and its associated embeddings. |
Sources: services/api/flow/interfaces/http/routes/knowledge.py:38-155, apps/web/src/app/(app)/knowledge/page.tsx:165-225
Evaluation & Golden Sets
Golden sets are curated datasets used to measure agent performance. The API provides CRUD operations for these sets and triggers asynchronous evaluation runs where an LLM judge scores agent outputs.
Evaluation Lifecycle
The evaluation system tracks agent quality over time, supporting regression detection and automated prompt improvement.
The LLM judge evaluates responses based on specific scoring_criteria defined within the golden set items.
Sources: services/api/flow/interfaces/http/routes/golden_sets.py:270-325, README.md:85-100
Evaluation Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/golden-sets | GET | List all golden sets for the current workspace. |
/api/v1/golden-sets | POST | Create a new golden set. |
/api/v1/golden-sets/{set_id}/items | POST | Add a test case (input/expected/criteria) to a set. |
/api/v1/golden-sets/{set_id}/evaluate | POST | Trigger an asynchronous evaluation run. |
/api/v1/golden-sets/{set_id}/results | GET | Retrieve detailed results and aggregate scores. |
/api/v1/golden-sets/{set_id}/history | GET | Get historical performance for regression tracking. |
/api/v1/golden-sets/seed-samples | POST | Populate workspace with sample datasets (Research, Code, etc.). |
Sources: services/api/flow/interfaces/http/routes/golden_sets.py:165-300
Agent Execution & Genome
Agents are defined by their "Genome"—a versioned snapshot of system prompts, tool configurations, and LLM settings.
Agent Configuration
Agents can be configured with specific tools to expand their capabilities.
| Tool | Capability |
|---|---|
retrieve | Knowledge search using pgvector cosine similarity. |
sandbox | Execution of Python code blocks in a secure environment. |
long_term_memory | Recall of past run summaries via Postgres. |
tavily_search | External web searching for real-time information. |
subagent_call | Delegation of tasks to specialized sub-agents. |
Sources: services/api/scripts/seed_agents_and_datasets.py:40-150, README.md:65-75
Continuous Improvement Loop
A nightly cron job (auto_eval_tick) executes the following logic to improve agents:
- Run Eval: Executes golden sets.
- Analyze Failures: If pass rate < 0.7, failed items go to the Prompt Rewriter.
- Rewrite Prompt: GPT-4o-mini proposes new system prompts.
- A/B Test: The new candidate is tested against the active baseline.
- Propose: If the candidate wins, a human-approvable proposal is created.
Sources: README.md:80-105
Conclusion
The Flow API Route & Endpoint Index serves as the backbone for a self-improving agentic system. By combining robust knowledge ingestion with a structured evaluation framework, the API enables developers to build, monitor, and automatically optimize AI agents within a unified workspace.