# Publish now

`POST /v1/publications/{id}/run`

Queues a run that publishes what changed: unchanged documents are skipped (content hash), remote edits are detected and pulled back or shown as a divergence, never overwritten. `force` republishes unchanged documents. `scheduledAt` runs it later. A waiting run absorbs repeated requests.

Scope: `docs:write`.

## Request

```bash
curl -X POST "https://api.lydie.co/v1/publications/01JCQ3V5MZ8G4ZK2X7T9R6N1PB/run" \
  -H "Authorization: Bearer $LYDIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Path parameters

- `id` (ULID, required)

## Body

- `force` (boolean, optional): Default: `false`.
- `scheduledAt` (timestamp, optional)

## Response

- `run` (PublicationRun, required): A run and its log.
  - `id` (ULID, required)
  - `publicationId` (ULID, required)
  - `action` (string, required): One of: `publish`, `unpublish`, `resolve`.
  - `trigger` (string, required): One of: `manual`, `auto`, `poll`.
  - `options` (object, required)
  - `status` (string, required): One of: `queued`, `running`, `succeeded`, `partial`, `failed`, `cancelled`.
  - `attempt` (integer, required)
  - `runAt` (timestamp, required)
  - `steps` (object[], required)
    - `at` (timestamp, required)
    - `step` (string, required)
    - `status` (string, required): One of: `ok`, `skipped`, `error`, `info`.
    - `documentId` (string, optional)
    - `ms` (number, optional)
    - `detail` (object, optional)
  - `summary` (object, required, nullable)
  - `error` (object, required, nullable)
  - `requestedBy` (string, required)
  - `createdAt` (timestamp, required)
  - `startedAt` (timestamp, required, nullable)
  - `finishedAt` (timestamp, required, nullable)

```json
{
  "run": {
    "id": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
    "publicationId": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
    "action": "publish",
    "trigger": "manual",
    "options": {},
    "status": "queued",
    "attempt": -9007199254740991,
    "runAt": "2026-11-12T09:30:00.000Z",
    "steps": [
      {
        "at": "2026-11-12T09:30:00.000Z",
        "step": "string",
        "status": "ok",
        "documentId": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
        "ms": 0,
        "detail": {}
      }
    ],
    "summary": null,
    "error": null,
    "requestedBy": "string",
    "createdAt": "2026-11-12T09:30:00.000Z",
    "startedAt": null,
    "finishedAt": null
  }
}
```

Errors use the envelope described at https://developers.lydie.co/errors.md.