Services

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

Preview the build settings a repo would get

GET /v1/build-detection

Best effort: fields come back null when the repo cannot be inspected. The same detection runs again when the service is created.

Key scopes: READ and PLATFORM_API.

Query parameters

Name	Type	Required	Notes
`gitUrl`	`string`	no	A public HTTPS git URL.
`repoFullName`	`string`	no	owner/name of a repo our GitHub App can see.
`installationId`	`string`	no	The installation's id.
`branch`	`string`	no
`rootDir`	`string`	no	A folder inside the repo, e.g. "apps/api".

Returns

200 with V1DetectedBuild.

bash

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

Every service across your workspaces

GET /v1/services

A flat list (id, name, project, type), ordered by project. search matches the service and project name.

Key scopes: READ and PLATFORM_API.

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.
`search`	`string`	no	Only rows whose name contains this. Send the same value with every page of one walk.

Returns

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

bash

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

Find the deployable apps in a repo

GET /v1/build-detection/apps

The members of a monorepo, a frontend next to a backend, or just the root app, each with its proposed build settings.

Key scopes: READ and PLATFORM_API.

Query parameters

Name	Type	Required	Notes
`gitUrl`	`string`	no	A public HTTPS git URL.
`repoFullName`	`string`	no	owner/name of a repo our GitHub App can see.
`installationId`	`string`	no	The installation's id.
`branch`	`string`	no
`rootDir`	`string`	no	A folder inside the repo, e.g. "apps/api".

Returns

200 with V1DetectedRepoApps.

bash

curl "https://api.naijacloud.com/v1/build-detection/apps" \
  -H "Authorization: Bearer $NC_API_KEY"

Get a service

GET /v1/services/{serviceId}

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Returns

200 with V1Service.

bash

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

Rename a service, or change its build settings or source

PATCH /v1/services/{serviceId}

Each part is optional and applied in order: name, build, source. Build and source changes apply on the next deploy unless source.redeploy is true.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Body

Field	Type	Required	Notes
`name`	`string`	no	A label only.
`build`	`V1UpdateServiceBuild`	no
`source`	`V1UpdateServiceSource`	no

Returns

200 with V1Service.

bash

curl -X PATCH "https://api.naijacloud.com/v1/services/$SERVICE_ID" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","build":{"buildCommand":"…","startCommand":"…"}}'

Delete a service

DELETE /v1/services/{serviceId}

Irreversible: removes its containers, volumes, DNS and secrets — a database's data goes with it. Requires ADMIN.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Returns

204 with no body.

bash

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

List the services in an environment

GET /v1/environments/{environmentId}/services

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`environmentId`	`string`	yes	The environment's id.

Returns

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

bash

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

Create a service and queue its first deploy

POST /v1/environments/{environmentId}/services

A web service, static site, cron job or database. Subject to the compute gate and to your balance for paid sizes.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`environmentId`	`string`	yes	The environment'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. `api`
`type`	`WEB`, `STATIC`, `CRON`, `POSTGRES`, `MYSQL`, `MARIADB`, `MONGODB`, `REDIS`, `VALKEY`	yes
`region`	`string`	no	e.g. `eu-west`
`tier`	`FREE`, `PRO`, `STANDARD`, `STARTER`	no	Instance size. FREE uses the workspace free slot.
`sourceType`	`GITHUB_APP`, `PUBLIC_GIT`, `DOCKER_IMAGE`	no	Optional: inferred from image, gitUrl or repoFullName when omitted.
`repoFullName`	`string`	no	e.g. `acme/shop`
`gitUrl`	`string`	no	e.g. `https://github.com/acme/shop`
`image`	`string`	no	e.g. `ghcr.io/acme/api:1.2.3`
`imageCommand`	`string`	no
`installationId`	`string`	no
`branch`	`string`	no	e.g. `main`
`rootDir`	`string`	no	e.g. `apps/api`
`monorepoStrategy`	`ISOLATED`, `WORKSPACE`	no
`watchPaths`	array of `string`	no
`port`	`number`	no
`healthCheckPath`	`string`	no	e.g. `/healthz`
`buildCommand`	`string`	no
`startCommand`	`string`	no
`runtimeVersion`	`string`	no
`staticOutputDir`	`string`	no	e.g. `dist`
`staticSpa`	`boolean`	no
`staticUploadId`	`string`	no
`staticIndexPath`	`string`	no
`subdomain`	`string`	no
`schedule`	`string`	no	CRON only: a five-field cron expression, in UTC.
`command`	`string`	no	CRON only: the command each run executes.
`envVars`	array of `V1EnvVarInput`	no
`secretFiles`	array of `V1SecretFileInput`	no
`dbName`	`string`	no
`dbUser`	`string`	no
`dbPassword`	`string`	no
`connectionEnvName`	`string`	no
`injectConnectionUrl`	`boolean`	no

