# Cosmoner

> Deploy apps, run servers and databases, manage networking, store artifacts, and automate operations from one focused cloud platform.

Every docs page below is Markdown. Any page on https://cosmoner.com/docs is also available as Markdown by appending `.md` to its URL, or by requesting it with `Accept: text/markdown`. The whole set is concatenated at https://cosmoner.com/llms-full.txt.

The API authenticates with a project API key, sent as `Authorization: Bearer <key>`. Keys are created in the control panel and scoped per resource; see the Getting Started page.

## Docs

- [Getting Started](https://cosmoner.com/docs.md): Create your account in the control panel, set up a project, issue an API key, and make your first API call.

## Guides

- [Deploy an App from Git](https://cosmoner.com/docs/guides/deploy-an-app.md): Connect GitHub, GitLab or Bitbucket, pick a repository, and have your app built and running on a cosmoner.com address — then redeployed on every push.
- [Deploy from a Template](https://cosmoner.com/docs/guides/deploy-from-a-template.md): Start from a ready-made starter app, or add a Deploy to Cosmoner button to your own repository's README so readers can run a copy in a few clicks.
- [Deploy a Next.js App](https://cosmoner.com/docs/guides/deploy-nextjs.md): Run a Next.js app on Cosmoner from your repository — server rendering, API routes and NEXT_PUBLIC_ variables included — or ship it as a static export.
- [Deploy a Container Image](https://cosmoner.com/docs/guides/deploy-container-image.md): Run any Docker image as an app — from your Cosmoner registry, Docker Hub or the GitHub container registry — and redeploy it from CI when you push a new tag.
- [Pull Request Previews](https://cosmoner.com/docs/guides/preview-deployments.md): Give every pull request its own running copy of your app, at its own URL, rebuilt on each push and removed when the pull request closes.
- [Passkeys](https://cosmoner.com/docs/guides/passkeys.md): Sign in with Touch ID, Face ID, Windows Hello, or a security key — no password and no code, and nothing a phishing site can capture.
- [Two-Factor Authentication](https://cosmoner.com/docs/guides/two-factor-authentication.md): Add a second step to sign-in so a stolen password is not enough to reach your servers, domains, and secrets on its own.
- [Account Security](https://cosmoner.com/docs/guides/account-security.md): Active sessions, changing or resetting your password, and the emails we send when something about your account's protections changes.
- [Email notifications](https://cosmoner.com/docs/guides/email-notifications.md): Which emails Cosmoner sends, how to turn product updates and the newsletter on or off, and the notifications in the control panel.
- [App Configuration Files](https://cosmoner.com/docs/guides/app-templates.md): Commit a .cosmoner/deployment.yaml to your repository to describe your app's build, runtime, and environment configuration — the deploy wizard fills its form in from it, and your editor validates it as you write.
- [Web Hosting](https://cosmoner.com/docs/guides/web-hosting.md): How web hosting is laid out, how to run several websites and domains on it, and how to reach your files.
- [Databases](https://cosmoner.com/docs/guides/databases.md): How a managed PostgreSQL cluster is sized and billed, how to connect to it, and how to browse and edit your data from the panel.
- [Connect to Redis](https://cosmoner.com/docs/guides/redis.md): Create a managed, Redis-compatible Valkey database in Stockholm, connect to it over TLS from your app or your machine, and choose how much of it survives a restart.
- [Object Storage](https://cosmoner.com/docs/guides/object-storage.md): Choose the right storage tier, understand how usage above it is billed, set an overage limit, and manage your S3-compatible buckets.
- [Container Registry](https://cosmoner.com/docs/guides/container-registry.md): Push and pull private images from a managed Cosmoner registry, choose a region and retention policy, and understand storage and egress pricing.
- [Billing & Payments](https://cosmoner.com/docs/guides/billing-and-payments.md): Understand how billing works, what happens when payments fail, and how credits and refunds work when you remove resources.
- [SMTP Setup](https://cosmoner.com/docs/guides/smtp-setup.md): Send transactional email from your own domain using Cosmoner's SMTP service.
- [Email Templates](https://cosmoner.com/docs/guides/email-templates.md): Write transactional emails once in the control panel, in code with React Email or in the visual editor, publish them as versions, and send them by alias through the API.
- [Receiving Webhooks](https://cosmoner.com/docs/guides/webhooks.md): Subscribe to email and platform events, verify the signature, and handle retries.
- [Connect Your Cloudflare Account](https://cosmoner.com/docs/guides/cloudflare-dns.md): Connect a project-owned Cloudflare account to manage its DNS zones and simplify app custom-domain setup.
- [Team Roles](https://cosmoner.com/docs/guides/team-roles.md): What viewers, developers, admins and owners can do in a project, and how roles apply to API keys and personal access tokens.
- [API Keys](https://cosmoner.com/docs/guides/api-keys.md): API keys let you access the Cosmoner API programmatically without a browser session. Use them for CI/CD pipelines, scripts, and integrations.
- [Connect AI Agents (MCP)](https://cosmoner.com/docs/guides/mcp.md): Let an AI assistant or coding agent inspect your apps, read their logs, redeploy them and manage variables, with an API key you scope.
- [Project Secrets](https://cosmoner.com/docs/guides/secrets.md): Store and reuse sensitive values like API keys, passwords, and tokens across your project's resources. Secrets are encrypted at rest using envelope encryption.

## SDKs

- [SDK Overview](https://cosmoner.com/docs/sdk.md): Install the official JavaScript, Python and PHP SDKs, configure a client, and handle retries and errors.
- [Email](https://cosmoner.com/docs/sdk/email.md): Send transactional email from your code through a project's SMTP credential.
- [Apps](https://cosmoner.com/docs/sdk/apps.md): Deploy an image app onto a new tag or digest and wait for the rollout to finish — the step a CI job runs after pushing an image.
- [Webhooks](https://cosmoner.com/docs/sdk/webhooks.md): Verify the webhooks Cosmoner sends you, register endpoints, and inspect or replay deliveries from code.
- [Secrets and Variables](https://cosmoner.com/docs/sdk/secrets-and-variables.md): Manage the secrets and variables a deployment file refers to with from_secret and from_variable.
- [Hosting](https://cosmoner.com/docs/sdk/hosting.md): Read your web hosting sites and the SFTP and SSH details for reaching their files.
- [Deployment Files](https://cosmoner.com/docs/sdk/deployment-files.md): Validate a .cosmoner/deployment.yaml from your own code, with no API key and no network call.
- [CLI](https://cosmoner.com/docs/sdk/cli.md): The cosmoner command line tool — read and manage everything in a project, validate deployment files, deploy image apps, upload to web hosting, and manage secrets from a terminal, CI or a coding agent.
- [Terraform](https://cosmoner.com/docs/sdk/terraform.md): Manage apps, databases, Redis, buckets, secrets, variables, webhook endpoints, SSH keys and resource groups as code with the Cosmoner Terraform provider.

## Pricing

- [How Pricing Works](https://cosmoner.com/docs/pricing.md): The four ways a Cosmoner resource can be priced, and the billing rules that apply to all of them.
- [Apps Pricing](https://cosmoner.com/docs/pricing/apps.md): How web services and static sites are priced, and what a build costs.
- [Servers Pricing](https://cosmoner.com/docs/pricing/servers.md): How server sizes are priced, why a stopped server still costs money, and what deleting one credits back.
- [Object Storage Pricing](https://cosmoner.com/docs/pricing/object-storage.md): How the three tier allowances are measured, how usage above them is billed, the monthly overage limit, and how CDN delivery is metered on top.
- [Container Registry Pricing](https://cosmoner.com/docs/pricing/container-registry.md): When registry storage is measured, what counts as egress, and why the egress allowance is shared across your organization.
- [Database Pricing](https://cosmoner.com/docs/pricing/databases.md): How PostgreSQL databases are priced per size, what a size includes, and what changing or deleting one costs.
- [Valkey & Redis Pricing](https://cosmoner.com/docs/pricing/redis.md): How Valkey, our Redis-compatible key-value database, is priced per plan, what a plan fixes, and what is included.
- [Web Hosting Pricing](https://cosmoner.com/docs/pricing/web-hosting.md): How PHP web hosting is priced per tier, and what extra storage and longer backup retention cost on top.
- [Email Pricing](https://cosmoner.com/docs/pricing/email.md): Pay as you go or an email plan, the monthly cap you control, and the daily and hourly limits under it.
- [Secrets Pricing](https://cosmoner.com/docs/pricing/secrets.md): The included secrets allowance, how packs are added and removed, and why project variables are never charged.
- [Domains Pricing](https://cosmoner.com/docs/pricing/domains.md): Why domain prices vary by extension, when you see the price, and how renewals are billed.

## API Reference

- [Projects](https://cosmoner.com/docs/api/projects.md): 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.
- [Resource groups](https://cosmoner.com/docs/api/resource-groups.md): Named boxes drawn around resources on the project overview's resource graph. Groups nest, a resource sits in at most one, and they change only how the project is drawn — nothing a group holds behaves any differently for being in it.
- [Members](https://cosmoner.com/docs/api/members.md): The people in a project, each holding one role: `viewer`, `developer`, `admin` or `owner`. Viewers are read-only across the API. Developers create, change, deploy and delete the project's resources, billable ones included, but cannot change its members, plans, API keys, secrets, variables or settings. Admins can do everything except delete the project, which is the owner's alone. The payment method, refunds and service agreements are the biller's, whatever their role. Only an owner can grant the owner role, change an owner's role or remove an owner. [Team roles](/docs/guides/team-roles) lists exactly what each role may do; a request the caller's role does not allow is refused with `403 INSUFFICIENT_ROLE`.

Exactly one member is the **biller**, responsible for paying for the project. The biller cannot be removed, or leave, while they hold that responsibility — the attempt is refused with `409 BILLER_CANNOT_LEAVE` — so transfer it to another member first.

Inviting, removing and changing the role of a member are done from the control panel by a signed-in owner or admin, never with an API key: a key is refused with `401 API_KEY_NOT_ALLOWED`. A pending invitation can be cancelled through the API.
- [Apps](https://cosmoner.com/docs/api/apps.md): Managed app hosting. An app is either built from a git repository or runs a container image, and is created in two steps: save its configuration as a draft, then create the app from the draft, which charges the project's payment method and starts the first deployment.

For an app running an image from one of the project's registries, `imageDeployPolicy` decides what a push to its repository does: `TAG` (the default) redeploys the app when the tag it uses is pushed again, and leaves other tags and an app pinned to a digest alone; `NEWEST` deploys whatever tag was pushed and switches the app to it; `MANUAL` does nothing, and the app moves only through Deploy image.

**Environment variables at build time.** An app built from a repository gets its environment variables in the build as well as in the running container, so a value a framework inlines while building — `NEXT_PUBLIC_*`, `VITE_*` — is there. A plain variable is a build argument: a Dockerfile reads it with `ARG NAME`, and an auto-detected build or a static site's build command sees it in its environment without declaring anything. A variable marked secret is a BuildKit secret: it is mounted for the command that reads it and never written to an image layer, the image history or the build cache. A Dockerfile opts in per step with `RUN --mount=type=secret,id=NAME,env=NAME <command>`; auto-detected and static builds see it in the command's environment like a plain one. Names must be identifiers (`[A-Za-z_][A-Za-z0-9_]*`) — a variable named otherwise still reaches the container but is left out of the build. A changed variable is picked up by the next build: a push to the tracked branch, or Redeploy. Variables prefixed `RAILPACK_` also configure an auto-detected build; see the [Railpack reference](https://railpack.com/config/environment-variables).

**Configuration file.** An app created from a repository's [configuration file](/docs/guides/app-templates) remembers which file and service it came from, and what the file applied. That is what lets Check configuration file tell the repository moving on apart from a setting changed in the control panel since; whether the file is then ignored, watched or applied on every push is the app's configuration file mode.

Every call that changes an app is refused to members with the viewer role, and to a project blocked over an unpaid invoice (`403 ACCOUNT_BLOCKED`). Reading an app's network settings and its recent activity currently sits behind the same gate, and needs `apps:write` as well as `apps:read`.

Four calls work with an API key but are not described operation by operation yet, because they answer with the app's full internal record, which is not a stable contract: listing apps (`GET /v1/projects/{projectId}/apps`, `apps:read`), reading one (`GET /v1/projects/{projectId}/apps/{appId}`, `apps:read`), updating its settings and environment variables (`PATCH /v1/projects/{projectId}/apps/{appId}`, `apps:write`) and changing its domain (`PATCH /v1/projects/{projectId}/apps/{appId}/domain`, `apps:write`). Rely only on the fields you also see in the control panel — `id`, `name`, `status`, `url`, the source and build settings, `envVars` — and expect the rest to change. Secret environment variable values come back masked, and a registry credential comes back without its password.

Following an app's logs live and opening a console are available in the control panel; the latest log lines are available here.
- [Servers](https://cosmoner.com/docs/api/servers.md): Dedicated machines in a project. The keys that can log into a server are fixed when it is created — they are written to the machine at first boot — so decide them before provisioning, not after.
- [SSH keys](https://cosmoner.com/docs/api/ssh-keys.md): Public keys that authorise access to the servers in a project. A key is written to a server by cloud-init at first boot, so it must be registered *before* the server that should trust it is created.
- [Domains](https://cosmoner.com/docs/api/domains.md): The domains in a project. A domain is registered through Cosmoner, moved in from another registrar, or external — a domain whose DNS you keep hosting elsewhere. An external domain starts `PENDING`, and the project's apps can use it only once you have proven you control it: publish the TXT record Verify ownership of an external domain returns, then call it again until the record is found. Turning email on for the domain and verifying its records proves the same thing. Keep the record published for as long as the domain is used here: it is checked again regularly, and an `ACTIVE` domain whose record stays missing for about a week goes back to `PENDING`, which stops its apps serving it. While the record is missing the domain stays `ACTIVE`, its owners and admins are notified, and calling Verify ownership again clears the warning once the record is back. If another project proves control of the domain while this project's record is missing, this project's domain goes back to `PENDING` at once.

Search shows which names can be registered and what each costs; see [Domain pricing](/docs/pricing/domains). Registering a domain and moving one in are done in the control panel.

Three calls work with an API key but are not described operation by operation yet, because they answer with the domain's full internal record, which is not a stable contract: listing the project's domains (`GET /v1/projects/{projectId}/domains`, `domains:read`), reading one by id or name (`GET /v1/projects/{projectId}/domains/{domain}`, `domains:read`) and adding an external domain (`POST /v1/projects/{projectId}/domains` with `{ "name": "example.com", "type": "EXTERNAL" }`, `domains:write` — `EXTERNAL` is the only type it takes). Rely only on `id`, `name`, `type`, `status`, `createdAt`, `dnsRecords` and, for an external domain, `verificationRecord` — the TXT record to publish — and `verificationLapsesAt`, which is set while an `ACTIVE` domain's record is missing and gives the earliest time it goes back to `PENDING`, and expect the rest to change. Adding a domain is refused to members with the viewer role, and to a project blocked over an unpaid invoice.
- [Email](https://cosmoner.com/docs/api/email.md): Sending email from your own domains, over SMTP or through Send an email. Turn email on for a domain in the project, publish the DKIM, SPF and DMARC records it returns, and verify them; then create an SMTP credential for each sender address. [SMTP Setup](/docs/guides/smtp-setup) walks through it and has the server settings.

Send an email takes its content inline or from a stored template; see [Email templates](/docs/api/email-templates) and the [Email Templates guide](/docs/guides/email-templates).

Every email sent is billed on the project's subscription, each recipient counting as one email, and there is no free allowance. Projects start on pay as you go, with no monthly fee; a plan includes a number of emails each month for a flat price and bills the emails beyond it at a lower rate. Change the email plan moves between them. See [Email pricing](/docs/pricing/email).

Sending is held under three ceilings, all shown by Get send limits. The **monthly cap** is your budget — the most the project will send, and pay for, in one quota month — and you set it. The **hourly** and **daily limits** are burst guards that stop a runaway loop from spending the month in an afternoon; they are raised on request, after review. Reaching any of them pauses sending. An hourly or daily pause lifts on its own as the window moves on; a monthly one lifts when the next quota month begins, or as soon as the cap is raised above what has already been sent. The project's biller is emailed whenever sending is paused.

Adding a domain whose DNS is hosted elsewhere for email, and turning email off for a domain, are done in the control panel for now.
- [Email templates](https://cosmoner.com/docs/api/email-templates.md): Stored, versioned emails that a send names instead of carrying its own subject and HTML. A template is written in the control panel, either as a React Email component in TSX or in the visual editor, and declares the variables a send supplies. Publishing freezes the draft into a numbered version; Send an email uses the published version unless it names another. [Email Templates](/docs/guides/email-templates) explains writing, previewing and publishing them.

A template is addressed by its id or its alias wherever `{templateId}` appears. Aliases are lower-case letters, digits, `-` and `_`, unique in the project, and can be changed — the id never does.

The calls here read templates, versions and folders, manage a template's name, alias, folder and sample data, roll back to an earlier version, and delete. Editing a template's content, publishing a version and sending a test are done in the control panel's editor, which builds what a publish stores.

Templates themselves are free; the emails sent from them are billed like any other. A project can hold up to 200 templates and 100 folders, and each template keeps its 50 most recent versions.
- [Storage](https://cosmoner.com/docs/api/storage.md): Object storage buckets and container registries.

**Buckets** are S3-compatible: any S3 client or SDK reads and writes them, with an access key issued under [IAM](/docs/api/iam). Each bucket runs on a prepaid tier that includes a storage, egress and request allowance, and its usage is watched against it — a bucket that goes more than 10% over any part of its allowance is suspended until it moves to a larger tier. See [Object Storage](/docs/guides/object-storage) and [Object storage pricing](/docs/pricing/object-storage).

**Container registries** hold the images apps deploy from. Push and pull with `docker`, logging in with a Cosmoner API key that carries `registry:read` to pull and `registry:write` to push; see [Container Registry](/docs/guides/container-registry) and [Container registry pricing](/docs/pricing/container-registry). Repository names are unique across the project, not just within a registry. A repository is private by default. A public one can be pulled by anyone without credentials, and must carry a monthly cap on that anonymous egress (`publicEgressCapGb`, 1–10,000 GB), because it is billed to the project; when the cap is reached the repository becomes private again and `publicEgressCapHitAt` records when. Making it public again, or raising the cap, starts a fresh allowance.

Several calls work with an API key but are not described operation by operation yet, because they answer with the resource's full internal record, which is not a stable contract: listing buckets (`GET /v1/projects/{projectId}/storage/object-storage`, `object-storage:read`), listing registries with their repositories (`GET /v1/projects/{projectId}/storage/container-registry`, `registry:read`), reading one (`GET …/container-registry/{id}`), listing and reading its repositories (`GET …/container-registry/{id}/repositories` and `…/repositories/{repoId}`), creating a repository (`POST …/container-registry/{id}/repositories` with `name` and optionally `visibility` and `publicEgressCapGb`, `registry:write`) and updating a repository's retention and visibility (`PATCH …/repositories/{repoId}`, `registry:write`). Rely only on `id`, `name`, `region`, `status`, `tier`, `publicAccess`, `publicPaths`, `versioning`, `corsRules`, `cdnEnabled`, `cdnDomain` and `createdAt` for a bucket; `id`, `name`, `region`, `status` and `createdAt` for a registry; and `id`, `name`, `fullPath`, `visibility`, `publicEgressCapGb`, `publicEgressUsedGb`, `publicEgressCapHitAt`, the `gc…` retention settings and `createdAt` for a repository — and expect the rest to change. Creating and updating a repository are refused to members with the viewer role, and to a project blocked over an unpaid invoice.

Creating a bucket or a registry, previewing what one costs, changing a registry's settings, turning a bucket's CDN on or off, browsing a bucket's files and seeing which access keys reach a bucket or repository are done in the control panel for now.
- [IAM](https://cosmoner.com/docs/api/iam.md): AWS access keys for tooling that cannot use a Cosmoner API key — `aws ecr get-login-password`, Kubernetes image pull secrets, S3 clients. These endpoints issue scoped credentials for those cases and list every credential a project has out there. Cosmoner API keys are a different thing and are not listed here; see [API Keys](/docs/guides/api-keys).

One credential can reach the project's container registries, its object storage buckets, or both. A grant either names individual repositories and buckets or covers every one in the project, **including those created later**. Each credential's `origin` says which shape it has: `project` is the current one, and `registry` and `bucket` are older single-service shapes that keep working with the scope they were created with.

The secret access key is returned once, when the credential is issued, and never stored. Pulls made with these credentials go directly to AWS and are not metered as egress; storage is billed as usual.

An API key issuing or re-scoping a credential needs the scopes for what the credential grants as well as `iam:write`, so a key cannot hand out access to buckets or repositories it could not reach itself.
- [Billing](https://cosmoner.com/docs/api/billing.md): How a project pays for what it runs. Each project has one payment method, a card, and every resource in it is billed to that card on the project's subscription: a prorated charge when the resource is created, then monthly on the 25th. See [Billing & Payments](/docs/guides/billing-and-payments) for the payment lifecycle and [Pricing](/docs/pricing) for what each product costs.

**The biller.** One member holds billing responsibility for the project. Only the biller sees and manages the card, and only the biller can have the project's credit refunded; see [Transfer billing responsibility](/docs/api/members#transfer-billing-responsibility) to hand it to someone else. Any member with write access can create resources, and the charge always goes to the project's card, never to the member's own.

**When a create is refused for payment.** A call that creates a billable resource charges the project's card before it answers, and is refused with `402` when it cannot, with nothing created. The `code` says why: `ORG_PAYMENT_METHOD_REQUIRED` — the project has no usable card and the caller is the biller, who adds one and retries; `BILLER_PAYMENT_METHOD_REQUIRED` — the project has no usable card and the caller is not the biller, and `error.details` names the biller (`billerUserId`, `billerName`, `billerEmail`) so they can be asked, which Notify the biller does; `ORG_BILLING_ADDRESS_REQUIRED` — the card's billing address is not complete enough to work out tax, so the card has to be added again with a full address; `PAYMENT_REQUIRED` — the card was declined, or the subscription is past due. A card that has expired, or is not the project's default, does not count as usable.

**Credit.** Removing a resource part-way through a billing period credits the unused part to the project's credit balance, which is applied to its next invoices automatically. The biller can instead have the balance refunded to the card or cards that paid it. Payment-processing fees on the original charges cannot be recovered, so the amount refunded is less than the credit it uses up, and credit that cannot be returned to a card stays on the balance.

The subscription breakdown, invoices, billing history, credit refunds and the card itself are managed under **Settings → Billing** in the control panel. Invoices and receipts are also emailed to the project's billing email, which Set the billing email changes.
- [Integrations](https://cosmoner.com/docs/api/integrations.md): Connections to the services a project builds from and pulls images from: GitHub, GitLab and Bitbucket for source code, and Docker Hub and the GitHub container registry for container images. A connection belongs to one project — connecting an account in one project never makes it available in another — and the credentials behind it are stored encrypted and never returned.

Connecting is done in the control panel, through each service's own authorization page, or for Docker Hub by entering an access token (a read-only one is enough to deploy). The calls here report on a connection, read what it can see — repositories, branches, configuration files, images and tags — and remove it.

A GitHub connection is made of accounts. The project links the Cosmoner GitHub App's installation on each GitHub account or organization that granted it access, and can link several; each grants read access to the repositories chosen on GitHub, and those with the Packages read permission to their container images too. Uninstalling the app on GitHub detaches that account from every project that linked it.

While a git service is connected, a push to the branch an app deploys from redeploys the app, as long as its auto-deploy is on. Nothing needs to be called for this.

Listing GitHub repositories and browsing a repository's directories are available in the control panel.
- [Webhooks](https://cosmoner.com/docs/api/webhooks.md): Subscriptions to platform events. Each endpoint has a signing secret, returned once when it is created or rotated, that signs every delivery so you can verify it came from us. Repeated failures pause an endpoint automatically; resuming it re-queues what was held.
- [Support tickets](https://cosmoner.com/docs/api/support-tickets.md): Conversations with the support team. A ticket belongs to one project, and an API key reaches only the tickets of the project it was issued for. Each ticket carries its whole conversation as a timeline of events, oldest first; when support replies, the ticket moves to `PENDING` and the member who opened it is emailed. Your own reply moves it back to `OPEN`.
- [Web hosting](https://cosmoner.com/docs/api/web-hosting.md): PHP websites on Apache. Each site runs in its own container, with its own disk, and answers on its own address under `cosmoner.com` as well as on the domains attached to it. The [Web Hosting guide](/docs/guides/web-hosting) explains the folder layout, SFTP and how PHP runs.

A site's tier — `STARTER`, `GROWTH` or `SCALE` — sets its PHP workers, memory, CPU, disk, and how many domains and databases it can have. The limits are recorded on the site when it is created, so List sites shows what each one was given, and retuning a tier later does not change an existing site. Extra disk is bought in blocks on top of the tier when the site is created. Creating a site charges the project's payment method straight away; there is no checkout step.

**Files.** A site's files are reached over SFTP, or over SSH where the site gives a shell, at the host, port and username Get connection details returns. The file calls here act on the same folder an SFTP login lands in and run as the site's own user, so what they create is owned by that login. Paths are relative to the home folder, with no leading slash, and an empty path is the home folder itself. They list folders, write text files of up to 1 MB, and create, move and delete files and folders; reading a file's contents, uploading and downloading are done in the control panel or over SFTP.

**Domains.** Each domain attached to a site, other than its own address, is a domain you own or a subdomain of one, and it serves a folder, redirects, or is parked. The site's own address takes no subdomains. Attaching a domain is done in the control panel for now; the calls here list a site's domains, change what one does and detach it.

**Databases.** A site can have MySQL databases, reached from the site only — not from outside, and not from other resources in the project. How many it can have, and how many connections each gets, depend on its tier.

The SFTP password and each database's password are shown in the control panel, and changing a site's tier is done there too.

Every call that changes a site, its domains, files or databases is refused to members with the viewer role, and to a project blocked over an unpaid invoice (`403 ACCOUNT_BLOCKED`).
- [Shared databases](https://cosmoner.com/docs/api/shared-databases.md): A shared database is a PostgreSQL database of its own, with its own user, on a server it shares with other databases. Only its user can reach it: connecting to the database, and using its `public` schema, are revoked from every other user on the server.

**No new shared databases can be created.** Existing ones keep working and stay manageable. For a new database, create a dedicated PostgreSQL database instead; see the [Databases guide](/docs/guides/databases).

**Connecting.** Use any PostgreSQL client or ORM. TLS is required: `postgresql://<dbUser>:<password>@<host>:<port>/<dbName>?sslmode=require`. A database with a connection pooler — `poolName` and `poolPort` are set — can also be reached through it, which lets more clients share the database's few connections: `postgresql://<dbUser>:<password>@<host>:<poolPort>/<poolName>?sslmode=require`. `poolMode` says when the pooler takes a server connection back: `TRANSACTION` at the end of each transaction, so session state such as `SET` and advisory locks does not carry over from one transaction to the next; `SESSION` when the client disconnects; `STATEMENT` after every statement, so a transaction spanning several statements is refused.

**Tiers.** A database's tier — `MICRO`, `STARTER`, `GROWTH` or `SCALE` — sets `maxConnections`, the most connections its user can hold open on the server at once. The pooler's own connections to the server count towards it, so going through the pooler is how to serve more clients than that.

**Password.** The password is returned once — when the database was created, and each time its password is rotated — and only a hash of it is kept, so it cannot be read back. Rotating it is done in the control panel for now. New connections need the new password at once; connections already open are not closed.

Listing the project's shared databases (`GET /v1/projects/{projectId}/databases/shared`) and reading one (`GET /v1/projects/{projectId}/databases/shared/{tenantId}`) work with an API key and `databases:read`, but are not described operation by operation yet: alongside the connection details, their responses describe the server the database is placed on, which is not a stable contract. The `id` they return is the `tenantId` below. A deleted database is no longer listed.
- [Redis](https://cosmoner.com/docs/api/redis.md): Managed Redis databases. A database's password is returned only by the single-database read, never by the list, so enumerating databases does not hand out credentials for all of them.
- [Secrets](https://cosmoner.com/docs/api/secrets.md): Encrypted configuration. A secret's value is returned exactly once — by the call that sets it — and never again; reads describe the secret without handing the plaintext back. For values that do not need protecting, use variables instead.
- [Variables](https://cosmoner.com/docs/api/variables.md): Non-sensitive configuration, stored and returned in plaintext and scoped to a deployment environment. For values that must not be readable, use secrets instead.
- [Infrastructure](https://cosmoner.com/docs/api/infrastructure.md): The catalogue of what can be created: the sizes on sale and their monthly list prices, in US dollars before tax. The catalogue is the same for every customer and reads nothing from a project, so any valid API key can read it, whatever its scopes. Answers are cached for a few minutes, so a change to what is on sale can take that long to show.

A size's `slug` is what a create call takes to choose it. For what creating a resource would actually be charged — tax and any project credit included — use the preview call next to its create call.

App sizes are listed here. Redis plans and regions are listed under [Redis](/docs/api/redis). The sizes, regions and templates a server can be created with, and the sizes, versions and regions of an always-on database, are shown in the control panel's create forms and are not described here yet.

## Machine-readable references

- [OpenAPI document](https://api.cosmoner.com/v1/openapi.json): The API as OpenAPI 3.0, generated from the schemas requests are validated against. Endpoints still documented only in prose above are not in it yet.
- [Platform MCP server](https://api.cosmoner.com/v1/mcp): A remote MCP server (Streamable HTTP) for operating a project: apps, logs, deployments, servers, variables. Authenticates with a project API key sent as `Authorization: Bearer`; see the Connect AI Agents guide.
- [Docs MCP server](https://cosmoner.com/docs/mcp): A remote MCP server (Streamable HTTP, no authentication) with tools to search these docs, read any page as Markdown, and list every page.
- [Deployment file JSON Schema](https://cosmoner.com/schemas/app.schema.json): Schema for `.cosmoner/deployment.yaml`, the file that describes how an app is built and deployed.

## Optional

- [Changelog](https://cosmoner.com/en/changelog): What has shipped, newest first.
- [Newsletter](https://cosmoner.com/en/newsletter): Guides, stories and news, broader than the changelog.
- [SDKs](https://cosmoner.com/en/products/sdk): The official JavaScript/TypeScript, Python and PHP clients.