---
title: List sub-projects
sidebar_label: List sub-projects
sidebar_position: 2
description: Read where your current project sits in the hierarchy, with its parent and its direct sub-projects.
---

# List sub-projects

| Method | Path |
| --- | --- |
| `GET` | `/v1/sub-project` |

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

Returns the id of your current project, the id of its parent and the ids of its direct sub-projects. Use it to find out which projects hang below yours, for example after you create one.

The same route also answers at `/sub-project`, without `/v1`.

**Auth:** Bearer token of a project admin, meaning the membership of the caller in the token's project is an admin one. A practitioner who is not an admin is refused.
**Scope:** The caller's project (from the token).

## Request

No parameters.

## Behaviour

- `currentProjectId` is the project in your token.
- `parentProjectId` is the project yours is a sub-project of, or `null` when yours has no parent.
- `subProjectIds` lists direct children only. Grandchildren are not included.
- The list is not paged and has no cap. It is empty when the project has no sub-projects.
- The ids come from the parent-child records, and the route does not read the projects themselves. It returns ids, not names. For project details use [`GET /v1/slim/project/child`](/slim-apis/project/list-child-project-relationships), which also allows practitioners who are not admins.
- The result is kept for up to 5 minutes. Creating or deleting a sub-project with [`POST /v1/sub-project`](/projects/create-sub-project) or [`DELETE /v1/sub-project/:subProjectId`](/projects/delete-sub-project) refreshes it at once. Other changes to the hierarchy can take up to 5 minutes to show.
- No access policy permission is checked beyond the admin role.

## Example

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/sub-project' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response

`200` — The project's place in the hierarchy.

```json
{
  "currentProjectId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "parentProjectId": null,
  "subProjectIds": [
    "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
    "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02"
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `currentProjectId` | `string (uuid)` | The project in your token. |
| `parentProjectId` | `string (uuid) \| null` | The parent project. `null` when the project has no parent. |
| `subProjectIds` | `string[]` | Ids of the direct sub-projects. Empty array when there are none. |

## Errors

| Status | Meaning |
| --- | --- |
| `400` | The session carries no project. |
| `401` | Bearer token is missing, invalid, revoked or expired. |
| `403` | The caller is not an admin of the project in the token. |
| `429` | Too many requests. Retry after a short wait. |