Returns

201 with V1Service.

bash

curl -X POST "https://api.naijacloud.com/v1/environments/$ENVIRONMENT_ID/services" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"api","type":"WEB"}'

A database's connection details

GET /v1/services/{serviceId}/connection

The password is empty for a read-only role. 404 for a service that is not a database, or not provisioned yet.

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Returns

200 with V1Connection.

bash

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

List a service's environment variables, by key

GET /v1/services/{serviceId}/env-vars

Values are blanked for a read-only role. Linked values come from a sibling database.

Key scopes: READ and PLATFORM_API.

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: V1EnvVar[], nextCursor }, where each item is V1EnvVar.

bash

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

Create or replace environment variables

PATCH /v1/services/{serviceId}/env-vars

Upserts by key. Keys not listed are left as they are.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Body

Field	Type	Required	Notes
`envVars`	array of `V1EnvVarInput`	yes	Created or replaced by key. Keys not listed are kept.

Returns

200 with V1EnvVarChange.

bash

curl -X PATCH "https://api.naijacloud.com/v1/services/$SERVICE_ID/env-vars" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"envVars":[{"key":"API_URL","value":"…"}]}'

Bring a suspended service back on the same URL

POST /v1/services/{serviceId}/resume

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Returns

200 with V1Service.

bash

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

List a service's secret files

GET /v1/services/{serviceId}/secret-files

Contents are blanked for a read-only role.

Key scopes: READ and PLATFORM_API.

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: V1SecretFile[], nextCursor }, where each item is V1SecretFile.

bash

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

Create or replace one secret file

PUT /v1/services/{serviceId}/secret-files

Mounted into the container on the next deploy.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Body

Field	Type	Required	Notes
`path`	`string`	yes	e.g. `config/credentials.json`
`content`	`string`	yes

Returns

200 with V1SecretFileChange.

bash

curl -X PUT "https://api.naijacloud.com/v1/services/$SERVICE_ID/secret-files" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"config/credentials.json","content":"…"}'

Remove one secret file by path

DELETE /v1/services/{serviceId}/secret-files

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Query parameters

Name	Type	Required	Notes
`path`	`object`	yes

Returns

200 with V1SecretFileChange.

bash

curl -X DELETE "https://api.naijacloud.com/v1/services/$SERVICE_ID/secret-files?path=%5Bobject%20Object%5D" \
  -H "Authorization: Bearer $NC_API_KEY"

Stop a service, keeping everything else

POST /v1/services/{serviceId}/suspend

Variables, domains, build settings, history and volumes are kept. Compute stops being billed.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Returns

200 with V1Service.

bash

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

Remove one environment variable

DELETE /v1/services/{serviceId}/env-vars/{key}

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.
`key`	`string`	yes

Returns

200 with V1EnvVarChange.

bash

curl -X DELETE "https://api.naijacloud.com/v1/services/$SERVICE_ID/env-vars/$KEY" \
  -H "Authorization: Bearer $NC_API_KEY"

Types

V1Connection

Field	Type	Notes
`scheme`	`string`	e.g. `postgresql`
`host`	`string`	Host reachable from your other services.
`port`	`number`
`database`	`string`
`username`	`string`
`password`	`string`	Empty for a read-only role: it may see where the database is, not log in.
`url`	`string`	Internal connection URL.
`externalUrl`	`string`, or `null`	Public URL, when external access is on.

V1DetectedApp

Field	Type	Notes
`rootDir`	`string`	The folder, "." for the repo root.
`name`	`string`
`deployable`	`boolean`
`build`	`V1DetectedBuild`

V1DetectedBuild

Field	Type	Notes
`runtime`	`string`, or `null`
`runtimeVersion`	`string`, or `null`
`framework`	`string`, or `null`
`packageManager`	`string`, or `null`
`buildCommand`	`string`, or `null`
`startCommand`	`string`, or `null`
`port`	`number`, or `null`
`staticOutputDir`	`string`, or `null`
`staticSpa`	`boolean`, or `null`
`monorepoStrategy`	`ISOLATED`, `WORKSPACE`, or `null`
`workspaceName`	`string`, or `null`
`watchPaths`	array of `string`

V1DetectedRepoApps

Field	Type	Notes
`status`	`OK`, `RATE_LIMITED`, `NOT_FOUND`, `NOT_GITHUB`, `FAILED`	Why a scan came back empty, when it did.
`workspace`	`boolean`	Whether the repo is a workspace monorepo.
`orchestrator`	`string`, or `null`
`truncated`	`boolean`
`apps`	array of `V1DetectedApp`

V1EnvVar

Field	Type	Notes
`key`	`string`	e.g. `DATABASE_URL`
`value`	`string`	Blanked for read-only roles. Linked values are read-only.
`scope`	`ALL`, `PROD`, `UAT`, `DEV`
`secret`	`boolean`
`linked`	`boolean`	Linked in from a sibling database's connection string; change it there.

