# impartire API — Reference: People and credits

Every path is under `https://impartire.com/api/v1`. The machine-readable contract is https://impartire.com/api/v1/openapi.json (OpenAPI 3.1).

#### GET /api/v1/people

List the org's people

The org's people (talent, crew, contributors) — archived ones left out — by name unless `sort` says otherwise. `q` searches name and bio; `nationality` matches exactly. To poll, pass `updated_after` with the newest `updated_at` you have seen (compared to the millisecond, so that person does not come back) and `sort=updated_at`; an archived person leaves the list. For an OAuth token, empty unless its person may read the org's people. Read only. 404 when the org does not have people.

Scopes: `people:read`

Parameters:

- `q` (query, string) — Case-insensitive substring of the name or the bio (as the app's people search).
- `nationality` (query, string) — Exact nationality, as the app stores it.
- `updated_after` (query, string (date-time)) — Only people changed strictly after this instant (ISO 8601 with offset), compared to the millisecond — pass the newest `updated_at` you have seen and that person is not returned again.
- `sort` (query, "name" | "-name" | "updated_at" | "-updated_at") — Default `name` (case-insensitive, the app's order); `-name`, `updated_at`, `-updated_at`. Ties break on id.
- `limit` (query, integer) — Page size, default 50. Values above 100 are treated as 100.
- `cursor` (query, string) — next_cursor from the previous page, with the other parameters unchanged.

Response 200 — `PersonList`

- `data` (array of Person, required)
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `bio` (string or null, required)
  - `nationality` (string or null, required) — As entered in the app (free text, e.g. `British`).
  - `birth_date` (string (date) or null, required) — YYYY-MM-DD, or null.
  - `credit_count` (integer, required) — How many credits the person holds on live assets of the org — org-wide, whoever asks (as the app's people list counts).
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required) — Moves when the person is edited in the app.
- `next_cursor` (string or null, required) — Pass as `cursor` to get the next page; null means this is the last page.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 422 (Problem) — validation — a bad `updated_after`, `sort`, `limit` or `cursor`.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### GET /api/v1/people/{id}

Get a person

One person of the org. Archived, foreign or (for an OAuth token whose person may not read the org's people) unreadable → 404. Send the ETag back in If-None-Match for a 304. 404 when the org does not have people.

Scopes: `people:read`

Parameters:

- `id` (path, string (uuid), required) — The person's id, from GET /api/v1/people.

Response 200 — `Person`: A person (talent, crew, contributor) the org keeps a record of. Archived people are not served.

- `id` (string (uuid), required)
- `name` (string, required)
- `bio` (string or null, required)
- `nationality` (string or null, required) — As entered in the app (free text, e.g. `British`).
- `birth_date` (string (date) or null, required) — YYYY-MM-DD, or null.
- `credit_count` (integer, required) — How many credits the person holds on live assets of the org — org-wide, whoever asks (as the app's people list counts).
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required) — Moves when the person is edited in the app.

Other responses:

- 304 — Not modified — the ETag in If-None-Match is current.
- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### GET /api/v1/people/{id}/credits

List a person's credits

The credits the person holds, from the asset's side — each asset (its current version) with its type, role and billing order — by asset name, paginated. A credit on a deleted asset is not listed. For an OAuth token, only assets its person may read. 404 for a person the credential cannot read. 404 when the org does not have people.

Scopes: `people:read`

Parameters:

- `id` (path, string (uuid), required) — The person's id, from GET /api/v1/people.
- `limit` (query, integer) — Page size, default 50. Values above 100 are treated as 100.
- `cursor` (query, string) — next_cursor from the previous page.

Response 200 — `PersonCreditList`

- `data` (array of PersonCredit, required)
  - `id` (string (uuid), required) — The credit's id.
  - `asset` (object, required) — The credited asset (its current version) and its type.
    - `id` (string (uuid), required)
    - `name` (string, required)
    - `type` (object, required)
      - `id` (string (uuid), required)
      - `name` (string, required)
  - `role` (string or null, required)
  - `billing_order` (integer or null, required)
- `next_cursor` (string or null, required) — Pass as `cursor` to get the next page; null means this is the last page.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 422 (Problem) — validation — a bad `limit` or `cursor`.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.