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.

Creating an account is not part of the API: sign up in the browser, where the flow includes email verification and GitHub sign-in. The same goes for resetting a forgotten password — see Account Security.

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 cos_pk_.

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 cos_pk_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

Prefer a client library to raw HTTP? The SDKs for JavaScript, Python and PHP handle authentication, retries and errors for you.

• Deploy an app — see Deploy an App from Git, Deploy a Next.js App or Deploy a Container Image, and the Apps API
• Find a domain, or verify one you own — see the Domains API
• Set up email sending — see the SMTP Setup guide
• Add a database — see the Databases guide
• Add a cache — see Connect to Redis
• Manage buckets and container images — 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, 502, 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) and 403 INSUFFICIENT_ROLE (the role you, or the key's service account, hold in the project does not allow the request).

503 is always temporary — retry the request after a short pause. 502 (BAD_GATEWAY) means a service the request depends on failed; it is usually temporary too.

Errors

Branch on error.code, not on error.message — codes are stable, while the wording of messages may change. When an error is one you can fix on your side, the body also carries a docsUrl linking to the section that explains the fix:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "API key does not have apps:write permission",
    "docsUrl": "https://cosmoner.com/docs#insufficient_scope"
  }
}

docsUrl is optional. Errors with nothing for you to change, such as NOT_FOUND or INTERNAL_ERROR, leave it out. Some errors add further fields next to code and message, such as issues on a validation error.

UNAUTHORIZED

401 — the request carried no credential the API accepts. Either the Authorization header is missing or not in the form Bearer <your-api-key>, or the key in it has been revoked or has expired.

Check that your script or pipeline actually reads the key from wherever you stored it, and sends it as shown in Using API Keys. If the key was revoked or has expired, create a new one.

INVALID_API_KEY

401 — the API key in the request could not be verified. It may be mistyped or truncated, or it may have been revoked or expired. Copy the key again from your secret store, or create a replacement and revoke the old one.

INSUFFICIENT_SCOPE

403 — the key is valid, but it does not carry the permission the route requires. The message names the missing permission, for example apps:write.

Add that permission to the key — in the control panel under Project → API keys, or with PATCH /v1/projects/:projectId/api-keys/:id, which replaces the key's permissions with the full set you send. See Permission Scopes for what each permission covers. A key created with no permissions ticked has none at all and gets this error on every scoped route.

INSUFFICIENT_ROLE

403 — the request is allowed by the key's scopes, but not by the role behind it: yours for a signed-in session, a CLI login or a personal access token, the service account's for a project API key. A developer cannot change members, plans, API keys, secrets, variables or project settings, and only an owner can delete a project. The details field names the permission refused and the role that holds it. See Team Roles for what each role can do; an owner or admin can change a role.

API_KEY_WRONG_ORGANIZATION

403 — the key belongs to a different project than the one in the request path. A key can only act on the project it was created in. Check the project id in the URL, or use a key created in the project you are addressing.

API_KEY_NOT_ALLOWED

401 — the action can only be taken by a person signed in to the control panel, not with an API key. This applies to inviting, removing and changing the role of a member, to viewing and answering your own invitations, to signing or ending a service agreement, and to account and sign-in actions. Do it in the control panel instead.

VALIDATION_ERROR

422 — the request body, path parameters or query parameters did not match what the endpoint accepts. The issues field mirrors the shape of your input: errors lists the problems at each level, properties holds one entry per object field, and items one per array element.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "issues": {
      "errors": [],
      "properties": { "name": { "errors": ["Too small: expected string to have >=1 characters"] } }
    },
    "docsUrl": "https://cosmoner.com/docs#validation_error"
  }
}

Fix the fields it names and send the request again. Retrying it unchanged returns the same error. The endpoint's page in the API reference, and the OpenAPI document, list the fields it accepts.

RATE_LIMITED

429 — you are sending requests faster than the API allows, and this one was rate-limited. Wait before retrying. If the response carries a Retry-After header, wait at least that many seconds; otherwise back off, increasing the wait after each refusal. Spreading requests out, or reusing results rather than fetching them again, keeps you clear of the limit.

ACCOUNT_BANNED

403 — the account this API key or session belongs to has been suspended, so every request made with it is refused. Retrying will not help. Contact support if you believe this is a mistake.

Billing errors

Billing errors link to the Billing & Payments guide:

• 402 ORG_PAYMENT_METHOD_REQUIRED and 402 BILLER_PAYMENT_METHOD_REQUIRED — the project has no card to charge, so it cannot deploy a billable resource. See The Project Payment Method.
• 403 ACCOUNT_BLOCKED — an unpaid invoice has blocked the project or account. See Resolving a Blocked Account.

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.

Docs for AI assistants and agents

These docs are published in forms a language model can read directly:

• /llms.txt indexes every page with a one-line summary, following the llms.txt convention.
• /llms-full.txt is every page in one Markdown file, for tools that would rather load everything at once.
• Any docs page as Markdown: add .md to its URL — https://cosmoner.com/docs/guides/secrets.md — or request the page with an Accept: text/markdown header.

Each page also has a Copy Markdown button under its title, and an Open menu that hands the page to ChatGPT, Claude or Cursor.

Docs MCP server

AI tools that support the Model Context Protocol can search and read these docs directly. Add this URL as a remote MCP server — no API key or sign-in is needed:

https://cosmoner.com/docs/mcp

In Claude Code, for example:

claude mcp add --transport http cosmoner-docs https://cosmoner.com/docs/mcp

The server offers three read-only tools:

• search_docs finds the pages and sections that match a query.
• get_doc_page returns a page as Markdown — the same text as its .md URL.
• list_doc_pages lists every page with a one-line summary, like /llms.txt.

It reads the public docs only. It cannot see or change anything in your account. It is rate-limited per client: a caller that sends too many requests too quickly gets 429 Too Many Requests with a Retry-After header saying how many seconds to wait.

To let an agent work on your project itself — read app logs, redeploy, set variables — connect the platform MCP server with an API key instead.