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

# Workflow API Overview

> List, create, update, publish, and delete workflows, and read paginated run history through the public API

The Workflow API lets you manage workflow definitions and read paginated run history. Use it to sync workflows from a repository, publish a draft, or inspect node inputs and outputs. Flattened run export stays on a separate endpoint.

## Base URL

```
https://api.langdock.com
```

<Warning>
  **Dedicated deployments**

  Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.
</Warning>

## API key scopes

Workflow access is split into three scopes. A key can hold any combination of them.

| Scope                 | Settings label            | Endpoints                                                                                                                                                                                                                                    |
| --------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WORKFLOW_API`        | **Workflow Read API**     | [List](/en/developer/workflow-api/list-workflows), [get](/en/developer/workflow-api/get-workflow), [paginated runs](/en/developer/workflow-api/list-workflow-runs), and [flattened export](/en/developer/workflow-api/intro-to-workflow-api) |
| `WORKFLOW_WRITE_API`  | **Workflow Write API**    | [Create](/en/developer/workflow-api/create-workflow), [update](/en/developer/workflow-api/update-workflow), [publish](/en/developer/workflow-api/publish-workflow)                                                                           |
| `WORKFLOW_DELETE_API` | **Workflow Deletion API** | [Delete](/en/developer/workflow-api/delete-workflow)                                                                                                                                                                                         |

Create a workspace API key under [Settings > Workspace > Products > API](/en/admin/workspace/workspace#api). A personal API key can include **Workflow Read API**, and **Workflow Write API** when your admin allows it. **Workflow Deletion API** cannot be granted on a personal key. See [Personal API keys](/en/using-langdock/account/personal-api-keys).

The API runs as the key's configured user. Workspace keys run as a service account. Personal keys run as their owner.

## Available endpoints

| Method   | Endpoint                       | Description                                                               |
| -------- | ------------------------------ | ------------------------------------------------------------------------- |
| `GET`    | `/workflows/v1/list`           | [List workflows](/en/developer/workflow-api/list-workflows)               |
| `POST`   | `/workflows/v1/create`         | [Create a workflow](/en/developer/workflow-api/create-workflow)           |
| `GET`    | `/workflows/v1/get`            | [Get a workflow](/en/developer/workflow-api/get-workflow)                 |
| `PATCH`  | `/workflows/v1/update`         | [Update a workflow](/en/developer/workflow-api/update-workflow)           |
| `POST`   | `/workflows/v1/publish`        | [Publish a workflow](/en/developer/workflow-api/publish-workflow)         |
| `DELETE` | `/workflows/v1/delete`         | [Delete a workflow](/en/developer/workflow-api/delete-workflow)           |
| `GET`    | `/workflows/v1/runs`           | [List workflow runs](/en/developer/workflow-api/list-workflow-runs)       |
| `GET`    | `/workflows/{workflowId}/runs` | [Export flattened runs](/en/developer/workflow-api/intro-to-workflow-api) |

Paginated runs (`/workflows/v1/runs`) return run objects with node executions, filters such as `runMode`, and a cursor. Flattened export (`/workflows/{workflowId}/runs`) returns date-bounded rows, is not paginated, and is capped at 10,000 runs.

## Workflow object

Get, create, update, and publish return the same workflow object:

```typescript theme={null}
{
  id: string;
  name: string;
  description: string | null;
  status: "ACTIVE" | "INACTIVE";
  timezone: string | null;
  createdAt: string;
  updatedAt: string;
  createdBy: string;
  owner: { id: string; name: string | null };
  versionId: string;
  version: string;
  nodes: Array<object>;
  edges: Array<object>;
  versions: Array<{
    id: string;
    version: string;
    description: string;
    createdAt: string;
  }>;
  activeVersion: {
    id: string;
    version: string;
    description: string;
    createdAt: string;
    updatedAt: string;
    createdBy: string;
    nodes: Array<object>;
    edges: Array<object>;
  } | null;
  hasPublishedVersion: boolean;
  limits: {
    monthlyCostUsd: number | null;
    perRunCostUsd: number | null;
    maxExecutionsPerHour: number | null;
  };
}
```

`nodes` and `edges` are the draft graph (version `0`). `activeVersion` is the published graph when one exists. Secret-like fields such as webhook secrets are redacted. Sending a redacted graph back in an update keeps the stored secrets.

## Permissions

| Action                | Required access                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| List or get           | Viewer access. Workspace admin identities, including workspace API keys, see every non-template workflow.                                 |
| Paginated runs        | Editor access                                                                                                                             |
| Flattened export      | Owner or editor. A **User** role does not grant this export. See [Workflow Run Export](/en/developer/workflow-api/intro-to-workflow-api). |
| Create                | `createWorkflows` permission                                                                                                              |
| Update or publish     | Editor access                                                                                                                             |
| Delete                | Editor access and `WORKFLOW_DELETE_API`. The builder still requires owner access.                                                         |
| `shareWith` on create | `shareWorkflows` permission                                                                                                               |

Created workflows stay private to the key until you pass `shareWith` or someone shares them later. Workspace admins can share a workflow with an active workspace API key from **Share**. Use **Search people, groups and API keys** to find the key. Personal keys are not share targets because they already act as their owner.

Templates cannot be created, listed, or published through this API.

## Rate limits

The Workflow API follows standard API rate limits. If you exceed the limit, you receive a `429` response. Wait and retry with exponential backoff.

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>