Docs/API Reference

API Reference

FragsRouter OpenAPI

The REST API for running plans and managing the tools they call. Every request is authenticated with a bearer token and scoped to your workspace.

Version

Base URL

/api/v1

Auth

bearer token

Authentication

Pass your key as a bearer token: Authorization: Bearer $DIAPHORA_API_KEY

Plans

Run stored or ephemeral plans and inspect the tool requirements each run depends on.

Run a plan

post/plan/{planId}/_run

Execute a stored plan by ID and return the full result once the run completes. Pass runtime parameters, auth overrides, and inline resources in the request body.

Path parameters

planIdstring · uuidRequired

Request body · application/json

parametersmapRequired

auth_overridesauth_override[]

typeenumRequired

mcpapicp

namestringRequired

tokenstringRequired

resourcesmap

bodystring

Responses

200OKapplication/json

Schema execute_response_body is defined in a shared spec and isn't inlined here.

Request · curl

curl -X POST "https://api.diaphora.ai/api/v1/plan/{planId}/_run" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {},
    "auth_overrides": [
      {
        "type": "mcp",
        "name": "…",
        "token": "…"
      }
    ],
    "resources": {},
    "body": "…"
  }'

Stream a plan run

post/plan/{planId}/_stream

Execute a stored plan and stream progress and output as Server-Sent Events. Use this for long-running plans where you want incremental tokens and step-by-step updates.

Path parameters

planIdstring · uuidRequired

Request body · application/json

parametersmapRequired

auth_overridesauth_override[]

typeenumRequired

mcpapicp

namestringRequired

tokenstringRequired

resourcesmap

bodystring

Responses

200OKtext/event-stream

Request · curl

curl -X POST "https://api.diaphora.ai/api/v1/plan/{planId}/_stream" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {},
    "auth_overrides": [
      {
        "type": "mcp",
        "name": "…",
        "token": "…"
      }
    ],
    "resources": {},
    "body": "…"
  }'

Response

event: token
data: {"delta":"…"}

event: done
data: {"status":"ok"}

Stream an ephemeral plan

post/plan/_stream

Run an unsaved (ephemeral) plan supplied inline in the request and stream the result as Server-Sent Events. Nothing is persisted.

Request body · application/json

parametersmapRequired

auth_overridesauth_override[]

typeenumRequired

mcpapicp

namestringRequired

tokenstringRequired

resourcesmap

bodystring

Responses

200OKtext/event-stream

Request · curl

curl -X POST "https://api.diaphora.ai/api/v1/plan/_stream" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {},
    "auth_overrides": [
      {
        "type": "mcp",
        "name": "…",
        "token": "…"
      }
    ],
    "resources": {},
    "body": "…"
  }'

Response

event: token
data: {"delta":"…"}

event: done
data: {"status":"ok"}

Refresh plan MCP requirements

post/plan/{planId}/_refresh-mcp-requirements

Re-evaluate the MCP servers a plan depends on and return the refreshed list. Call this after connecting new tools or rotating credentials.

Path parameters

planIdstring · uuidRequired

Responses

200OKapplication/json

An array of mcp_server.

Request · curl

curl -X POST "https://api.diaphora.ai/api/v1/plan/{planId}/_refresh-mcp-requirements" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Response

[]

Check plan MCP requirements

get/plan/{planId}/_check-mcp-requirements

Return the current readiness of every MCP requirement a plan needs, so you can prompt the user to connect anything that isn't ready yet.

Path parameters

planIdstring · uuidRequired

Responses

200OKapplication/json

array of objects

tool_typeenumRequired

mcpapicp

tools_idstring · uuidRequired

server_idstring · uuidRequired

namestringRequired

authentication_methodstringRequired

statusenumRequired

readynot_ready

urlstringRequired

challenge_urlstring

Request · curl

curl -X GET "https://api.diaphora.ai/api/v1/plan/{planId}/_check-mcp-requirements" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Response

[
  {
    "tool_type": "mcp",
    "tools_id": "b1a4…",
    "server_id": "b1a4…",
    "name": "…",
    "authentication_method": "…",
    "status": "ready",
    "url": "…",
    "challenge_url": "…"
  }
]

Tools

Discover MCP requirements and call commands on connected tool servers.

Check tool MCP requirements

get/tools/_check-mcp-requirements

List the MCP requirements for the calling context's tools and whether each one is ready to use.

Responses

