Cosmoner Docs
API Reference

Projects

A project is the unit of ownership and billing: every resource belongs to exactly one, and an API key reaches exactly one. Address a project by its `id` or its `slug` — both are accepted wherever `{projectId}` appears.

List projects

GET
/v1/projects

Every project the authenticated user is a member of, newest first.

Auth: a project API key carrying projects:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects"
{  "success": true,  "data": [    {      "id": "string",      "name": "string",      "slug": "string",      "billingEmail": "[email protected]",      "blockedAt": "2019-08-24T14:15:22Z",      "blockedReason": "string",      "_count": {        "servers": -9007199254740991,        "domains": -9007199254740991,        "members": -9007199254740991,        "apps": -9007199254740991,        "objectStorages": -9007199254740991,        "containerRegistries": -9007199254740991,        "databaseClusters": -9007199254740991      }    }  ]}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Fetch a project

GET
/v1/projects/{projectId}

The project, with a count of the resources it holds.

Auth: a project API key carrying projects:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string"
{  "success": true,  "data": {    "id": "string",    "name": "string",    "slug": "string",    "billingEmail": "[email protected]",    "blockedAt": "2019-08-24T14:15:22Z",    "blockedReason": "string",    "_count": {      "servers": -9007199254740991,      "domains": -9007199254740991,      "members": -9007199254740991,      "apps": -9007199254740991,      "objectStorages": -9007199254740991,      "containerRegistries": -9007199254740991,      "databaseClusters": -9007199254740991    }  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Rename a project

PATCH
/v1/projects/{projectId}

Auth: a project API key carrying all of projects:read and projects:write.

Role: the caller must be an owner or admin of the project.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/projects/string" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "success": true,  "data": {    "id": "string",    "name": "string",    "slug": "string",    "billingEmail": "[email protected]"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Delete a project

DELETE
/v1/projects/{projectId}

Deletes the project. Every resource it holds must be removed first — servers, domains, apps, buckets, registries and databases. While any remain the call returns 409 CONFLICT listing what is left.

Deletion is immediate and cannot be undone.

Auth: a project API key carrying all of projects:read and projects:write.

Role: the caller must be the project owner.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/projects/string"
{  "success": true,  "data": null}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Set the billing email

PATCH
/v1/projects/{projectId}/billing-email

Sets the address invoices and receipts are sent to. Pass null to clear it, which falls back to the account email of the member who holds billing for the project.

Auth: a project API key carrying all of projects:read and projects:write.

Role: the caller must be an owner or admin of the project.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/projects/string/billing-email" \  -H "Content-Type: application/json" \  -d '{    "billingEmail": "[email protected]"  }'
{  "success": true,  "data": {    "billingEmail": "[email protected]"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Fetch spend by resource type

GET
/v1/projects/{projectId}/stats

What the project was charged per resource type over the last five closed months, plus the month still accruing — that one is marked inProgress and is a running total, not a settled invoice.

Auth: a project API key carrying projects:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/stats"
{  "success": true,  "data": {    "resourceHistory": [      {        "month": "string",        "servers": 0,        "domains": 0,        "apps": 0,        "objectStorage": 0,        "containerRegistry": 0,        "databases": 0,        "redis": 0,        "email": 0,        "other": 0,        "inProgress": true      }    ]  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Create a project

POST
/v1/projects/create

Creates a project and the infrastructure grouping behind it.

Project names are unique per user, case-insensitively: reusing one returns 409 CONFLICT. Creation is transactional — if any step fails, everything it created is rolled back.

Auth: a project API key carrying projects:write.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/projects/create" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "success": true,  "data": {    "projectId": "string",    "projectSlug": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Accounts

Create user accounts and manage password resets.

Members

API reference for project membership, invitations, and billing responsibility.

On this page

List projectsFetch a projectRename a projectDelete a projectSet the billing emailFetch spend by resource typeCreate a project