Getting started
Everything here is scoped to your account and reachable three ways: the web UI, plain HTTP with your API key, and MCP for AI clients such as Claude.
These docs are also available as one Markdown file at https://www.blle.co/docs.md, always current. Point your agents at it so they work from the latest reference.
Connection
| API key | On your Account page. |
| Auth | A browser session in the UI, or Authorization: Bearer <API_KEY> for everything outside it. Both scope the request to your user. |
api.blle.co |
Runs things: agents, the MCP server, tools, files, jobs, runners and secrets. |
www.blle.co |
Manages things: creating and editing agents, schedules, file share links. |
| MCP endpoint | https://api.blle.co/mcp (Streamable HTTP transport, stateless) |
Connecting Claude
claude mcp add --transport http blle https://api.blle.co/mcp
Claude Code and Claude Desktop sign in with OAuth 2.0 (PKCE) and open the browser for it. For headless or script use, send Authorization: Bearer <API_KEY> directly against https://api.blle.co/mcp.
Agents
An agent is a versioned prompt plus a JSON settings block naming a provider, a model, and the tools it may reach. Once saved it is addressable by UUID: from the UI, the HTTP API, a cron schedule, or as an OpenAI-compatible model. Every run it makes is recorded. Build and edit them on Agents.
Endpoints
Running agents, on api.blle.co:
| Method | Path | Purpose |
|---|---|---|
| POST | /agent/stream |
Server-Sent Events stream of the run. Events arrive as {"type": "content", "content": "..."}. Also accepts multipart/form-data to attach a file to the prompt. |
| POST | /agent/run |
Synchronous. Blocks until the run finishes, returns {response}. Best for short interactive calls. |
| POST | /agent/runs |
Asynchronous. Returns 202 {executionId} plus a Location header immediately; the run continues server-side. |
| GET | /agent/runs/:id |
Poll a run: status, response, and the full event list. A run cut short by a platform restart ends as failed with error "Interrupted by restart"; start it again. |
| GET | /agent/runs/:id/events |
Attach an SSE stream to a run already in flight. |
| POST | /agent/runs/:id/cancel |
Abort an in-flight run. The execution row is marked failed. |
| GET | /v1/models |
OpenAI-compatible model list: one entry per agent you own, id agent:<uuid>. |
| POST | /v1/chat/completions |
OpenAI-compatible chat completions against model: "agent:<uuid>". Lets any OpenAI client talk to an agent unmodified. |
Managing agents, on www.blle.co:
| Method | Path | Purpose |
|---|---|---|
| GET | /api/agents |
Latest version of every agent you own. |
| POST | /api/agents |
action=add (name, prompt required, settings optional JSON) · action=edit (agent_uuid, saves a new version) · action=delete (id) · action=history (uuid) · action=executions (agent_id, execution_id, status, limit) |
Agents & versioning
- Files: each agent is a folder in your files,
/workspace/agents/<folder>/.AGENT.mdis the prompt andagent.jsonthe settings. Agents (and you) can edit those files directly; the next run uses them. - Prompt: the agent's role and instructions. Markdown headers keep long prompts navigable.
- Settings: JSON, see the reference below. Secrets go in by name only:
"apiKey": "OPENAI_API_KEY", and in another MCP server's headers"Authorization": "Bearer {{secret:NAME}}". Blue Leaf's own MCP server needs no header: the agent reaches it as you. - Versioning: every save keeps the previous files in the folder's
.versions/. History and one-click restore live behind the clock icon on the Agents table. - UUID: stable across versions. It is what
agentIdmeans everywhere on this page, so callers never have to track versions. - An edit saves a whole new version from exactly what you send; only the favorite flag carries over. Through the API that means sending the complete
promptandsettingsevery time: fields you leave out come back empty on the new version.
Settings reference
| Setting | Meaning |
|---|---|
provider |
claude · openai · gemini · openai-compatible. Defaults to claude. |
model |
Provider model id, e.g. claude-sonnet-4-6. |
apiKey |
The name of a row in your secrets manager (e.g. OPENAI_API_KEY), never a raw key. The server decrypts it at request time. Required. |
temperature |
Sampling temperature. |
maxTokens |
Response cap. |
thinkingBudget |
Extended-thinking token budget, for models that support it. |
mcpServers |
MCP servers the agent may call, keyed by name. Point one at your own MCP server (/mcp, or /mcp/toolset/<id> for a toolset) to give an agent your tool library; no API key needed. To limit which tools it sees, add "tool_configuration": {"allowed_tools": [...]} inside that server entry. |
responseSchema |
A JSON Schema. The agent then answers in a single call with JSON that matches it: /agent/run returns the object as response. Schema agents have no tools, so it can't be combined with mcpServers. temperature defaults to 0. Suited to steps a workflow tool hands off, like classifying, extracting or turning a search query into filters. |
baseURL |
Required for openai-compatible: the endpoint to send to. |
{
"provider": "claude",
"model": "claude-sonnet-4-6",
"apiKey": "ANTHROPIC_API_KEY",
"temperature": 0.7,
"maxTokens": 1000,
"mcpServers": {
"blle": { "type": "http", "url": "https://api.blle.co/mcp" }
}
}
Execution model
- Pick by shape of the call: stream for a UI, run for something that finishes in seconds, runs for anything that might not.
/agent/runholds the connection open. That is fine until it isn't: long calls fight every timeout in the path, which is what/agent/runsplus polling exists to avoid.- Add
format: "json"torunorrunsfor structured output. The synchronous call returns it parsed, fences stripped; the poll returns the agent's raw response, so strip fences yourself. - Pass a
sessionIdto continue a conversation: runs sharing one see the prior turns. Omit it and each run starts clean.metadatacarries any extra context you want on the record. - Every run (UI, API, or schedule) writes an execution row. Token spend and failures show up on Activity.
Embedding a chat agent
A website chat widget is an agent wrapped in a public widget. It carries its own client id, so the page it sits on never sees your API key. Widgets are listed under the agents on the Agents page; copy the snippet from a widget's code button and paste it anywhere in the <body> of your site.
<chat-bot client-id="YOUR_CLIENT_ID"></chat-bot>
<script type="module" src="https://blle.s3.amazonaws.com/chatbot/index.js"></script>
Calling an agent from HTTP
Use your API key as the Bearer token. agentId is the agent's UUID: copy it from the Agents table.
Synchronous
curl -X POST https://api.blle.co/agent/run \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agentId": "<uuid>", "prompt": "Summarize the inbox"}'
Asynchronous: start, then poll until status is completed or failed.
curl -X POST https://api.blle.co/agent/runs \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agentId": "<uuid>", "prompt": "Research and write the weekly brief"}'
curl https://api.blle.co/agent/runs/<executionId> -H "Authorization: Bearer YOUR_API_KEY"
Streaming (SSE)
curl -N -X POST https://api.blle.co/agent/stream \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agentId": "<uuid>", "prompt": "Hello", "sessionId": "<optional>"}'
As an OpenAI model
curl -X POST https://api.blle.co/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "agent:<uuid>", "messages": [{"role": "user", "content": "Hello"}]}'
Create an agent
curl -X POST https://www.blle.co/api/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "add", "name": "Brief writer", "prompt": "You are...", "settings": "{\"provider\":\"claude\"}"}'
Secrets, not keys. Provider credentials live in the secrets manager and agent settings reference them by name. A raw key pasted into an agent is stored in every version of that agent from then on.
Tools & MCP
Blue Leaf runs its own Model Context Protocol server so AI clients (Claude, workflow tools, your own agents) can discover and run tools, read documents, and use encrypted secrets. Tools are stored as code and run in a secure Deno sandbox. Your library is listed on Tools.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /mcp |
Main MCP endpoint (Streamable HTTP). Per-request server, tools scoped to the user. |
| GET | /mcp/health |
Health check. |
| POST | /tools/run |
Direct HTTP execution of a tool by name. Authenticated with your API key. Optional timeout (ms, max 300000) and "async": true to answer at once and run in the background. |
| OAUTH | /authorize · /token |
OAuth 2.0 Authorization Code + PKCE for Claude Desktop / CLI. |
Tools can also run from outside services or on a schedule: see Long jobs, schedules & triggers.
Built-in tools
The MCP server exposes these to any connected client or agent, alongside your own tools.
| Tool | What it does |
|---|---|
Search_Tools |
Search your tools by keyword. Returns id, name, description. |
Get_Tools |
Fetch one or more tools by name, including the full source code, read from the tool's file. |
Run_tool |
Execute a tool by name with params. Default 60s timeout, max 300s. |
Create_Tool |
Create a new tool (name, description, JS/TS code). The code is saved to /workspace/lib/tools/<name>.ts. Owned by the calling user. |
Update_Tool |
Update a tool by id. You can only update your own tools. The code it replaces is kept in /workspace/lib/tools/.versions/<name>/. |
Delete_Tool |
Delete a tool by id. You can only delete your own tools. |
Execute_Code |
Run ad-hoc JS/TS in the Deno sandbox for one-off tasks, including reading and writing your files through context.fs. Streams console output. |
Get_Resource |
Read a document from /workspace/docs by key (its path there without the extension). See Documents as MCP resources. |
Invoke_Agent |
Run one of your agents as a sub-agent and return its reply. Runs on the server, not in the sandbox, with no tool timeout; chains stop at 3 levels. |
Run_On_Runner |
Run a command on your account's runner (ffmpeg, renders, Python) and wait up to an hour for the result. |
Show_UI |
Show an interactive page you built under /workspace/ui/<name>/ inline in the chat. The page can call the tools listed in that folder's ui.json (through UI_Call). |
Manage_Secrets |
list / set / delete encrypted secrets scoped to your user. |
Writing a tool
- A tool is a module that exports
async function run(context). Params arrive oncontext(const { foo } = context);returnoutputs the result;console.logis captured as log events. - Tools run inside a shared Deno sandbox with
fetch()available. Import npm packages fromhttps://esm.sh/<package>@<major>. context.fsreads and writes your/workspacefiles (read / write / list / stat / exists / delete / move).- Default timeout 60s, max 300s. For longer work see Long jobs; work that needs real programs goes to a runner.
- All your secrets are injected into every run as
context.secretsand asDeno.envvariables. - Tools can persist a new secret (e.g. refreshed OAuth tokens) via
await context.saveSecret(name, value). - When an agent calls a tool,
context.callernames it (agentId,agentName,folder,executionId); it isnullfor a person or an outside caller.
Deno sandbox
Execute_Code and every tool run inside one Deno sandbox. Each run is fresh — variables do not survive to the next run. Your /workspace files and secrets do persist, so write anything you want to keep to disk. In your code, a returned value is the run's result; console.log streams alongside it as log events, so it is a side channel, not the answer.
- Imports are ESM only.
npm:imports resolve to a small pre-installed set; anything else comes from esm.sh with the major pinned:import OpenAI from "https://esm.sh/openai@4". Prefer built-in Web APIs (fetch,crypto.randomUUID,atob) over a small package. Shared TypeScript you keep in/workspace/libimports by path:import { clients } from "lib/clients.ts". - A
lib/...import line fails anExecute_Coderun before it starts — the host resolves anyimport ... from "lib/..."in the source, even one inside a string, so keep such lines out of code you generate at runtime. - Files: the async
Deno.*filesystem calls work on your/workspace(the sync variants throw), as do the explicitcontext.fsverbs —read/write/list/stat/move/delete. There is nomkdir: writing/workspace/a/b.txtcreates the folder. Paths must be absolute and start with/workspace/. A single write is capped at 10 MB — larger payloads go to S3 or another store. Text crosses as UTF-8 and binary as base64, so don't base64-encode text yourself. - Secrets are in
Deno.envfor the run, so an SDK that reads its own key from the environment just works; a refreshed token is saved back withawait context.saveSecret(name, value). - No shell and no native modules (FFI is denied). Anything needing a real program goes to a runner; in the sandbox, reach for pure-JS or WASM packages.
Running a tool from HTTP
Use your API key as the Bearer token. Tools are scoped to your user account.
curl -X POST https://api.blle.co/tools/run \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"toolName": "my_tool", "params": {"limit": "5"}}'
Toolsets
A toolset is a named list of tools with its own MCP URL, https://api.blle.co/mcp/toolset/<id>. A client or agent on that URL sees only those tools, none of the built-in management tools. Use one for any agent that talks to the public: however a visitor steers it, it can only call what the list names. Create and edit them at the top of the Tools page.
- Point the agent's MCP server entry at the toolset URL instead of
/mcp. An agent on Blue Leaf needs no header; an outside client sends your API key as the Bearer token. - Toolset tools take any params: list them in each tool's description so the model fills them in.
- On chat-widget runs, tools get the visitor as
context.visitor: the page's cookies (context.visitor.cookies) and URL (context.visitor.currentUrl). The platform sets it, so a model can't substitute another visitor. Each site's tools pick the cookie they need. - Tools still run as you, with your secrets, so keep a public toolset to tools meant for visitors.
Tools are managed by agents, not the UI. The Tools page is a read-only listing. To add, update, or delete tools, ask an agent with MCP access: it calls
Create_Tool/Update_Tool/Delete_Toolon your behalf.
Files & resources
Your workspace (/workspace/...) is one file tree shared by the Files page, agents, tools (context.fs) and the endpoints below, so an agent can drop an artifact and a script can pull it out, or the other way round. Everything is private except /workspace/public/, which anyone with the link can open.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /mcp/files/upload |
Upload one or more files (multipart). |
| GET | /mcp/files/download |
Download a file by path. |
| GET | /mcp/files/list |
List entries under a directory with size + mtime. |
| POST | /mcp/files/upload-url · /download-url |
Signed S3 URL to PUT (up to 5 GB) or GET one file directly, for files above the 10 MB the endpoints above buffer. |
| POST | /mcp/files/delete |
Delete a file by path. |
| POST | www.blle.co/services/mcp/share-file |
Public download link to a file, expiring in 1–30 days: {path, days} → share.url. List links with GET …/share-links?path=, revoke with POST …/unshare-file {id}. |
Uploading & downloading
Multipart uploads accept file (single) or files[] (multiple), plus an optional prefix field (defaults to /workspace/uploads).
Upload
curl -X POST https://api.blle.co/mcp/files/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prefix=/workspace/inbox" \
-F "file=@./report.pdf"
Download
curl -OJ https://api.blle.co/mcp/files/download?path=/workspace/inbox/report.pdf \
-H "Authorization: Bearer YOUR_API_KEY"
The per-file limit on these two is 10 MB; use the signed URLs above for anything bigger. Paths must be absolute and start with /workspace.
Documents as MCP resources
Markdown and text files under /workspace/docs/ are MCP resources: agents read and edit them as files, and MCP clients read them as resources. Keep anything you don't want shared with MCP clients outside that folder.
- URI template:
docs://documents/{key}, where the key is the path under/workspace/docs/without the extension (e.g.support/policies/returns→/workspace/docs/support/policies/returns.md). - Agents read one with the
Get_Resourcetool and the same key. - MIME type:
text/markdown. - Clients list them via the MCP
resources/listrequest and read them viaresources/read.
Long jobs, schedules & triggers
Agents can work for as long as a job takes. A run belongs to the platform, not your browser: close the chat or switch threads and the reply is waiting when you come back. If the platform restarts mid-run, the run ends as failed ("Interrupted by restart"); run it again. Tools are the short pieces: each tool call has a 5-minute limit.
Long-running work
- Long commands (renders, ffmpeg, Python, headless Chrome): the
Run_On_Runnertool waits up to an hour for a job on your runner. - Work for another agent:
Invoke_Agentruns one of your agents as a sub-agent, with no time limit, and returns its reply. - Big batches: the agent splits the work and runs a tool once per chunk.
- Recurring work: a schedule.
- From outside:
POST /agent/runsstarts an agent and answers202at once; pollGET /agent/runs/<executionId>for the reply. To start a tool without waiting, add"async": truetoPOST /tools/run; it answers202and the outcome is in the tool's history.
curl -X POST https://api.blle.co/tools/run \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"toolName": "my_tool", "params": {...}, "timeout": 300000, "async": true}'
Using a workflow tool? Let n8n, Zapier or Make do the plumbing: triggers, app connectors, timed sequences and routing. Call Blue Leaf for the steps that need an agent:
/agent/runfor a quick answer (structured JSON if the agent has a response schema), or/agent/runsfor a long run.
Schedules
A schedule sends one fixed prompt to one agent on a cron interval: the way a recurring report or a nightly sweep gets built.
- Cron format:
minute hour day month weekday - Timezone:
America/Chicago - Each run creates an execution record, same as an API call, visible on Activity or through
action=executions. - From HTTP:
POST www.blle.co/services/chatbot/scheduleswith your API key and form fieldsaction=add,agent_id(the agent's UUID),name,prompt,cron_expressionandenabled=1. Pausing, editing and deleting are on the Schedules page.
Triggers from outside services
To react to an outside event (a form, a store order, a Stripe event), let a workflow tool receive the webhook, then call Blue Leaf with your API key: POST https://api.blle.co/tools/run for a tool, or /agent/runs for an agent. Blue Leaf itself has no unauthenticated way in.
curl -X POST https://api.blle.co/tools/run \
-H "Authorization: Bearer $BLLE_API_KEY" -H "Content-Type: application/json" \
-d '{"toolName": "my_tool", "params": {"order_id": 12345}}'
Runners
The Deno sandbox is for quick API and data work. Jobs that need real programs (ffmpeg, headless Chrome, video rendering, speech-to-text) run on a runner: a machine connected to your account that runs each command in a locked-down sandbox. The runner downloads the job's inputs from your /workspace, runs the command and uploads the outputs back.
Getting a runner
Runners are set up per account; ask us to add one. It can run on your own Linux machine (it only makes an outbound connection, so no ports are opened) or we can host it. Each runner only takes jobs for its own account.
Running a job
Agents call the Run_On_Runner tool, which waits for the job and returns its result. command is the program and its arguments; inputs are /workspace files (or folders ending in /) copied into the job; outputs are file patterns to keep, saved under output_dir.
{
"command": ["ffmpeg", "-i", "talk.mp4", "-vn", "talk.mp3"],
"inputs": ["/workspace/artifacts/video/talk.mp4"],
"outputs": ["*.mp3"],
"output_dir": "/workspace/audio",
"timeout": 600
}
- Timeout up to 1 hour; files up to 5 GB each; each runner takes 2 jobs at a time and queues the rest.
- The agent waits without tying up the tool sandbox, and its reply comes back when the job is done. You don't have to keep the chat open.
- From another MCP client, call
Run_On_Runnerover MCP like any other tool. - If no runner is connected to your account, the call fails right away. A job in progress when the platform restarts is lost; run it again.
Secrets
One encrypted store for every credential on the platform. A secret is a name and a value; everything else here is about getting that value to the thing that needs it (a tool, an agent, a process on your laptop) without the value itself being written down anywhere else. Nothing that consumes a secret stores it: they all reference the name and resolve it at run time. Manage them on Secrets.
Secrets, projects & mappings
- A secret is a name, an encrypted value, and an optional description. The value can be a plain string or a JSON object.
- A project is just a label. It has no row of its own: it exists as long as some mapping names it.
- A mapping binds an environment variable to a secret within a project. The variable name is independent of the secret name, so one secret can arrive as
DB_PASSWORDin one project andPOSTGRES_PASSWORDin another. Names are upper-cased when saved. - A mapping can also carry a key. With one set, the secret is parsed as JSON and only that key's value is exported, so a single secret holding
{"host": "...", "user": "...", "password": "..."}can feed three separate environment variables. Without one, the whole value is exported as-is.
Manage secrets on All Secrets; wire up the mappings on Projects.
What reads them
| Reader | How |
|---|---|
| Tools | All of your secrets are injected into every tool run, as context.secrets and as ordinary Deno.env variables, so an SDK that picks its own key out of the environment just works. No project mapping needed; this path ignores projects entirely. |
| Agents | An agent's settings.apiKey holds the name of a secret, never a key. It is required: an agent whose secret is missing or misnamed fails the run with a 400 rather than falling back to a platform key. |
| The CLI | Exports one project's mappings into a process at launch. This is the only consumer that uses projects. |
| HTTP | Anything else: GET /secrets/:project hands back a ready-made env object. |
Endpoints
On api.blle.co. Every route resolves your API key to your user and only ever touches that user's secrets.
| Method | Path | Purpose |
|---|---|---|
| GET | /secrets |
Project names that have at least one mapping. Returns a plain array. |
| GET | /secrets/:project |
That project's environment as {VAR: value}, decrypted and with JSON keys resolved. 404 if the project has no mappings. |
| POST | /secrets/manage |
Create or update: name required, plus value and description. Sending an empty value updates only the description; it does not blank the secret. |
| DELETE | /secrets/manage/:name |
Delete by name. |
Three refusals worth coding for: 403 when the name is already taken by another user's secret (names are checked across all users, so a create can be refused by a secret you cannot see), 409 on delete when project mappings still point at the secret (the response lists them; unmap first), and 404 on delete when the name doesn't exist.
What the API can and can't do
The API manages values: create, rotate, describe, delete. It does not manage mappings: adding, editing, or removing a project mapping is a signed-in action on the Projects page. So a rotation script can replace a value and every project already pointing at it picks up the new one on next read; standing up a new project still needs a visit there.
The CLI
export SECRETS_API_KEY=<your api key>
secrets run --project <name> -- <command> [args...]
- Fetches the project's environment, adds it to the current environment, and then replaces itself with your command. There is no wrapper process and no temp file: the values exist only in the memory of the process you were launching anyway.
- Fetched values override variables already set in your shell.
- An unknown or unmapped project fails the command: the API answers
404and the CLI exits rather than launching with a thinner environment than you expected. - It presents a browser-like TLS fingerprint to get past the edge. A response that arrives as HTML is reported as
blocked by Cloudflare challenge: that's the edge, not your key. - Download it from the All Secrets page: macOS (Apple Silicon), Linux x64, Linux ARM.
Encryption
- Values are encrypted at rest with AES-256-GCM and stored as
iv:authTag:ciphertext. Encryption happens server-side on write; you always send plaintext. - A stored value that doesn't match that shape is returned as-is rather than failing, which is how older plaintext rows still read. Don't take a successful read as proof a given row was ever encrypted.
- Reads decrypt in the API process. Values are never rendered back into the UI: the list shows names, descriptions, and how many projects use each one.
From HTTP
Rotate a value
curl -X POST https://api.blle.co/secrets/manage \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "OPENAI_API_KEY", "value": "sk-...", "description": "rotated 2026-09"}'
Pull a project's environment
curl https://api.blle.co/secrets/<project> \
-H "Authorization: Bearer YOUR_API_KEY"
# {"DB_HOST":"...","DB_PASSWORD":"..."}
Delete one (unmap it first, or this answers 409)
curl -X DELETE https://api.blle.co/secrets/manage/<name> \
-H "Authorization: Bearer YOUR_API_KEY"
Every tool run sees every secret. Injection is not scoped by project or by tool, so a secret in this store is readable by any tool you run. That is what makes tools convenient to write, and it is the reason to keep credentials you would not hand to an agent out of here entirely.