Skip to main content

Projects & Cohorts

Organize your fleet: projects group your work; cohorts group devices for targeted deployments and access control.

Endpoints

MethodPathDescription
GET/api/orgs/{org_id}/projectsList projects
POST/api/orgs/{org_id}/projectsCreate a project
GET/api/orgs/{org_id}/projects/{id}Get a project
PUT/api/orgs/{org_id}/projects/{id}Update a project
DELETE/api/orgs/{org_id}/projects/{id}Delete a project
POST/api/orgs/{org_id}/projects/{id}/access/usersGrant a user project access
DELETE/api/orgs/{org_id}/projects/{id}/access/users/{user_id}Revoke a user's project access
POST/api/orgs/{org_id}/projects/{id}/access/groupsGrant a group project access
DELETE/api/orgs/{org_id}/projects/{id}/access/groups/{group_id}Revoke a group's project access
GET/api/orgs/{org_id}/projects/{project_id}/cohortsList cohorts in a project
POST/api/orgs/{org_id}/projects/{project_id}/cohortsCreate a cohort
GET/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}Get a cohort
PUT/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}Update a cohort
DELETE/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}Delete a cohort
POST/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/usersGrant a user cohort access
DELETE/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/users/{user_id}Revoke a user's cohort access
POST/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/groupsGrant a group cohort access
DELETE/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/groups/{group_id}Revoke a group's cohort access
GET/api/orgs/{org_id}/cohortsList all cohorts in the org

List projects

GET /api/orgs/{org_id}/projects

Lists projects the caller can access. Paginated when a pagination param is supplied.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.

Query parameters:

NameTypeRequiredDescription
cursorstringNoOpaque pagination cursor from a prior response's meta.after/meta.before.
limitintegerNoMax items per page (clamped 1–100). Defaults to 20. Range 1–100.
directionstringNoPage direction relative to the cursor. One of: after, before. Defaults to "after".

Responses:

StatusBodyDescription
200data: array of Project, meta: PaginationMetaProjects.
401ErrorAuthentication is missing, invalid, or expired.

Example request:

curl "https://connect.peridio.com/api/orgs/{org_id}/projects" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"data": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"organization_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z"
}
],
"meta": {
"after": "string",
"before": "string",
"has_next": true,
"has_previous": true,
"total": 0
}
}

Create a project

POST /api/orgs/{org_id}/projects

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.

Request body:

FieldTypeRequiredDescription
projectobjectYes
project.namestringYes
project.descriptionstringNo
project.everyone_enabledbooleanNo

Responses:

StatusBodyDescription
201data: ProjectCreated.
422ValidationErrorRequest body failed validation.

Example request:

curl -X POST "https://connect.peridio.com/api/orgs/{org_id}/projects" \
-H "Authorization: Bearer $AVOCADO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": {
"name": "string",
"description": "string",
"everyone_enabled": true
}
}'

Example response (201):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"organization_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z"
}
}

Get a project

GET /api/orgs/{org_id}/projects/{id}

Returns the project with its access users and groups.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
idstring

Responses:

StatusBodyDescription
200data: ProjectWithAccessProject.
404ErrorResource not found.

Example request:

curl "https://connect.peridio.com/api/orgs/{org_id}/projects/{id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"organization_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z",
"access_users": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"email": "string",
"username": "string"
}
],
"access_groups": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string"
}
]
}
}

Update a project

PUT /api/orgs/{org_id}/projects/{id}

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
idstring

Request body:

FieldTypeRequiredDescription
projectobjectYes
project.namestringNo
project.descriptionstringNo
project.everyone_enabledbooleanNo

Responses:

StatusBodyDescription
200data: ProjectUpdated.
404ErrorResource not found.
422ValidationErrorRequest body failed validation.

Example request:

curl -X PUT "https://connect.peridio.com/api/orgs/{org_id}/projects/{id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": {
"name": "string",
"description": "string",
"everyone_enabled": true
}
}'

Example response (200):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"organization_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z"
}
}

Delete a project

DELETE /api/orgs/{org_id}/projects/{id}

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
idstring

Responses:

StatusBodyDescription
200OkDeleted.
404ErrorResource not found.

Example request:

curl -X DELETE "https://connect.peridio.com/api/orgs/{org_id}/projects/{id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"ok": true
}

Grant a user project access

POST /api/orgs/{org_id}/projects/{id}/access/users

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
idstring

Request body:

FieldTypeRequiredDescription
user_idstringYes

Responses:

StatusBodyDescription
200data: ProjectWithAccessAccess granted; returns the project with updated access lists.
404ErrorResource not found.

Example request:

curl -X POST "https://connect.peridio.com/api/orgs/{org_id}/projects/{id}/access/users" \
-H "Authorization: Bearer $AVOCADO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"user_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12"
}'

