Skip to main content

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.md is the prompt and agent.json the 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 agentId means 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 prompt and settings every 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/run holds the connection open. That is fine until it isn't: long calls fight every timeout in the path, which is what /agent/runs plus polling exists to avoid.
  • Add format: "json" to run or runs for structured output. The synchronous call returns it parsed, fences stripped; the poll returns the agent's raw response, so strip fences yourself.
  • Pass a sessionId to continue a conversation: runs sharing one see the prior turns. Omit it and each run starts clean. metadata carries 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 on context (const { foo } = context); return outputs the result; console.log is captured as log events.
  • Tools run inside a shared Deno sandbox with fetch() available. Import npm packages from https://esm.sh/<package>@<major>.
  • context.fs reads and writes your /workspace files (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.secrets and as Deno.env variables.
  • Tools can persist a new secret (e.g. refreshed OAuth tokens) via await context.saveSecret(name, value).
  • When an agent calls a tool, context.caller names it (agentId, agentName, folder, executionId); it is null for 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/lib imports by path: import { clients } from "lib/clients.ts".
  • A lib/... import line fails an Execute_Code run before it starts — the host resolves any import ... 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 explicit context.fs verbs — read / write / list / stat / move / delete. There is no mkdir: writing /workspace/a/b.txt creates 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.env for the run, so an SDK that reads its own key from the environment just works; a refreshed token is saved back with await 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_Tool on 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_Resource tool and the same key.
  • MIME type: text/markdown.
  • Clients list them via the MCP resources/list request and read them via resources/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_Runner tool waits up to an hour for a job on your runner.
  • Work for another agent: Invoke_Agent runs 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/runs starts an agent and answers 202 at once; poll GET /agent/runs/<executionId> for the reply. To start a tool without waiting, add "async": true to POST /tools/run; it answers 202 and 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/run for a quick answer (structured JSON if the agent has a response schema), or /agent/runs for 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/schedules with your API key and form fields action=add, agent_id (the agent's UUID), name, prompt, cron_expression and enabled=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_Runner over 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_PASSWORD in one project and POSTGRES_PASSWORD in 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 404 and 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.