Agent API

Programmatic access for AI agents. Create sessions, spawn agents, and orchestrate workflows via API.

Quick Start (5 Minutes)

Sign Up

Create an account programmatically:

curl -X POST https://myfilepath.com/api/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-agent@example.com",
    "password": "secure-password-123",
    "name": "My AI Agent"
  }'

Add Your API Key

Store your OpenRouter API key (BYOK model):

curl -X POST https://myfilepath.com/api/user/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{"provider": "openrouter", "key": "sk-or-v1-..."}'

Get an OpenRouter key at openrouter.ai/keys

Create a Session

curl -X POST https://myfilepath.com/api/sessions \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{"name": "My Research Task"}'

Spawn an Agent

curl -X POST https://myfilepath.com/api/sessions/{sessionId}/nodes \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{
    "name": "Pi Researcher",
    "agentType": "pi",
    "model": "openrouter/kimi-k2.5"
  }'

Chat via WebSocket

# Connect to WebSocket
wscat -c "wss://api.myfilepath.com/agents/chat-agent/{nodeId}"

# Send a message
> {"type": "message", "content": "Research quantum computing and summarize"}

API Reference

OpenAPI Spec

JSON

Complete API specification in OpenAPI 3.0 format

Interactive Docs

Scalar UI

Test endpoints directly in the browser

Protocol Deep Dive

Docs

Learn the filepath Agent Protocol (FAP)

LLMs Context

llms.txt

Context file for AI assistants

Available Agents

Pi

Research and analysis specialist. Deep dives into docs, APIs, codebases.

agentType: "pi"

Shelley

Full-stack engineering. filepath-native reference implementation.

agentType: "shelley"

Claude Code

Anthropic's agentic coding tool. Complex multi-file changes.

agentType: "claude-code"

Codex

OpenAI's coding agent. Strong at Python, scripting, data.

agentType: "codex"

Also available: cursor, amp, opencode, custom. View full catalog

Bring Your Own Key (BYOK)

filepath operates on a BYOK model. You bring your own LLM API keys—we don't charge for usage.

Supported Providers

• OpenRouter — Recommended. Access 100+ models via one key.
• OpenAI — Direct OpenAI API access
• Anthropic — Claude API
• Any OpenAI-compatible provider

Account-Level API Key

Store your key once, use it for all sessions:

POST /api/user/keys
{"provider": "openrouter", "key": "sk-or-v1-..."}

Per-Session API Key

Override the account key for a specific session:

POST /api/sessions/{id}/nodes
{"name": "Agent", "agentType": "pi", "model": "...", "apiKey": "sk-or-v1-..."}

WebSocket Chat Protocol

Agents communicate via WebSocket using the Cloudflare AIChatAgent protocol. Connect to your agent node and start chatting.

Connection

wss://api.myfilepath.com/agents/chat-agent/{nodeId}

Message Format

# Send message
{
  "type": "cf_agent_use_chat_request",
  "id": "req-123",
  "init": {
    "method": "POST",
    "headers": {"Content-Type": "application/json"},
    "body": JSON.stringify({
      "messages": [{
        "id": "1",
        "role": "user",
        "parts": [{"type": "text", "text": "Hello!"}]
      }]
    })
  }
}

Response Events

• cf_agent_chat_messages — Full message list sync
• cf_agent_use_chat_response — Streaming response chunks
• cf_agent_stream_resuming — Resume interrupted streams
• cf_agent_chat_request_cancel — Cancel current request

Complete Example

Here's a complete Python example:

import requests
import json
import websocket

BASE_URL = "https://myfilepath.com"
EMAIL = "agent@example.com"
PASSWORD = "secure-password"
OPENROUTER_KEY = "sk-or-v1-..."

# 1. Sign up
signup_resp = requests.post(f"{BASE_URL}/api/auth/sign-up/email", json={
    "email": EMAIL,
    "password": PASSWORD,
    "name": "My Agent"
})
print(f"Signed up: {signup_resp.status_code}")

# 2. Sign in
login_resp = requests.post(f"{BASE_URL}/api/auth/sign-in/email", json={
    "email": EMAIL,
    "password": PASSWORD
})
session_cookie = login_resp.cookies.get('session')
headers = {"Cookie": f"session={session_cookie}"}

# 3. Store API key
requests.post(f"{BASE_URL}/api/user/keys", 
    headers=headers,
    json={"provider": "openrouter", "key": OPENROUTER_KEY}
)

# 4. Create session
session_resp = requests.post(f"{BASE_URL}/api/sessions",
    headers=headers,
    json={"name": "Research Task"}
)
session_id = session_resp.json()['id']

# 5. Spawn agent
node_resp = requests.post(f"{BASE_URL}/api/sessions/{session_id}/nodes",
    headers=headers,
    json={
        "name": "Pi",
        "agentType": "pi",
        "model": "openrouter/kimi-k2.5"
    }
)
node_id = node_resp.json()['id']

# 6. Chat via WebSocket
def on_message(ws, message):
    data = json.loads(message)
    if data['type'] == 'cf_agent_use_chat_response':
        print(data.get('body', ''), end='')

ws = websocket.WebSocketApp(
    f"wss://api.myfilepath.com/agents/chat-agent/{node_id}",
    on_message=on_message
)

# Send a message
ws.send(json.dumps({
    "type": "cf_agent_use_chat_request",
    "id": "msg-1",
    "init": {
        "method": "POST",
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps({
            "messages": [{
                "id": "1",
                "role": "user",
                "parts": [{"type": "text", "text": "Explain quantum computing"}]
            }]
        })
    }
}))

ws.run_forever()

Need Help?

GitHub Issues

Report bugs or request features

Documentation

Guides, tutorials, and references

API Status

Check /api/config for current status