---
title: Projects
sidebar_label: Projects
description: Understand projects and sub-projects on Ovok, and choose between the routes that list the projects you administer and create or delete sub-projects.
---

# Projects

A **project** is the unit of tenancy on Ovok. Your bearer token is scoped to one project, and most routes work on that project. A project is entered by signing in with its **tenant code**.

A **sub-project**, also called a child project, is a project linked below another project, its **parent**. A project has at most one parent. Projects can be nested: a sub-project can have sub-projects of its own. The routes on these pages report one level at a time, so a project lists its direct sub-projects, not its grandchildren.

Use the routes here to find the projects you administer, and to create and delete sub-projects. See [Authentication](/authentication) for tokens.

## Which route do I need?

| I want to… | Who calls | Route | Page |
| --- | --- | --- | --- |
| List every project I administer, with its tenant code | A practitioner or admin | `GET /v1/projects` | [List administered projects](/projects/list-projects) |
| See my project's parent and its direct sub-projects | A project admin | `GET /v1/sub-project` | [List sub-projects](/projects/list-sub-projects) |
| Create a sub-project of my project | A project admin | `POST /v1/sub-project` | [Create a sub-project](/projects/create-sub-project) |
| Delete an empty sub-project of my project | A project admin | `DELETE /v1/sub-project/:subProjectId` | [Delete a sub-project](/projects/delete-sub-project) |
| Add a colleague to my project | A project admin | `POST /v1/projects/me/members` | [Invite a team member](/invitations/team-members) |
| Change a project's features or settings | A project admin | See the page | [Settings and features](/settings-and-features) |

## Routes

- [`GET /v1/projects` — List administered projects](/projects/list-projects)
- [`GET /v1/sub-project` — List sub-projects](/projects/list-sub-projects)
- [`POST /v1/sub-project` — Create a sub-project](/projects/create-sub-project)
- [`DELETE /v1/sub-project/:subProjectId` — Delete a sub-project](/projects/delete-sub-project)

The three `sub-project` routes also answer without `/v1`, for example `POST /sub-project`. `GET /v1/projects` answers only with `/v1`.

## How the routes fit together

`GET /v1/projects` is the only route that looks across projects. It reads your own memberships, so it works from a practitioner session on any project you belong to. Every other route here, and most routes in these docs, works on the project in your token.

A typical flow for a sub-project, with a user token:

1. Create it with [`POST /v1/sub-project`](/projects/create-sub-project). With a user token the response carries no project id.
2. Find it with [`GET /v1/projects`](/projects/list-projects). The row carries its `tenantCode`.
3. Sign in again with that `tenantCode`. The token you get is scoped to the new project.
4. Set it up. [Features and settings](/settings-and-features) apply to the project in the token, and team members are added with [Invite a team member](/invitations/team-members).
5. When it is no longer needed and holds no residents, devices or locations, delete it with [`DELETE /v1/sub-project/:subProjectId`](/projects/delete-sub-project).

A client application token has no user behind it. It gets `projectId` in the create response, and it cannot call `GET /v1/projects`, which needs a user.

## Sub-projects and Slim project routes

The [Slim APIs](/slim-apis) have a "Projects" group, and two of its routes do the same jobs as routes here. They are not interchangeable.

| | `POST /v1/slim/project/child` | `POST /v1/sub-project` |
| --- | --- | --- |
| Who | Project admin | Project admin. A super admin may name another parent. |
| Body | `name`, `address`, `contact`, `settings` | `name`, `extension`, `parentProjectId` for super admins |
| Access policies | Copies every access policy of your project. Without one the request is refused with `424`. | Copies none at creation. Later changes made through the Slim access-policy routes are copied by name. |
| Project settings | Sets login, invitation and registration settings | Sets none. Each starts unset. |
| Thresholds | Seeded from the global defaults | Not seeded |
| Same name under one parent | Refused with `422` | Allowed. Only concurrent creates are refused with `409`. |
| Response | `{ "projectId": "...", "success": true }` | `{ "success": true }` for a user, with `projectId` added for a client application |

Use the Slim route to set up a customer or site: it copies your access policies and seeds thresholds. Use `/v1/sub-project` when you only need the project, its tenant and its admin.

| | `GET /v1/slim/project/child` | `GET /v1/sub-project` |
| --- | --- | --- |
| Who | Practitioner, admin or System Owner, with `AccessPolicy:read` | Project admin |
| Returns | Your project, its parent and its direct children, each with name, address, contact and settings | Ids only: your project, its parent and its direct children |

Deleting is the same. [`DELETE /v1/slim/project/child/:subProjectId`](/slim-apis/project/delete-a-child-project) and `DELETE /v1/sub-project/:subProjectId` run the same delete.

The other Slim project routes have no equivalent here: [get a project](/slim-apis/project/get-a-project), [update a project](/slim-apis/project/update-a-project), [list child projects with device counts](/slim-apis/project/list-child-projects-with-device-counts), [list current project users](/slim-apis/project/list-current-project-users) and [list project users](/slim-apis/project/list-project-users).

## Members, settings and features

- **Members.** The practitioners of your project are listed and managed under `/v1/projects/me/members`. Those routes are documented in [Invite a team member](/invitations/team-members) and [Invitations](/invitations), not here.
- **Features and settings.** A project created with `POST /v1/sub-project` has the standard features `bots`, `cron`, `email`, `transaction-bundles` and `websocket-subscriptions`, and no setting stored. Change them with the routes in [Settings and features](/settings-and-features), while signed in to that project.
- **Access policies.** The routes here check your role, not an access policy permission. See [Access policies](/access-policies) for how roles work in the rest of the API.

## Next

1. [List administered projects](/projects/list-projects)
2. [List sub-projects](/projects/list-sub-projects)
3. [Create a sub-project](/projects/create-sub-project)
4. [Delete a sub-project](/projects/delete-sub-project)