Deploys

Every /v1 route for deploys. 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 deploy

GET /v1/deploys/{deployId}

Key scopes: READ and DEPLOYS.

Path parameters

Name	Type	Required	Notes
`deployId`	`string`	yes	The deploy's id.

Returns

200 with V1Deploy.

bash

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

Cancel a deploy that has not gone live

POST /v1/deploys/{deployId}/cancel

The version already live keeps serving.

Key scopes: WRITE and DEPLOYS.

Path parameters

Name	Type	Required	Notes
`deployId`	`string`	yes	The deploy's id.

Returns

200 with V1Deploy.

bash

curl -X POST "https://api.naijacloud.com/v1/deploys/$DEPLOY_ID/cancel" \
  -H "Authorization: Bearer $NC_API_KEY"

A deploy's build log, oldest line first

GET /v1/deploys/{deployId}/logs

Readable once the build has finished.

Key scopes: READ and DEPLOYS.

Path parameters

Name	Type	Required	Notes
`deployId`	`string`	yes	The deploy'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: V1DeployLogLine[], nextCursor }, where each item is V1DeployLogLine.

bash

curl "https://api.naijacloud.com/v1/deploys/$DEPLOY_ID/logs" \
  -H "Authorization: Bearer $NC_API_KEY"

Roll back to a previous deploy's image

POST /v1/deploys/{deployId}/rollback

Replays the stored image rather than rebuilding. Only a deploy that went live can be rolled back to.

Key scopes: WRITE and DEPLOYS.

Path parameters

Name	Type	Required	Notes
`deployId`	`string`	yes	The deploy'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.

Returns

202 with V1Deploy.

bash

curl -X POST "https://api.naijacloud.com/v1/deploys/$DEPLOY_ID/rollback" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

List a service's deploys, newest first

GET /v1/services/{serviceId}/deploys

Key scopes: READ and DEPLOYS.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service'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: V1Deploy[], nextCursor }, where each item is V1Deploy.

bash

curl "https://api.naijacloud.com/v1/services/$SERVICE_ID/deploys" \
  -H "Authorization: Bearer $NC_API_KEY"

Deploy a service now

POST /v1/services/{serviceId}/deploys

Builds the tracked branch (or pulls the image) and rolls it out. Also how to restart a service. Poll the deploy until it is RUNNING or FAILED.

Key scopes: WRITE and DEPLOYS.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service'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.

Returns

202 with V1Deploy.

bash

curl -X POST "https://api.naijacloud.com/v1/services/$SERVICE_ID/deploys" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Types

V1Deploy

Field	Type	Notes
`id`	`string (uuid)`
`serviceId`	`string (uuid)`
`status`	`QUEUED`, `BUILDING`, `TESTING`, `DEPLOYING`, `RUNNING`, `FAILED`, `CANCELLED`, `REPLACED`, `SUPERSEDED`
`trigger`	`PUSH`, `MANUAL`, `ROLLBACK`, `FIRST_DEPLOY`, `SYSTEM`, or `null`	What started it: a push, a person, a rollback, …
`branch`	`string`, or `null`
`commitSha`	`string`, or `null`
`commitMessage`	`string`, or `null`
`authorName`	`string`, or `null`
`buildCommand`	`string`, or `null`
`startCommand`	`string`, or `null`
`error`	`string`, or `null`	Why it failed, written for you.
`errorCode`	`MISSING_SCRIPT`, `COMMAND_NOT_FOUND`, `MODULE_NOT_FOUND`, `BUILD_FAILED`, `CRASH`, `OOM`, `PORT_NOT_LISTENING`, `HEALTH_TIMEOUT`, `IMAGE_REJECTED`, `BUILD_OOM`, `NODE_BUSY`, `NODE_LOW_DISK`, `DATA_SERVICE_ON_OTHER_NODE`, `UNKNOWN`, or `null`
`durationMs`	`number`, or `null`	From the start of work (not queueing) to the end, in ms.
`createdAt`	`string (date-time)`
`startedAt`	`string (date-time)`, or `null`
`finishedAt`	`string (date-time)`, or `null`

V1DeployLogLine

Field	Type	Notes
`id`	`string (uuid)`
`line`	`string`
`stream`	`STDOUT`, `STDERR`, `SYSTEM`
`level`	`INFO`, `WARN`, `ERROR`
`createdAt`	`string (date-time)`