What you're looking at.
Yoke Agent ships a FastAPI backend that exposes every piece of the platform over REST. Dashboards, CLI and MCP clients all talk through the same surface documented here — there is no private API.
Responses are JSON, dates are ISO 8601, identifiers are integer primary keys. Long-running operations (dataset generation, grid-search runs, simulation sweeps) are kicked off by an endpoint and then observed via the experiment-status / transcripts endpoints — never blocking the HTTP round-trip.
One command to get the stack up.
Clone the repository, then bring up the backend, frontend, worker and ChromaDB in one shot. Everything runs locally — no data leaves your machine.
$ git clone https://github.com/Empreiteiro/yoke-agent.git
$ cd yoke-agent
$ make dev
# → dashboard http://localhost:3000
# → REST API http://localhost:4040
# → Swagger UI http://localhost:4040/docs
# → ReDoc http://localhost:4040/redocEverything hangs off /api.
In the default compose setup the API is served at
http://localhost:4040. In production the
base URL is whatever you front it with. All routes below are
relative to that host.
The Swagger UI at /docs and ReDoc at
/redoc are generated live from the same schemas
this page documents — keep them in view while you wire clients.
JWT, with API keys as a shortcut.
Most endpoints need a bearer token. Two ways to get one:
- Login flow — POST email + password to
/api/users/loginand use the returnedaccess_token. - API keys — create one under
/api/auth/keysand send it as a bearer. Handy for CI and server-to-server scripts.
$ TOKEN=$(curl -s http://localhost:4040/api/users/login \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"..."}' | jq -r .access_token)
$ curl -H "Authorization: Bearer $TOKEN" \
http://localhost:4040/api/users/meStandard HTTP, JSON payload.
Non-2xx responses carry a detail field
(string or object) as the body. 401 means the token
is missing or expired; 403 means you're authenticated
but don't own the resource; 404 resources silently
scope to the caller — you won't see other users' IDs.
Auth
API-key bootstrap mode and per-user API keys.
/api/auth/statusReturn API-key bootstrap mode and current count./api/auth/keysList API keys for the caller (admins see all)./api/auth/keysCreate a new API key./api/auth/keys/{key_id}Delete an API key by id.Users
Registration, login and audit trail. First user created becomes admin.
/api/users/registerCreate an account. First caller is promoted to admin./api/users/loginExchange email and password for a JWT./api/users/meReturn the currently authenticated user./api/users/List all users (admin only)./api/users/{user_id}/roleChange a user's role (admin only)./api/users/audit-logsPaginated audit log (admin only).MCP
Tools the MCP server exposes, and the toggle to disable individual ones.
/api/mcp/toolsList MCP tools and their enabled status./api/mcp/toolsUpdate the MCP tool disabled-list./api/mcp/connection-infoGet the MCP server path and connection details.Providers
LLM and embedding providers — OpenAI, Anthropic, Gemini, Cohere, Azure, Ollama, HuggingFace, Claude Code CLI, custom OpenAI-compatible.
/api/providers/catalogSupported provider types and their models./api/providers/ollama/discoverDiscover models on a running Ollama server./api/providers/List configured providers./api/providers/Create a provider./api/providers/{provider_id}Get a provider by id./api/providers/{provider_id}Update a provider./api/providers/{provider_id}Delete a provider./api/providers/{provider_id}/testTest provider connectivity./api/providers/models/availableAggregate models across active providers./api/providers/models/embedding-dimensionsEmbedding-dimension capabilities per model./api/providers/claude-code/statusCheck the Claude Code CLI install status./api/providers/claude-code/authSave the Claude Code OAuth token.Vector stores
ChromaDB, Pinecone, Qdrant, pgvector and Astra DB. Managed as configurations you can test-connect before running experiments.
/api/vectorstores/catalogSupported vector-store types./api/vectorstores/configsList vector-store configurations./api/vectorstores/configsCreate a configuration./api/vectorstores/configs/{config_id}Update a configuration./api/vectorstores/configs/{config_id}Delete a configuration./api/vectorstores/configs/{config_id}/testTest connectivity for a configuration./api/vectorstores/availableChromaDB plus every active configured store.Token usage
Every LLM and embedding call logs token counts and estimated USD. Flex-tier discounts are detected automatically.
/api/token-usage/List usage rows with filters./api/token-usage/summaryAggregated summary — totals, per-provider, per-day.Traces
OpenTelemetry traces captured during runs. Pipe out via OTLP for Grafana, Honeycomb or Datadog.
/api/traces/List traces with optional filters./api/traces/summaryAggregated trace statistics./api/traces/{trace_id}Trace detail with span tree./api/traces/{trace_id}Delete a trace.Chat
A streaming SSE endpoint backed by your default provider — the assistant the dashboard ships with.
/api/chat/streamStream chat deltas via Server-Sent Events.Documents
Upload and manage the source documents that feed evaluation datasets and RAG pipelines.
/api/documents/uploadUpload PDF, DOCX, TXT or Markdown files./api/documents/List documents scoped to the caller./api/documents/{document_id}Get a document by id./api/documents/{document_id}Delete a document.Datasets
Evaluation Q&A sets. Generate with an LLM from your docs, import curated JSON, edit, review and lock with approve.
/api/datasets/Create an evaluation dataset./api/datasets/List datasets — benchmarks are shared, rest are user-scoped./api/datasets/{dataset_id}Get a dataset by id./api/datasets/{dataset_id}Delete a dataset./api/datasets/bulk-deleteDelete many datasets at once./api/datasets/seed-benchmarksSeed the built-in benchmark datasets./api/datasets/{dataset_id}/generateGenerate Q&A pairs with an LLM (background)./api/datasets/{dataset_id}/itemsAdd a Q&A item manually./api/datasets/{dataset_id}/items/{item_id}Update a dataset item./api/datasets/{dataset_id}/items/{item_id}Delete a dataset item./api/datasets/{dataset_id}/importImport items from a JSON file./api/datasets/{dataset_id}/duplicateDuplicate a dataset including all items./api/datasets/{dataset_id}/approveLock a dataset as approved for experiments.Experiments
Grid-search runs. Propose a grid with an LLM, estimate cost, configure combinations, run, and read the RAGAS-scored report.
/api/experiments/Create an experiment./api/experiments/List experiments for the caller./api/experiments/{experiment_id}Get an experiment by id./api/experiments/{experiment_id}Delete an experiment./api/experiments/bulk-deleteDelete many experiments at once./api/experiments/{experiment_id}/propose-gridLLM-proposed grid configuration./api/experiments/{experiment_id}/estimate-costEstimate tokens and USD for a proposed grid./api/experiments/{experiment_id}/configure-gridMaterialise combinations from the grid config./api/experiments/{experiment_id}/runStart execution (background)./api/experiments/{experiment_id}/stopStop a running experiment./api/experiments/{experiment_id}/resumeResume a stopped or failed experiment./api/experiments/{experiment_id}/reportGet the results report./api/experiments/{experiment_id}/exportExport results as CSV./api/experiments/custom-metrics/registeredList custom metrics registered via the hook./api/experiments/{experiment_id}/failures/exportExport failure analysis as CSV./api/experiments/combinations/{combination_id}/ratingsList human ratings for a combination./api/experiments/combinations/{combination_id}/ratingsCreate or update a rating for (combination, question)./api/experiments/combinations/{combination_id}/ratings/{rating_id}Update a rating./api/experiments/combinations/{combination_id}/ratings/{rating_id}Delete a rating./api/experiments/{experiment_id}/correlationPearson & Spearman between ratings and metrics./api/experiments/{experiment_id}/export-ratedExport rated questions with RAGAS scores.Collections
Saved winning collections — the vector stores materialised from an experiment's best configuration, ready to query.
/api/collections/List saved collections with sizes./api/collections/{collection_id}Delete a saved collection./api/collections/{collection_id}/queryQuery a collection and synthesise an answer./api/collections/save-from-experiment/{experiment_id}Persist the winning config from an experiment.Agent configs
Agent definitions — system prompt, tools, MCP servers, guardrails — plus prompt variants, scenarios and personas.
/api/agent/configs/List agent configurations./api/agent/configs/Create an agent configuration./api/agent/configs/{config_id}Get config by id./api/agent/configs/{config_id}Update a configuration./api/agent/configs/{config_id}Delete a configuration./api/agent/configs/test-httpDry-run test for an external HTTP agent./api/agent/configs/{config_id}/test-httpTest the HTTP endpoint bound to a saved config./api/agent/configs/enhance/promptLLM-assisted system-prompt rewrite./api/agent/configs/enhance/descriptionLLM-assisted description rewrite./api/agent/configs/enhance/suggest-toolsSuggest tools to attach to the agent./api/agent/configs/{config_id}/variantsList prompt variants./api/agent/configs/{config_id}/variantsCreate a prompt variant./api/agent/configs/{config_id}/variants/{variant_id}Delete a variant./api/agent/configs/{config_id}/variants/generateGenerate variants with an LLM./api/agent/configs/{config_id}/scenariosList scenarios./api/agent/configs/{config_id}/scenariosCreate a scenario./api/agent/configs/{config_id}/scenarios/bulkCreate many scenarios at once./api/agent/configs/{config_id}/scenarios/{scenario_id}Update a scenario./api/agent/configs/{config_id}/scenarios/{scenario_id}Delete a scenario./api/agent/configs/{config_id}/scenarios/generateGenerate scenarios with an LLM./api/agent/configs/{config_id}/personasList personas./api/agent/configs/{config_id}/personasCreate a persona./api/agent/configs/{config_id}/personas/bulkCreate many personas at once./api/agent/configs/{config_id}/personas/{persona_id}Update a persona./api/agent/configs/{config_id}/personas/{persona_id}Delete a persona./api/agent/configs/{config_id}/personas/generateGenerate synthetic personas with an LLM./api/agent/configs/{config_id}/personas/templatesPre-built persona archetypes.Agent experiments
Agent datasets, simulation sweeps, transcripts and G-Eval scoring.
/api/agent/datasetsList interaction datasets./api/agent/datasetsCreate an interaction dataset./api/agent/datasets/{dataset_id}Get interaction dataset by id./api/agent/datasets/{dataset_id}Delete an interaction dataset./api/agent/datasets/{dataset_id}/duplicateDuplicate a dataset including items./api/agent/datasets/{dataset_id}/itemsList items./api/agent/datasets/{dataset_id}/itemsAdd an item./api/agent/datasets/{dataset_id}/items/{item_id}Delete an item./api/agent/datasets/{dataset_id}/importImport items./api/agent/datasets/{dataset_id}/exportExport an interaction dataset./api/agent/datasets/generateGenerate an interaction dataset with an LLM./api/agent/experimentsList agent experiments./api/agent/experimentsCreate an agent experiment./api/agent/experiments/{exp_id}Get experiment by id./api/agent/experiments/{exp_id}Delete an experiment./api/agent/experiments/bulk-deleteDelete many experiments at once./api/agent/experiments/{exp_id}/combinationsList combinations in an experiment./api/agent/experiments/{exp_id}/runRun all combinations (background)./api/agent/experiments/{exp_id}/stopStop a running experiment./api/agent/experiments/{exp_id}/resumeResume a stopped or failed experiment./api/agent/experiments/{exp_id}/statusExperiment status counts./api/agent/experiments/{exp_id}/transcriptsList simulation transcripts./api/agent/transcripts/{transcript_id}Get a transcript by id./api/agent/transcripts/{transcript_id}/metricsMetrics for a transcript./api/agent/experiments/{exp_id}/resultsAggregated results for every combination./api/agent/experiments/{exp_id}/evaluateEvaluate all completed transcripts./api/agent/experiments/{exp_id}/report/generateGenerate an LLM-powered improvement report./api/agent/experiments/{exp_id}/reportFetch a previously-generated report.
Schemas, request/response shapes and validation rules live
in the live Swagger UI
once the backend is running. Source for every router is at
backend/app/api.