Storage

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

A workspace's buckets in one region

GET /v1/workspaces/{workspaceId}/buckets

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.
`region`	`string`	no

Returns

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

bash

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

Create a bucket

POST /v1/workspaces/{workspaceId}/buckets

Key scopes: WRITE and PLATFORM_API.

Path parameters

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

Query parameters

Name	Type	Required	Notes
`region`	`string`	no	The bucket's region; the workspace default when omitted.

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	3–63 lowercase letters, digits, dots and hyphens; unique across Naijacloud.
`visibility`	`PRIVATE`, `PUBLIC_READ`	no

Returns

201 with V1StorageBucket.

bash

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

Delete a bucket

DELETE /v1/workspaces/{workspaceId}/buckets/{bucket}

Refused while it holds objects unless force=true, which deletes them too.

Key scopes: WRITE and PLATFORM_API.

Path parameters

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

Query parameters

Name	Type	Required	Notes
`region`	`string`	no	The bucket's region; the workspace default when omitted.
`force`	`boolean`	no

Returns

204 with no body.

bash

curl -X DELETE "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/buckets/$BUCKET" \
  -H "Authorization: Bearer $NC_API_KEY"

The workspace's storage access keys (IDs only, never secrets)

GET /v1/workspaces/{workspaceId}/storage/access-keys

Key scopes: READ and PLATFORM_API.

Path parameters

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

Returns

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

bash

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

A bucket's CORS rules

GET /v1/workspaces/{workspaceId}/buckets/{bucket}/cors

Key scopes: READ and PLATFORM_API.

Path parameters

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

Query parameters

Name	Type	Required	Notes
`region`	`string`	no	The bucket's region; the workspace default when omitted.

Returns

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

bash

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

Replace a bucket's CORS rules

PUT /v1/workspaces/{workspaceId}/buckets/{bucket}/cors

Key scopes: WRITE and PLATFORM_API.

Path parameters

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

Query parameters

Name	Type	Required	Notes
`region`	`string`	no	The bucket's region; the workspace default when omitted.

Body

Field	Type	Required	Notes

Returns

204 with no body.

bash

curl -X PUT "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/buckets/$BUCKET/cors" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Remove a bucket's CORS rules

DELETE /v1/workspaces/{workspaceId}/buckets/{bucket}/cors

Key scopes: WRITE and PLATFORM_API.

Path parameters

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

Query parameters

Name	Type	Required	Notes
`region`	`string`	no	The bucket's region; the workspace default when omitted.

Returns

204 with no body.

bash

curl -X DELETE "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/buckets/$BUCKET/cors" \
  -H "Authorization: Bearer $NC_API_KEY"

A bucket's policy document, or null

GET /v1/workspaces/{workspaceId}/buckets/{bucket}/policy

Key scopes: READ and PLATFORM_API.

Path parameters

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

Query parameters

Name	Type	Required	Notes
`region`	`string`	no	The bucket's region; the workspace default when omitted.

Returns

200 with V1BucketPolicy.

bash

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

Replace a bucket's policy

PUT /v1/workspaces/{workspaceId}/buckets/{bucket}/policy

Key scopes: WRITE and PLATFORM_API.

Path parameters

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

Query parameters

Name	Type	Required	Notes
`region`	`string`	no	The bucket's region; the workspace default when omitted.

Body

Field	Type	Required	Notes
`policy`	`string`	yes	An S3 bucket policy document, as JSON text.

Returns

204 with no body.

bash

curl -X PUT "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/buckets/$BUCKET/policy" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"policy":"…"}'

Remove a bucket's policy (makes it private)

DELETE /v1/workspaces/{workspaceId}/buckets/{bucket}/policy

Key scopes: WRITE and PLATFORM_API.

Path parameters

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

Query parameters

Name	Type	Required	Notes
`region`	`string`	no	The bucket's region; the workspace default when omitted.

Returns

204 with no body.

bash

curl -X DELETE "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/buckets/$BUCKET/policy" \
  -H "Authorization: Bearer $NC_API_KEY"

Types

V1BucketPolicy

Field	Type	Notes
`policy`	`string`, or `null`

V1CorsRule

Field	Type	Notes
`allowedHeaders`	array of `string`, or `null`
`allowedMethods`	array of `string`
`allowedOrigins`	array of `string`
`exposeHeaders`	array of `string`, or `null`
`maxAgeSeconds`	`integer`, or `null`

V1StorageAccessKey

Field	Type	Notes
`accessKeyId`	`string`	The S3 access key ID. Safe to show.
`createdAt`	`string (date-time)`
`id`	`string`
`name`	`string`	What the key is for, e.g. "storefront uploads".
`updatedAt`	`string (date-time)`

V1StorageBucket

Field	Type	Notes
`createdAt`	`string`, or `null`
`endpoint`	`string`
`name`	`string`
`publicBaseUrl`	`string`, or `null`
`region`	`string`
`visibility`	`PRIVATE`, `PUBLIC_READ`, or `null`