🌓

API Examples

Copy-paste worked examples against the MultiTerminal REST API on http://localhost:5050, each shown in curl, PowerShell (Invoke-RestMethod), and Python (requests). For the full endpoint catalogue, see the REST API Reference.

Before you start

• The API binds to loopback only (localhost:5050). It has no auth boundary by design — it's reachable only from the local machine. Don't expose it directly; the phone story goes through the gateway (see Multi-Connect).
• MultiTerminal must be running so the API is listening. Verify with curl http://localhost:5050/health.
• All request and response bodies are JSON.
• The Python snippets assume pip install requests and a shared base URL:

import requests
BASE = "http://localhost:5050"

List tasks

GET /api/tasks — optionally filter with ?status= (all, todo, in_progress, done, suggestion).

curl

curl "http://localhost:5050/api/tasks?status=in_progress"

PowerShell

Invoke-RestMethod -Uri "http://localhost:5050/api/tasks?status=in_progress" |
  Select-Object id, title, status, assignee

Python

r = requests.get(f"{BASE}/api/tasks", params={"status": "in_progress"})
for task in r.json():
    print(task["id"], task["title"], task["status"])

Create a task

POST /api/tasks. Required: title, description, createdBy. Optional: status (default todo), priority (default normal), projectId. The response is { "taskId": "...", "task": { ... } }.

curl

curl -X POST http://localhost:5050/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix login bug",
    "description": "500 error on login when password contains special characters",
    "createdBy": "Alice",
    "status": "todo",
    "priority": "high"
  }'

PowerShell

$body = @{
  title       = "Fix login bug"
  description = "500 error on login when password contains special characters"
  createdBy   = "Alice"
  status      = "todo"
  priority    = "high"
} | ConvertTo-Json

$resp = Invoke-RestMethod -Uri "http://localhost:5050/api/tasks" `
  -Method Post -ContentType "application/json" -Body $body
$resp.taskId

Python

resp = requests.post(f"{BASE}/api/tasks", json={
    "title": "Fix login bug",
    "description": "500 error on login when password contains special characters",
    "createdBy": "Alice",
    "status": "todo",
    "priority": "high",
})
print(resp.json()["taskId"])

Send a message

Messaging is keyed by a terminal id, not a name. First register to get a terminalId via POST /api/messaging/register, then send with that id as fromTerminalId.

# 1) Register once — returns { "terminalId": "..." }
curl -X POST http://localhost:5050/api/messaging/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","docId":"cli"}'

POST /api/messaging/send — fields: fromTerminalId, to (recipient name), message, and optional priority.

curl

curl -X POST http://localhost:5050/api/messaging/send \
  -H "Content-Type: application/json" \
  -d '{
    "fromTerminalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to": "Bob",
    "message": "Build is ready for testing",
    "priority": "normal"
  }'

PowerShell

# Register, then send using the returned terminalId
$reg = Invoke-RestMethod -Uri "http://localhost:5050/api/messaging/register" `
  -Method Post -ContentType "application/json" `
  -Body (@{ name = "Alice"; docId = "cli" } | ConvertTo-Json)

$body = @{
  fromTerminalId = $reg.terminalId
  to             = "Bob"
  message        = "Build is ready for testing"
  priority       = "normal"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:5050/api/messaging/send" `
  -Method Post -ContentType "application/json" -Body $body

Python

reg = requests.post(f"{BASE}/api/messaging/register",
                    json={"name": "Alice", "docId": "cli"}).json()

requests.post(f"{BASE}/api/messaging/send", json={
    "fromTerminalId": reg["terminalId"],
    "to": "Bob",
    "message": "Build is ready for testing",
    "priority": "normal",
})

Get project context

GET /api/projects/{projectId}/context returns the single "everything an agent needs" object — the project plus all its associations (agents, MCP servers, specialists, paths, prompts, skills). List projects with GET /api/projects to find an id.

curl

# Find a project id, then fetch its context
curl http://localhost:5050/api/projects
curl http://localhost:5050/api/projects/proj-123/context

PowerShell

$ctx = Invoke-RestMethod -Uri "http://localhost:5050/api/projects/proj-123/context"
$ctx | ConvertTo-Json -Depth 6

Python

ctx = requests.get(f"{BASE}/api/projects/proj-123/context").json()
print(ctx)

Note: a missing project id returns 404 with { "error": "Project '...' not found" }.

Search the code graph

GET /api/code-graph/search?query=... finds symbols by name, with an optional type filter (class, method, interface, ...). The response is { "success": true, "count": N, "results": [ ... ] }. Index the project first (see Code Graph) — an unindexed graph returns 503.

curl

curl "http://localhost:5050/api/code-graph/search?query=MessageBroker&type=class"

PowerShell

$res = Invoke-RestMethod `
  -Uri "http://localhost:5050/api/code-graph/search?query=MessageBroker&type=class"
$res.count
$res.results | Select-Object name, type, file_path, line_number

Python

res = requests.get(f"{BASE}/api/code-graph/search",
                   params={"query": "MessageBroker", "type": "class"}).json()
print(res["count"])
for sym in res["results"]:
    print(sym["name"], sym["type"], sym["file_path"], sym["line_number"])

From a result's symbol id you can walk the graph further: /api/code-graph/callers, /api/code-graph/callees, /api/code-graph/impact, and /api/code-graph/inheritance all accept ?symbolId= (or ?symbolName=).