Example response (200):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"organization_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z",
"access_users": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"email": "string",
"username": "string"
}
],
"access_groups": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string"
}
]
}
}

Revoke a user's project access

DELETE /api/orgs/{org_id}/projects/{id}/access/users/{user_id}

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
idstring
user_idstring

Responses:

StatusBodyDescription
200OkRevoked.
404ErrorResource not found.

Example request:

curl -X DELETE "https://connect.peridio.com/api/orgs/{org_id}/projects/{id}/access/users/{user_id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"ok": true
}

Grant a group project access

POST /api/orgs/{org_id}/projects/{id}/access/groups

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
idstring

Request body:

FieldTypeRequiredDescription
group_idstringYes

Responses:

StatusBodyDescription
200data: ProjectWithAccessAccess granted; returns the project with updated access lists.
404ErrorResource not found.

Example request:

curl -X POST "https://connect.peridio.com/api/orgs/{org_id}/projects/{id}/access/groups" \
-H "Authorization: Bearer $AVOCADO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"group_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12"
}'

Example response (200):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"organization_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z",
"access_users": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"email": "string",
"username": "string"
}
],
"access_groups": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string"
}
]
}
}

Revoke a group's project access

DELETE /api/orgs/{org_id}/projects/{id}/access/groups/{group_id}

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
idstring
group_idstring

Responses:

StatusBodyDescription
200OkRevoked.
404ErrorResource not found.

Example request:

curl -X DELETE "https://connect.peridio.com/api/orgs/{org_id}/projects/{id}/access/groups/{group_id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"ok": true
}

List cohorts in a project

GET /api/orgs/{org_id}/projects/{project_id}/cohorts

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.

Query parameters:

NameTypeRequiredDescription
cursorstringNoOpaque pagination cursor from a prior response's meta.after/meta.before.
limitintegerNoMax items per page (clamped 1–100). Defaults to 20. Range 1–100.
directionstringNoPage direction relative to the cursor. One of: after, before. Defaults to "after".

Responses:

StatusBodyDescription
200data: array of Cohort, meta: PaginationMetaCohorts.

Example request:

curl "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"data": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"project_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"device_count": 0,
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z"
}
],
"meta": {
"after": "string",
"before": "string",
"has_next": true,
"has_previous": true,
"total": 0
}
}

Create a cohort

POST /api/orgs/{org_id}/projects/{project_id}/cohorts

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.

Request body:

FieldTypeRequiredDescription
cohortobjectYes
cohort.namestringYes
cohort.descriptionstringNo
cohort.everyone_enabledbooleanNo

Responses:

StatusBodyDescription
201data: CohortCreated.
422ValidationErrorRequest body failed validation.

Example request:

curl -X POST "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts" \
-H "Authorization: Bearer $AVOCADO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"cohort": {
"name": "string",
"description": "string",
"everyone_enabled": true
}
}'

Example response (201):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"project_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"device_count": 0,
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z"
}
}

Get a cohort

GET /api/orgs/{org_id}/projects/{project_id}/cohorts/{id}

Returns the cohort with access lists.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.
idstring

Responses:

StatusBodyDescription
200data: CohortWithAccessCohort.
404ErrorResource not found.

Example request:

curl "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"project_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"device_count": 0,
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z",
"access_users": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"email": "string",
"username": "string"
}
],
"access_groups": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string"
}
]
}
}

Update a cohort

PUT /api/orgs/{org_id}/projects/{project_id}/cohorts/{id}

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.
idstring

Request body:

FieldTypeRequiredDescription
cohortobjectYes
cohort.namestringNo
cohort.descriptionstringNo
cohort.everyone_enabledbooleanNo

Responses:

StatusBodyDescription
200data: CohortUpdated.
404ErrorResource not found.
422ValidationErrorRequest body failed validation.

Example request:

curl -X PUT "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"cohort": {
"name": "string",
"description": "string",
"everyone_enabled": true
}
}'

Example response (200):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"project_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"device_count": 0,
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z"
}
}

Delete a cohort

DELETE /api/orgs/{org_id}/projects/{project_id}/cohorts/{id}

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.
idstring

Responses:

StatusBodyDescription
200OkDeleted.
404ErrorResource not found.

Example request:

curl -X DELETE "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"ok": true
}

Grant a user cohort access

POST /api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/users

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.
idstring

Request body:

FieldTypeRequiredDescription
user_idstringYes

Responses:

StatusBodyDescription
200data: CohortWithAccessAccess granted; returns the cohort with updated access lists.
404ErrorResource not found.

Example request:

curl -X POST "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/users" \
-H "Authorization: Bearer $AVOCADO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"user_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12"
}'

