> ## Documentation Index
> Fetch the complete documentation index at: https://docs.briefedmedia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows API overview

> Compose, schedule and run repeatable Briefed Research pipelines over pinned companies.

# Workflows API

A workflow is a saved research pipeline. You compose it from a closed catalogue of steps, pin the companies it runs against, publish a version, and then run it on demand, on a schedule, or from an event.

Workflows is part of Briefed Research. It is a separate surface from Briefed Intelligence's signals and markets API and from the Atlas ownership API.

## Base URL

```text theme={null}
https://research-api.briefedmedia.com
```

All routes in this reference sit beneath `/workflows`.

## What a workflow is made of

A published workflow version holds a **graph**: nodes joined by edges.

| Node kind     | Purpose                                                        |
| ------------- | -------------------------------------------------------------- |
| `trigger`     | What starts a run: on demand, a schedule, or a catalogue event |
| part          | A research or delivery step, identified by `partId`            |
| `gate`        | What happens when evidence comes back below the floor          |
| `destination` | Where the result goes                                          |

Parts are typed. Each declares what it `requires` and what it `produces`, and an edge is only legal when the upstream part produces something the downstream part requires. That contract is enforced identically when you validate and when you save, so a graph that validates will save.

See [Definitions](/api-reference/workflows/definitions) for the graph shape and [Catalogue](/api-reference/workflows/catalogue) for the available parts.

## The lifecycle

Authoring and running are deliberately separate. A definition is inert until a version of it is published, and only a published version can run.

```text theme={null}
create workflow → author a version → validate → publish → run → poll
```

[Quickstart](/api-reference/workflows/quickstart) walks the whole loop with curl.

## Access

Workflows requires a **Pro, Max or Team** Briefed Research plan. A caller without it receives `402 plan_required`.

Running a workflow draws on your research usage allowance, so API keys carry separate read and write scopes. A key can be issued that reads definitions and run history but cannot publish or run. See [Authentication](/api-reference/workflows/authentication).

## Response shape

Routes return their payload directly rather than a wrapper. A create returns the object it created:

```json theme={null}
{ "workflow": { "id": "wf_...", "name": "Coverage pack" } }
```

Errors carry an `error` code and, where the failure is structured, the specific faults:

```json theme={null}
{ "error": "invalid_graph", "errors": [{ "code": "unmet_requirement", "nodeId": "n2", "requires": ["subjects"] }] }
```

See [Errors](/api-reference/workflows/errors) for the full list.

## Honest degrade

Briefed Research does not fabricate financial data. Where a run cannot obtain evidence, it reports that state rather than substituting a plausible value, and the evidence gate decides whether a below-floor result is held or delivered. A `null` in a response is meaningful.