API Reference | Docs | Barndoor Automations

Barndoor Automations API

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

https://api.diaphora.ai

Auth

bearer token

Authentication

Pass your key as a bearer token:

Authorization: Bearer $DIAPHORA_API_KEY

Or, with an Ory session token from signing in, send it in its own header instead:

X-Session-Token: $DIAPHORA_SESSION_TOKEN

Run plans

Run a stored plan and get the result back in one response, or stream it as it runs.

Run a plan

post /router/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

planId string · uuid Required

ID of the plan to run. Find it with List plans.

Request body · application/json

parameters map Required
auth_overrides auth_override[]
type enum Required
name string Required
token string Required
resources map
body string

Responses

200 OK application/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/router/plan/{planId}/_run" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{\n    "parameters": {\n      "meetingQuery": "Acme Corp renewal call"\n    }\n  }'

Response

{
  "result": {},
  "document": "…",
  "warnings": []
}

Stream a plan run

post /router/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 step-by-step updates as each session starts and finishes.

Path parameters

planId string · uuid Required

ID of the plan to run. Find it with List plans.

Request body · application/json

Responses

200 OK text/event-stream

Request · curl

curl -X POST "https://api.diaphora.ai/router/plan/{planId}/_stream" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{\n    "parameters": {\n      "meetingQuery": "Acme Corp renewal call"\n    }\n  }'

Response

{
  "event": "start",
  "data": {"component":"…","session":"…"}
}

{
  "event": "end",
  "data": {"component":"…"}
}

{
  "event": "result",
  "data": {"content":{"document":"…"}}
}

Plans

Find the plans you can run, and the parameters each one takes.

List plans

get /store/plans

List the plans you can run. Each plan includes its parameters, so you can see what to pass when you run it.

Query parameters

label string[]

Only return items with this label. Repeat the parameter to pass several.

search string

Free-text search over plans.

limit integer

Maximum number of items to return.

offset integer

Number of items to skip, for paging.

order-by enum

Field to sort by.

order-mode enum

Sort direction.

signature string

Responses

200 OK application/json

array of objects

id string · uuid Required
organization_id string · uuid Required
creator_id string · uuid Required
description string Required
name string Required
visibility enum Required

user organization-read organization-write

labels string[] Required
parameters parameter_def[]
created_at string · date-time
updated_at string · date-time
signature string

Request · curl

curl -X GET "https://api.diaphora.ai/store/plans?limit=20" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Response

[
  {
    "id": "b1a4…",
    "organization_id": "b1a4…",
    "creator_id": "b1a4…",
    "description": "…",
    "name": "…",
    "visibility": "user",
    "labels": [
      "…"
    ],
    "parameters": [
      {
        "name": "…",
        "schema": {}
      }
    ],
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "signature": "…"
  }
]

Results

Look up the results of past plan runs.

List results

get /store/results

List the results of past plan runs. Filter by plan, status, label, search text or a time window, and page with limit and offset.

Query parameters

search string

Free-text search over results.

status enum

Only return successful runs or failed runs.

limit integer

Maximum number of items to return.

offset integer

Number of items to skip, for paging.

start string · date-time

Start of the time window, by when the result was created.

end string · date-time

End of the time window, by when the result was created.

plan_id string · uuid

Only return results for this plan.

label string[]

Only return items with this label. Repeat the parameter to pass several.

Responses

200 OK application/json

array of objects

id string · uuid Required
plan_id string · uuid Required
plan_name string Required
created_at string · date-time Required
error string
labels string[] Required

Request · curl

curl -X GET "https://api.diaphora.ai/store/results?plan_id={planId}&limit=20" \
  -H "Authorization: Bearer $DIAPHORA_API_KEY"

Response

[
  {
    "id": "b1a4…",
    "plan_id": "b1a4…",
    "plan_name": "…",
    "created_at": "2026-01-01T00:00:00Z",
    "error": "…",
    "labels": [
      "…"
    ]
  }
]