V1EnvVarChange

Field	Type	Notes
`envVars`	array of `V1EnvVar`
`needsRedeploy`	`boolean`	True when a redeploy is needed for the change to apply.
`warnings`	array of `string`

V1EnvVarInput

Field	Type	Notes
`key`	`string`	e.g. `API_URL`
`value`	`string`
`scope`	`ALL`, `PROD`, `UAT`, `DEV`	When the variable is available. Defaults to build and runtime.
`secret`	`boolean`

V1Region

Field	Type	Notes
`key`	`string`	e.g. `eu-west`
`label`	`string`	e.g. `Europe`

V1SecretFile

Field	Type	Notes
`path`	`string`	e.g. `config/credentials.json`
`content`	`string`	Blanked for read-only roles.

V1SecretFileChange

Field	Type	Notes
`secretFiles`	array of `V1SecretFile`
`needsRedeploy`	`boolean`

V1SecretFileInput

Field	Type	Notes
`path`	`string`	e.g. `config/credentials.json`
`content`	`string`

V1Service

Field	Type	Notes
`id`	`string (uuid)`
`environmentId`	`string (uuid)`
`name`	`string`	e.g. `api`
`type`	`WEB`, `STATIC`, `CRON`, `POSTGRES`, `MYSQL`, `MARIADB`, `MONGODB`, `REDIS`, `VALKEY`
`status`	`PROVISIONING`, `ACTIVE`, `ERROR`
`tier`	`FREE`, `PRO`, `STANDARD`, `STARTER`, or `null`
`url`	`string`, or `null`	The platform URL. Null for databases and before placement. e.g. `https://api-shop.naijacloud.app`
`region`	`V1Region`, or `null`
`runtime`	`string`, or `null`	e.g. `node`
`framework`	`string`, or `null`	e.g. `nextjs`
`isStatic`	`boolean`
`port`	`number`, or `null`
`healthCheckPath`	`string`, or `null`
`memoryMb`	`number`
`cpuMillicores`	`number`
`storageLimitMb`	`number`, or `null`
`source`	`V1ServiceSource`
`build`	`V1ServiceBuild`
`cron`	`V1ServiceCron`, or `null`	Set for CRON services only.
`suspension`	`NONE`, `USER`, `BILLING`, `ABUSE`	Why nothing is running, if anything: NONE, USER (suspended by a person), BILLING or ABUSE.
`health`	`HEALTHY`, `CRASH_LOOPING`, `STOPPED`, `MISSING`, `UNKNOWN`
`lastDeployedAt`	`string (date-time)`, or `null`
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

V1ServiceBuild

Field	Type	Notes
`buildCommand`	`string`, or `null`
`startCommand`	`string`, or `null`
`runtimeVersion`	`string`, or `null`	e.g. `22`
`staticOutputDir`	`string`, or `null`
`staticSpa`	`boolean`
`monorepoStrategy`	`ISOLATED`, `WORKSPACE`, or `null`
`watchPaths`	array of `string`, or `null`

V1ServiceCron

Field	Type	Notes
`schedule`	`string`, or `null`	e.g. `/15 * * *`
`command`	`string`, or `null`
`suspended`	`boolean`	Scheduled runs are paused.

V1ServiceSource

Field	Type	Notes
`type`	`GITHUB_APP`, `PUBLIC_GIT`, `DOCKER_IMAGE`, or `null`
`repoFullName`	`string`, or `null`	e.g. `acme/shop`
`gitUrl`	`string`, or `null`
`branch`	`string`, or `null`
`rootDir`	`string`, or `null`
`image`	`string`, or `null`	The public image a DOCKER_IMAGE service runs.
`imageCommand`	`string`, or `null`

V1ServiceSummary

Field	Type	Notes
`id`	`string (uuid)`
`name`	`string`
`projectName`	`string`
`type`	`WEB`, `STATIC`, `CRON`, `POSTGRES`, `MYSQL`, `MARIADB`, `MONGODB`, `REDIS`, `VALKEY`

V1UpdateServiceBuild

Field	Type	Notes
`buildCommand`	`string`
`startCommand`	`string`
`runtimeVersion`	`string`
`rootDir`	`string`
`port`	`number`
`healthCheckPath`	`string`
`monorepoStrategy`	`ISOLATED`, `WORKSPACE`
`staticOutputDir`	`string`
`staticSpa`	`boolean`
`watchPaths`	array of `string`

V1UpdateServiceSource

Field	Type	Notes
`sourceType`	`GITHUB_APP`, `PUBLIC_GIT`, `DOCKER_IMAGE`
`repoFullName`	`string`
`installationId`	`string`
`gitUrl`	`string`
`branch`	`string`
`image`	`string`
`imageCommand`	`string`
`redeploy`	`boolean`	Deploy from the new source straight away.