API Reference | Diaphora Docs | Diaphora

FragsRouter OpenAPI

The REST API for running blueprints 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 · curlCopy

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

Responses

200OKtext/event-stream

Request · curlCopy

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 '{\n    "parameters": {},\n    "auth_overrides": [\
      {\
        "type": "mcp",\
        "name": "…",\
        "token": "…"\
      }\
    ],\n    "resources": {},\n    "body": "…"\
  }'

ResponseCopy

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.

Responses

200OKtext/event-stream

Request · curlCopy

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 '{\n    "parameters": {},\n    "auth_overrides": [\
      {\
        "type": "mcp",\
        "name": "…",\
        "token": "…"\
      }\
    ],\n    "resources": {},\n    "body": "…"\
  }'

ResponseCopy

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 · curlCopy

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

ResponseCopy

[]

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 · curlCopy

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

ResponseCopy

[\
  {\
    "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

Request · curlCopy

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

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

Request · curlCopy

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 '{\n    "body": "…"\n  }'

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 · curlCopy

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

ResponseCopy

[\
  {\
    "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 · curlCopy

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

ResponseCopy

{}

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 · curlCopy

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 · curlCopy

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

ResponseCopy

[\
  {\
    "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 · curlCopy

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 · curlCopy

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