# 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

v1

## 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  }'
```