> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jojapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployments

> Every save of your API's Worker is an immutable deployment with its own URL: test it, share it as a pinned version, promote it to production, roll back in seconds.

On the edge gateway every save of an API's Worker creates a **deployment**: an immutable snapshot of the files it runs, the template, the variables and the bindings. Your API's hosts (`{api}.jojapi.net` and your custom hosts) serve the **production** deployment. Every other active deployment has its own URL, so you can test a change before your consumers see it, share an exact version, and go back to a previous one without rebuilding anything.

<Info>
  Deployments exist for APIs served by the edge gateway (the **Worker** tab). Open **Worker → Deployments** in the Studio, or use the [CLI](#cli-and-management-api).
</Info>

## URLs

| URL                                           | Serves                                   |
| --------------------------------------------- | ---------------------------------------- |
| `https://{api}.jojapi.net` (and custom hosts) | the production deployment                |
| `https://{api}--{id}.jojapi.dev`              | one deployment, pinned: it never changes |
| `https://{api}--preview.jojapi.dev`           | the latest deployment, promoted or not   |

Every URL goes through the same gateway: API keys, subscriptions, plans, quotas, rate limits, billing and request logs work exactly as on production. Calls to a deployment URL are billed like any other call. Each answer carries `x-jojapi-deployment: {id}`, so you always know which version responded.

## What a save does

| Save                                     | Creates                                                                   | Goes to production                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Template                                 | a deployment of the new template                                          | yes — or **Save as preview**                                                          |
| Code (browser editor or `jojapi deploy`) | a deployment of your files; an API in template mode switches to code mode | no, it is a preview — **Deploy to production**, **Promote** or `jojapi deploy --prod` |
| Variable, storage binding                | production's code with the new values                                     | yes — or **Deploy as a preview** for a variable                                       |
| Back to template / Edit code             | a deployment in the new mode                                              | yes                                                                                   |

A variable or binding change never carries unpromoted code into production: it is built from the code production runs. Console logging is a Worker setting, not part of a deployment; switching it applies to production and every active deployment at once.

## Promote and roll back

**Promote** serves a deployment on your production hosts within seconds. You can add a **release note**: promotions and their notes appear as **Releases** on your API's public page, with a "last updated" date. Consumers never see unpromoted deployments.

**Roll back** returns production to the deployment it served before. A deployment carries its variables and bindings, so rolling back restores their values too — secrets included. If you rotated a leaked key, deploy again after the rollback.

Stateful objects keep one shared state: every deployment of an API talks to the same objects as production. A class that production does not have yet starts with its own empty state in a preview and moves to the shared state when that deployment is promoted.

## Access

Your production hosts always serve every subscriber. The access setting only concerns a deployment's own URL, and it appears on every deployment except the one in production:

* **My keys only** (default): only API keys of your own account can call the URL; anyone else gets `403 Deployment Is Private`.
* **Public URL**: any subscriber of your API can call it, billed as usual. Share it to let a consumer pin an exact version while production moves on.

The `--preview` URL is always for your keys only.

## Active and archived deployments

An **active** deployment is deployed and callable. Three active deployments per API are included in [compute usage](/studio/custom-code#compute-usage); beyond that, each costs the list price of **\$0.02 per deployment per month**, prorated by day. To keep routine saves free, the oldest active deployment is archived automatically once more than three are active — except production, the previous production, the latest deployment, public deployments and those you **Keep active**.

An **archived** deployment keeps its snapshot but no longer runs: its URL answers `410 Deployment Archived` with your production URL. **Activate** brings it back in seconds (and keeps it active); promoting an archived deployment activates it as well. The last 100 deployments of an API are retained. An API can keep up to 50 deployments active; write to support if you need more.

## CLI and Management API

```bash theme={null}
jojapi deploy                  # preview deployment, prints its URL
jojapi deploy --prod           # deploy and promote (without changes: promote the latest)
jojapi deploy --message "Faster search"
jojapi deployments             # newest first, with production / previous / latest
jojapi promote k3j9x2ab --note "Faster search results"
jojapi rollback
```

To deploy from a GitHub repository — a preview for every pull request, production on every merge — see [Deploy from GitHub](/studio/github-actions).

The same actions are [Management API](/studio/management-api#worker-code-edge-gateway) routes: `provider-api-edge-deployments`, `promote-api-edge-deployment`, `rollback-api-edge` and `update-api-edge-deployment` (access, Keep active, archive, activate), with the `code:read` and `code:write` scopes.