Example response (200):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"project_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"device_count": 0,
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z",
"access_users": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"email": "string",
"username": "string"
}
],
"access_groups": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string"
}
]
}
}

Revoke a user's cohort access

DELETE /api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/users/{user_id}

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.
idstring
user_idstring

Responses:

StatusBodyDescription
200OkRevoked.
404ErrorResource not found.

Example request:

curl -X DELETE "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/users/{user_id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"ok": true
}

Grant a group cohort access

POST /api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/groups

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.
idstring

Request body:

FieldTypeRequiredDescription
group_idstringYes

Responses:

StatusBodyDescription
200data: CohortWithAccessAccess granted; returns the cohort with updated access lists.
404ErrorResource not found.

Example request:

curl -X POST "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/groups" \
-H "Authorization: Bearer $AVOCADO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"group_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12"
}'

Example response (200):

{
"data": {
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"project_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"device_count": 0,
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z",
"access_users": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"email": "string",
"username": "string"
}
],
"access_groups": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string"
}
]
}
}

Revoke a group's cohort access

DELETE /api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/groups/{group_id}

Admin only.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.
project_idstring (uuid)Project UUID.
idstring
group_idstring

Responses:

StatusBodyDescription
200OkRevoked.
404ErrorResource not found.

Example request:

curl -X DELETE "https://connect.peridio.com/api/orgs/{org_id}/projects/{project_id}/cohorts/{id}/access/groups/{group_id}" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"ok": true
}

List all cohorts in the org

GET /api/orgs/{org_id}/cohorts

Lists cohorts across all projects the caller can access.

Path parameters:

NameTypeDescription
org_idstring (uuid)Organization UUID.

Query parameters:

NameTypeRequiredDescription
cursorstringNoOpaque pagination cursor from a prior response's meta.after/meta.before.
limitintegerNoMax items per page (clamped 1–100). Defaults to 20. Range 1–100.
directionstringNoPage direction relative to the cursor. One of: after, before. Defaults to "after".

Responses:

StatusBodyDescription
200data: array of Cohort, meta: PaginationMetaCohorts.

Example request:

curl "https://connect.peridio.com/api/orgs/{org_id}/cohorts" \
-H "Authorization: Bearer $AVOCADO_TOKEN"

Example response (200):

{
"data": [
{
"id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"name": "string",
"description": "string",
"everyone_enabled": true,
"project_id": "0198a2e6-6f24-7cc3-b456-663cd21c4b12",
"device_count": 0,
"inserted_at": "2026-08-14T12:00:00Z",
"updated_at": "2026-08-14T12:00:00Z"
}
],
"meta": {
"after": "string",
"before": "string",
"has_next": true,
"has_previous": true,
"total": 0
}
}

Object reference

Project

FieldTypeDescription
idstring
namestring
descriptionstringNullable.
everyone_enabledbooleanWhen true, all org members have access; otherwise access is granted per-user/group.
organization_idstring
inserted_atstring (date-time)
updated_atstring (date-time)

PaginationMeta

Cursor pagination metadata. Present only when the request supplied a pagination param (cursor, limit, or direction); otherwise the full list is returned unpaginated with no meta.

FieldTypeDescription
afterstringOpaque cursor for the next page. Pass back as ?cursor=. Nullable.
beforestringOpaque cursor for the previous page. Nullable.
has_nextboolean
has_previousboolean
totalintegerNullable.

Error

Standard error envelope.

FieldTypeDescription
errorstringMachine-readable error code.
messagestringHuman-readable explanation.

ValidationError

Changeset validation error. Keys are field names; values are lists of messages.

FieldTypeDescription
errorsobject

ProjectWithAccess

FieldTypeDescription
idstring
namestring
descriptionstringNullable.
everyone_enabledbooleanWhen true, all org members have access; otherwise access is granted per-user/group.
organization_idstring
inserted_atstring (date-time)
updated_atstring (date-time)
access_usersarray of AccessUser
access_groupsarray of AccessGroup

AccessUser

FieldTypeDescription
idstring
namestring
emailstring
usernamestringNullable.

AccessGroup

FieldTypeDescription
idstring
namestring

Ok

Simple acknowledgement.

FieldTypeDescription
okboolean

Cohort

FieldTypeDescription
idstring
namestring
descriptionstringNullable.
everyone_enabledboolean
project_idstring
device_countintegerPresent on list responses.
inserted_atstring (date-time)
updated_atstring (date-time)

CohortWithAccess

FieldTypeDescription
idstring
namestring
descriptionstringNullable.
everyone_enabledboolean
project_idstring
device_countintegerPresent on list responses.
inserted_atstring (date-time)
updated_atstring (date-time)
access_usersarray of AccessUser
access_groupsarray of AccessGroup