---
title: List administered projects
sidebar_label: List administered projects
sidebar_position: 1
description: List every project you administer, with the tenant code you need to enter it, to build a project picker.
---

# List administered projects

| Method | Path |
| --- | --- |
| `GET` | `/v1/projects` |

[Authentication](/authentication) · [Projects](/projects)

Lists every project in which you are an admin, with the tenant code of each. Every other route works on the single project in your token. Use this one to build a project picker.

**Auth:** Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. You do not need to be an admin of the project in your token. The session must belong to a user, so a client application session is refused.
**Scope:** Your own user. The list is built from your Practitioner memberships across all projects, and keeps only those where the membership is an admin one. You never see anyone else's projects.

## Request

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Zero-based page number. Default `0`, minimum `0`. |
| `count` | `integer` | No | Projects per page. Default `20`, minimum `1`, maximum `100`. |

## Behaviour

- Only memberships where you are an admin count. A project where you are a plain member is not listed.
- There is one row per project, even when you hold two memberships on it.
- Rows follow the order of your memberships. No sort is applied, so sort on your side if you need one.
- `page` and `count` page over the projects. `total` is the number of projects you administer, not the number of memberships. A page past the end returns an empty `resources` array.
- `tenantCode` is `null` for a project that has none.
- `name` is `null` when the project can no longer be read. The row is kept, so the list stays consistent with `total`.
- `isMainProject` is `true` for a project with no parent and `false` for a child. It is `null` when the project hierarchy could not be read. Treat `null` as "unknown" and show a flat list, not as `true`.
- `parentProjectId` is set only when the parent is also a project you administer. Otherwise it is `null`, including for a project with no parent. This lets a picker group children under a parent it is also listing.
- To enter one of these projects, sign in again and send its `tenantCode` in step 3 of practitioner sign-in (`POST /auth/tenant/Practitioner/login/token`). A token is scoped to one project.
- No access policy permission is checked beyond the role above. The route only reads your own memberships.

## Example

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/projects?page=0&count=20' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response

`200` — One page of the projects you administer.

```json
{
  "total": 2,
  "page": 0,
  "count": 20,
  "resources": [
    {
      "projectId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
      "name": "Example Health Group",
      "tenantCode": "example-health-group",
      "isMainProject": true,
      "parentProjectId": null
    },
    {
      "projectId": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
      "name": "Example Clinic North",
      "tenantCode": "example-clinic-north",
      "isMainProject": false,
      "parentProjectId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of projects you administer, across all pages. |
| `page` | `integer` | Page number of this response. |
| `count` | `integer` | Page size you asked for. The page can hold fewer rows. |
| `resources` | `object[]` | The projects of this page. |
| `resources[].projectId` | `string (uuid)` | Project id. |
| `resources[].name` | `string \| null` | Project name. `null` when the project can no longer be read. |
| `resources[].tenantCode` | `string \| null` | Code that selects the project at sign-in. `null` when the project has none. |
| `resources[].isMainProject` | `boolean \| null` | `true` when the project has no parent, `false` when it is a child, `null` when the hierarchy could not be read. |
| `resources[].parentProjectId` | `string (uuid) \| null` | The parent, only when you administer it too. |

## Errors

| Status | Meaning |
| --- | --- |
| `401` | Bearer token is missing, invalid, revoked or expired, or the session has no user, as with a client application. |
| `403` | The session is not a practitioner, admin, super admin or System Owner session. |
| `422` | `page` or `count` fails validation: not a number, `page` below `0`, or `count` outside `1` to `100`. |
| `429` | Too many requests. Retry after a short wait. |