# 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

v1

## 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

```bash
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

```json
{
  "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

```bash
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

```json
{
  "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

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

#### Response

```json
[
  {
    "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

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

#### Response

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