# List series

Returns a page of the series your organisation is licensed for, each with a `content_version`. Use it in a CMS sync job: when `content_version` equals the value you stored, nothing changed and you can skip [Get series metadata](https://docs.wandura.ai/developers/reference/series-get).

```
GET /api/delivery/v1/series
```

**Scope:** `metadata:read`

## Description
Lists your licensed series, oldest change first. Pass `updated_since` (Unix epoch seconds) to get only the series changed after that moment. A series whose licence ended stays in the list as `withdrawn` for 30 days, so your sync job sees it. Successful responses are wrapped in the `{code, message, data, server_time}` envelope; errors use the same envelope without `data`, except `429` and `400` `unsupported_version`, which use the flat format. This endpoint shares its rate-limit counter with the [catalog](https://docs.wandura.ai/developers/reference/catalog).

Your CMS may override any field. Wandura never overwrites your edits: store the `content_version` you imported and keep your own edits.

## Request parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Authorization` | header | string | Yes | `Bearer <API key>` for a key with the `metadata:read` scope. |
| `updated_since` | query | integer | No | Optional. Unix epoch seconds; only series changed after this moment are returned. |
| `limit` | query | integer | No | Optional. Items per page, 1 to 100. Default 50. |
| `cursor` | query | string | No | Optional. `next_cursor` of the previous page, passed back unchanged. |
| `Wandura-Version` | header | string | No | Optional. A dated API version (YYYY-MM-DD) to use for this request instead of the version pinned to your API key. Unknown or retired values answer 400 with `error_code` `unsupported_version`. |

Keep the same `updated_since` on every page of one sync, and follow `next_cursor` until it is `null`.

## Request example
```bash
curl -s "https://www.wandura.ai/api/delivery/v1/series?updated_since=1790390000&limit=50" \
  -H "Authorization: Bearer $WANDURA_API_KEY"
```

## Response
`200 OK`. New fields may be added at any time: ignore the ones you do not recognise.

| Field | Type | Description |
|---|---|---|
| `code` | integer | `0`. |
| `message` | string | `"ok"`. |
| `data.next_cursor` | string or null | Pass it back as `cursor`; `null` on the last page. |
| `server_time` | integer | Server time in Unix epoch seconds. |
| `links` | object | Ready-made absolute URLs of a list response. Follow them instead of building URLs. |

### Fields of a series (`data.items[]`)
| Field | Type | Description |
|---|---|---|
| `code` | string | Series code, for example `WD000016`. |
| `status` | string | `active`: you may stream it now. `withdrawn`: your licence ended or was suspended, or Wandura took the series down; it stays in this list for 30 days so your sync job sees it. New values may be added. |
| `updated_at` | integer | Last change in Unix epoch seconds (metadata, licence or episodes in your media space). |
| `content_version` | string or null | Hash of everything GET /series/{code} returns for you. Unchanged = no need to fetch the detail. `null` when withdrawn. |
| `episode_count` | integer or null | Published episodes. `null` when withdrawn. |
| `withdrawn_at` | integer or null | When it was withdrawn (epoch seconds), or `null`. |
| `film_status` | string or null | Production state of the film in Wandura's catalogue: `published` (released), `draft` (in progress, not released yet) or `archived` (taken down). Not the same as `status`, which says whether you may stream it. Whether every planned episode is out is `is_completed`. New values may be added. |
| `tier` | string or null | Wandura's quality tier of the film, `S` highest to `F` lowest, or `null` when not rated yet. It is not an age rating (see `content_rating`). |

## Response example
```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "code": "WD000016",
        "status": "active",
        "updated_at": 1790390000,
        "content_version": "c3f1a9e07b2d4c5e8f9a0b1c2d3e4f50",
        "episode_count": 60,
        "withdrawn_at": null,
        "film_status": "published",
        "tier": "A"
      },
      {
        "code": "WD000021",
        "status": "withdrawn",
        "updated_at": 1790395000,
        "content_version": null,
        "episode_count": null,
        "withdrawn_at": 1790395000,
        "film_status": "archived",
        "tier": null
      }
    ],
    "next_cursor": null
  },
  "server_time": 1790400000
}
```

## Response headers
| Header | Responses | Description |
|---|---|---|
| `Wandura-API-Status` | all | API status. `beta` today, on every response, success or error. |
| `Wandura-Version` | 200 | The dated API version (YYYY-MM-DD) this response was produced in: the version pinned to your API key, or the one you sent in the `Wandura-Version` request header. Keys created before dated versions existed use `2026-10-02`. |
| `Wandura-Request-Id` | 200 | An opaque id for this request (`req_` followed by 26 characters). Every response carries it, errors included, and error bodies repeat it as `request_id`. Log it, and quote it when you contact Wandura about a request: it finds the exact request in our logs. Do not parse it. |
| `Cache-Control` | 200 | Always `no-store`. Do not cache these responses in shared caches. |
| `Retry-After` | 429 | Seconds to wait before retrying. Sent with 429 and with retryable 503 responses. |

## Errors
| Status | `code` | When |
|---|---|---|
| 400 | none | The `Wandura-Version` header, or the version pinned to your key, is unknown or retired. |
| 401 | 4010 | The `Authorization: Bearer` header is missing. |
| 401 | 4011 | The key is unknown or revoked. |
| 403 | 4030 | The key lacks the `metadata:read` scope. |
| 403 | 4031 | Your organisation's access is suspended. |
| 422 | 4220 | `limit` is not 1 to 100, `updated_since` is not epoch seconds, or `cursor` is not a value this endpoint returned. |
| 429 | none | Rate limit reached. |
| 503 | 5030 | The list is temporarily unavailable. |
| 503 | 5031 | Wandura could not verify the API key in time. |

What to do for each: [Errors](https://docs.wandura.ai/developers/concepts/errors#series-errors).