200OKapplication/json

array of objects

tool_typeenumRequired

mcpapicp

tools_idstring · uuidRequired

server_idstring · uuidRequired

namestringRequired

authentication_methodstringRequired

statusenumRequired

readynot_ready

urlstringRequired

challenge_urlstring

Request · curl

curl -X GET "https://api.diaphora.ai/api/v1/tools/_check-mcp-requirements" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Response

[
  {
    "tool_type": "mcp",
    "tools_id": "b1a4…",
    "server_id": "b1a4…",
    "name": "…",
    "authentication_method": "…",
    "status": "ready",
    "url": "…",
    "challenge_url": "…"
  }
]

Check ephemeral plan requirements

post/tools/_check-mcp-requirements

Given an inline plan body, return the MCP requirements it would need — without saving the plan.

Request body · application/json

bodystringRequired

Responses

200OKapplication/json

array of objects

tool_typeenumRequired

mcpapicp

tools_idstring · uuidRequired

server_idstring · uuidRequired

namestringRequired

authentication_methodstringRequired

statusenumRequired

readynot_ready

urlstringRequired

challenge_urlstring

Request · curl

curl -X POST "https://api.diaphora.ai/api/v1/tools/_check-mcp-requirements" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "…"
  }'

Response

[
  {
    "tool_type": "mcp",
    "tools_id": "b1a4…",
    "server_id": "b1a4…",
    "name": "…",
    "authentication_method": "…",
    "status": "ready",
    "url": "…",
    "challenge_url": "…"
  }
]

List tool commands

get/tools/{toolsId}/{serverId}/_list-commands

List the callable commands exposed by a connected tool server, including each command's name, description, and input schema.

Path parameters

toolsIdstring · uuidRequired

serverIdstring · uuidRequired

Responses

200OKapplication/json

array of objects

namestring

descriptionstring

input_schemamap

Request · curl

curl -X GET "https://api.diaphora.ai/api/v1/tools/{toolsId}/{serverId}/_list-commands" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Response

[
  {
    "name": "…",
    "description": "…",
    "input_schema": {}
  }
]

Call a tool command

post/tools/{toolsId}/{serverId}/_call-command/{commandName}

Invoke a single command on a connected tool server and return its raw result.

Path parameters

toolsIdstring · uuidRequired

serverIdstring · uuidRequired

commandNamestringRequired

Responses

200OKapplication/json

A JSON object of arbitrary key/value pairs.

Request · curl

curl -X POST "https://api.diaphora.ai/api/v1/tools/{toolsId}/{serverId}/_call-command/{commandName}" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Response

{}

MCP

Manage MCP server authorization — complete OAuth handshakes and inspect the credential cache.

MCP OAuth callback

get/mcp/callback

OAuth redirect endpoint that completes an MCP server authorization handshake. The MCP provider redirects the user here with a state and code.

Query parameters

statestringRequired

codestringRequired

Responses

200OK

Request · curl

curl -X GET "https://api.diaphora.ai/api/v1/mcp/callback?state={state}&code={code}" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

List cached MCP authorizations

get/mcp/auth/cache

List cached MCP authorization entries, including the domain, client, and expiry for each.

Responses

200OKapplication/json

array of objects

idstringRequired

endpointstring

created_atstring · date-timeRequired

expirystring · date-timeRequired

client_idstring

Request · curl

curl -X GET "https://api.diaphora.ai/api/v1/mcp/auth/cache" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Response

[
  {
    "id": "…",
    "endpoint": "…",
    "created_at": "2026-01-01T00:00:00Z",
    "expiry": "2026-01-01T00:00:00Z",
    "client_id": "…"
  }
]

Delete a cached MCP authorization

delete/mcp/auth/cache/{cacheId}

Delete a cached MCP authorization entry by ID, forcing re-authorization on the next call.

Path parameters

cacheIdstringRequired

Responses

204No Content

Request · curl

curl -X DELETE "https://api.diaphora.ai/api/v1/mcp/auth/cache/{cacheId}" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Utilities

Helper endpoints for working with the runtime.

Render a template

post/util/template/_render

Render a template string against a scope object and return the resulting text. Useful for previewing prompt or message templates.

Request body · application/json

templatestringRequired

scopemapRequired

Responses

200OKtext/plain

Request · curl

curl -X POST "https://api.diaphora.ai/api/v1/util/template/_render" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "…",
    "scope": {}
  }'