Getting Started

Everything on this page starts in the browser. You create your account, your project and your first API key in the control panel — the API is what you use afterwards, once you have a key to authenticate with.

1. Create an account

Go to cosmoner.com/signup and fill in the form, or use Continue with GitHub to sign up with your GitHub account instead.

Passwords must be at least 8 characters. No card is collected at signup — you add one per project, later, at the point you actually deploy something.

After submitting, check your inbox and click the verification link. You cannot sign in until your email address is verified.

There is a public POST /v1/accounts endpoint behind this form, but it exists to serve the sign-up page. Sign up in the browser: the flow includes email verification and GitHub sign-in, and neither is something you want to reimplement against the endpoint yourself.

2. Create a project

Once you are signed in you land on the control panel. Projects are workspaces for your apps, team members, and billing — every resource you create later (apps, servers, domains, databases, buckets, registries) lives inside one, so this is the first thing to make.

Click New project on the control panel home, or pick New project from the project switcher in the navbar:

Only the name is required. Use something descriptive — auth-service, marketing-website — since you can run several projects to keep different sets of apps and team members apart.

Inviting teammates is optional. Each address you add gets an email invitation to join the project; Add another gives you an extra row. You can skip this entirely and invite people later from the project's settings.

After you submit, you are offered a payment method step. You can skip that too, but a project cannot deploy any billable resource until it has a card on it, and only the project's biller can manage that card. See the Billing guide for how project billing works.

3. Create an API key

API keys are what you use for scripts, CI pipelines and integrations. They are issued from the control panel — this is the only way to get your first one.

Go to Account → API keys → Create key, name the key, and tick the permissions it needs:

Permissions are a resource plus an action. Tick only what the key needs — a deploy pipeline usually wants apps: read, write and nothing else.

A key with no permissions ticked cannot call any scoped endpoint. Leaving the grid empty does not grant full access; it grants none, and every scoped route answers 403 INSUFFICIENT_SCOPE.

When you submit, the key is shown to you exactly once:

Copy it now and store it in your secret manager or CI secrets. Leaving the page without copying it means creating a new key. Keys start with db_.

See the API Keys guide for the full scope list and for rotating or revoking a key.

4. Make your first API call

Pass the key as a bearer token:

curl https://api.cosmoner.com/v1/projects \
  -H "Authorization: Bearer db_your_key_here"

{ "success": true, "data": [{ "id": "...", "name": "northwind-labs" }] }

That is the whole authentication story for the API — there is no separate key id and secret, and no token exchange step.

5. Start building

• Deploy an app — see the Apps API
• Register a domain — see the Domains API
• Set up email sending — see the SMTP Setup guide
• Add a database — see the Databases guide
• Provision storage — see the Storage API
• Push container images — see the Container Registry guide
• Provision a server — see the Servers API

Base URL

All API requests go to:

https://api.cosmoner.com

Response format

Every response follows the same envelope:

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "..." } }

Standard HTTP status codes are used: 200, 201, 400, 401, 403, 404, 422, 429, 500, 503. The codes you are most likely to meet while getting started are 401 UNAUTHORIZED (missing or invalid key) and 403 INSUFFICIENT_SCOPE (the key is valid but lacks the permission the route requires).

503 is always temporary — retry the request after a short pause.

Machine-readable reference

The API describes itself as an OpenAPI 3.0 document:

https://api.cosmoner.com/v1/openapi.json

It is generated from the same schemas the API validates requests against, so it does not drift from the behaviour it describes. Point your own code generator at it, or load it into an API client, to work against the endpoints it covers.

Endpoints still documented only on the pages above are not in the document yet; it grows as they are migrated.