Projects

Every /v1 route for projects. This page is generated from the API's OpenAPI contract, so it always matches what the API accepts and returns.

Authentication, pagination, errors and idempotency work the same on every route. They are described once, in the API overview.

Get a project, with its environments

GET /v1/projects/{projectId}

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`projectId`	`string`	yes	The project's id.

Returns

200 with V1Project.

bash

curl "https://api.naijacloud.com/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

Change a project's name, display name or description

PATCH /v1/projects/{projectId}

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`projectId`	`string`	yes	The project's id.

Body

Field	Type	Required
`name`	`string`	no
`displayName`	`string`	no
`description`	`string`	no

Returns

200 with V1Project.

bash

curl -X PATCH "https://api.naijacloud.com/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","displayName":"…"}'

Delete a project and everything in it

DELETE /v1/projects/{projectId}

Irreversible: tears down every service in every environment, data included. Requires ADMIN.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`projectId`	`string`	yes	The project's id.

Returns

204 with no body.

bash

curl -X DELETE "https://api.naijacloud.com/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

List a project's environments

GET /v1/projects/{projectId}/environments

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`projectId`	`string`	yes	The project's id.

Returns

200 with a page: { data: V1Environment[], nextCursor }, where each item is V1Environment.

bash

curl "https://api.naijacloud.com/v1/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer $NC_API_KEY"

List a workspace's projects, newest first

GET /v1/workspaces/{workspaceId}/projects

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Query parameters

Name	Type	Required	Notes
`limit`	`integer`	no	Rows per page. Ignored when a cursor is given.
`cursor`	`string`	no	The `nextCursor` of the previous page, unchanged.

Returns

200 with a page: { data: V1Project[], nextCursor }, where each item is V1Project.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/projects" \
  -H "Authorization: Bearer $NC_API_KEY"

Create a project

POST /v1/workspaces/{workspaceId}/projects

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Headers

Name	Type	Required	Notes
`Idempotency-Key`	`string`	no	Any unique string (1–255 printable characters). A retry with the same key and body returns the first response instead of acting twice, for 24 hours.

Body

Field	Type	Required	Notes
`name`	`string`	yes	e.g. `shop`
`displayName`	`string`	no
`description`	`string`	no
`region`	`string`	no	Region key. New services in the project are placed there unless they name another. e.g. `af-west`

Returns

201 with V1Project.

bash

curl -X POST "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/projects" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"shop"}'

Types

V1Environment

Field	Type	Notes
`id`	`string (uuid)`
`projectId`	`string (uuid)`
`name`	`string`	e.g. `production`
`isPreview`	`boolean`	True for a pull-request preview environment.
`paused`	`boolean`	True while this environment is paused on its own. A paused project stops it too without setting this.
`pausedAt`	`string (date-time)`, or `null`
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

V1Project

Field	Type	Notes
`id`	`string (uuid)`
`workspaceId`	`string (uuid)`
`name`	`string`	e.g. `shop`
`displayName`	`string`, or `null`
`description`	`string`, or `null`
`defaultRegion`	`string`, or `null`	Region new services in this project are placed in, e.g. "af-west".
`paused`	`boolean`
`pausedAt`	`string (date-time)`, or `null`
`environments`	array of `V1Environment`	Included when one project is fetched; omitted from lists.
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`