# impartire API — Reference: Tags

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/tags

List the org's tags

Org tags and team tags, ordered by name, each with how many assets and projects carry it. For an OAuth token, a team tag is listed only when its person is in the team (or an org admin).

Scopes: `tags:read`

Parameters:

- `q` (query, string) — Only tags whose name starts with this, ignoring case and extra spaces.
- `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 — `TagList`

- `data` (array of Tag, required)
  - `id` (string (uuid), required) — The tag's id — what DELETE …/tags/{tag_id} and `{ id }` on POST …/tags take.
  - `name` (string, required) — The tag as first typed. Tags are matched by a normalized form: case, extra spaces and invisible characters are ignored.
  - `scope` ("org" | "team", required) — `org`: the whole org's. `team`: private to one team (an OAuth token sees it only when its person is in the team or an org admin).
  - `team` (object or null, required) — The owning team, for a team tag; null for an org tag.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `usage_count` (integer, required) — How many assets and projects carry the tag, across the org.
- `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.