# Report a drift run from CI

> Page: https://docs.plotwork.dev/api/post-orgs-org-drift-runs. Index of every page: https://docs.plotwork.dev/llms.txt

What one run of the GitHub Action's generate command found in one repository: per source its status, change counts, errors and owners.

`POST /orgs/{org}/drift/runs`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Report a drift run from CI. |
| What does it take? | A JSON body of type [`DriftRunBody`](https://docs.plotwork.dev/api/schemas.md#driftrunbody). |
| What does it return? | Status 201 with a body of type [`DriftRunReceipt`](https://docs.plotwork.dev/api/schemas.md#driftrunreceipt). |
| What can go wrong? | `400` the body is not valid; `401` no key, or the key is not valid; `403` not an organisation key (orgs.org_key_required), or the owner's plan does not include the drift dashboard (plan.drift_dashboard_not_included); `404` no such organisation, or the key is another organisation's; `413` the body is larger than 1 mib; `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope. |

## What it does

What one run of the GitHub Action's generate command found in one repository: per source its status, change counts, errors and owners. Metadata only, never a file or diagram source. An organisation key only; `_` as `{org}` means the key's own organisation. On a plan with the drift dashboard.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |

## Request body

The body has the type [`DriftRunBody`](https://docs.plotwork.dev/api/schemas.md#driftrunbody).

| Field | Type | Required | Description |
|---|---|---|---|
| `repository` | `string` | yes | The repository the run checked, as owner/name. at most 140 characters; pattern `^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$`. |
| `ref` | `string \| null` | yes | The git ref the run checked, or null. at least 1 character; at most 255 characters; pattern `^[^\p{Cc}]+$/u`. |
| `sha` | `string \| null` | yes | The commit the run checked, or null. pattern `^[0-9a-fA-F]{7,64}$`. |
| `event` | `string \| null` | yes | The event that started the run, or null. at least 1 character; at most 64 characters; pattern `^[a-z][a-z0-9_]*$`. |
| `runUrl` | `string \| null` | yes | The run on GitHub. An https address of at most 500 characters, or null. at most 500 characters. |
| `pullRequestUrl` | `string \| null` | yes | The pull request the run opened or checked. An https address of at most 500 characters, or null. at most 500 characters. |
| `sources` | `DriftSourceBody[]` | yes | Every source the run checked, at most 250. A source of the repository that a run leaves out is removed from the dashboard. |
| `sources[].name` | `string` | yes | The source's name as the repository's settings write it, 1 to 120 characters. Unique within a run. at least 1 character; at most 120 characters; pattern `^[^\p{Cc}]+$/u`. |
| `sources[].out` | `string` | yes | The diagram's path in the repository, 1 to 300 characters. at least 1 character; at most 300 characters; pattern `^[^\p{Cc}]+$/u`. |
| `sources[].status` | `"in-step" \| "drifted" \| "written" \| "failed"` | yes | What the check found: the diagram matches its files (in-step), differs (drifted), was written by the run (written), or could not be made (failed). |
| `sources[].added` | `integer` | yes | Items in the files that the diagram does not have. minimum 0; maximum 1000000. |
| `sources[].removed` | `integer` | yes | Items in the diagram that the files no longer have. minimum 0; maximum 1000000. |
| `sources[].changed` | `integer` | yes | Items both have that differ. minimum 0; maximum 1000000. |
| `sources[].errors` | `integer` | yes | Errors the run met making this diagram. minimum 0; maximum 1000000. |
| `sources[].owners` | `string[]` | yes | The owners CODEOWNERS gives the diagram's path, as it writes them: at most 20, each @user, @org/team or an email address. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 201 | Stored. | [`DriftRunReceipt`](https://docs.plotwork.dev/api/schemas.md#driftrunreceipt) |
| 400 | The body is not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | No key, or the key is not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | Not an organisation key (orgs.org_key_required), or the owner's plan does not include the drift dashboard (plan.drift_dashboard_not_included). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, or the key is another organisation's. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 413 | The body is larger than 1 MiB. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Organisations are not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 201 answer has the type [`DriftRunReceipt`](https://docs.plotwork.dev/api/schemas.md#driftrunreceipt).

| Field | Type | Required | Description |
|---|---|---|---|
| `organization` | `object` | yes | The organisation the run was stored for. With `_` in the path, this says which one the key belongs to. |
| `organization.id` | `string` | yes |  |
| `organization.slug` | `string` | yes |  |
| `repository` | `string` | yes | The repository, as sent. |
| `sources` | `integer` | yes | Sources stored. minimum 0. |
| `drifted` | `integer` | yes | Sources that drifted. minimum 0. |
| `dashboardUrl` | `string` | yes | The organisation's drift dashboard in the portal, for a signed-in member. |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |