# Examples

Whole jobs with the API, step by step in cURL: deploy and wait, roll back, set a variable and redeploy, add a domain, and deploy a folder.

Source: https://docs.orbits.africa/api/examples

Each example uses a `full` token in `ORBITS_TOKEN`, a team `my-team` and a project `my-app`. Replace them with your own. For the same jobs in code, see the [SDKs](https://docs.orbits.africa/sdks); from a terminal, the [CLI](https://docs.orbits.africa/cli) does each in one command.

```console
$ export ORBITS_TOKEN=orb_live_…
$ export API=https://api.theorbits.app/v1
```

## Deploy a branch and wait for it

Pushes deploy by themselves. To build a branch's newest commit now:

```console
$ curl -X POST "$API/teams/my-team/projects/my-app/deployments" \
    -H "Authorization: Bearer $ORBITS_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{"branch": "main"}'
```

The answer is `202` with the deployment, `state: "queued"`. The production branch deploys to production; any other branch to a preview. Poll it until its `state` is `ready`, `failed` or `canceled`:

```console
$ curl "$API/teams/my-team/projects/my-app/deployments/dpl_…" \
    -H "Authorization: Bearer $ORBITS_TOKEN"
```

Or follow the build log as it happens, as Server-Sent Events:

```console
$ curl -N "$API/teams/my-team/projects/my-app/deployments/dpl_…/logs/stream" \
    -H "Authorization: Bearer $ORBITS_TOKEN"
```

When it is `ready`, its `url` is where it is served. If it `failed`, its `failure` says why, and `GET …/deployments/dpl_…/logs` has the whole log.

## Roll production back

List production's deployments, newest first, and pick the one to go back to:

```console
$ curl "$API/teams/my-team/projects/my-app/deployments?environment=production" \
    -H "Authorization: Bearer $ORBITS_TOKEN"
$ curl -X POST "$API/teams/my-team/projects/my-app/deployments/dpl_…/rollback" \
    -H "Authorization: Bearer $ORBITS_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)"
```

Production serves it at once, with no rebuild, and auto-deploy is paused so the next push doesn't replace it. The answer's `undo` is what to send to `POST …/projects/my-app/production` to go back. See [Deployments](https://docs.orbits.africa/api/deployments).

## Set a variable and redeploy

```console
$ curl -X POST "$API/teams/my-team/projects/my-app/env" \
    -H "Authorization: Bearer $ORBITS_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{"variables": [{"key": "STRIPE_SECRET_KEY", "value": "sk_live_…", "environments": ["production"], "sensitive": true}]}'
```

A variable reaches deployments made after it is set. Redeploy production's current deployment to use it:

```console
$ curl -X POST "$API/teams/my-team/projects/my-app/deployments/dpl_…/redeploy" \
    -H "Authorization: Bearer $ORBITS_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)"
```

## Add a custom domain

```console
$ curl -X POST "$API/teams/my-team/domains" \
    -H "Authorization: Bearer $ORBITS_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{"domain": "shop.example.com", "project": "my-app", "dns": "external"}'
```

The answer's `required_record` is the record to add at your DNS provider. Orbits looks for it every minute; to look now:

```console
$ curl -X POST "$API/teams/my-team/domains/shop.example.com/checks" \
    -H "Authorization: Bearer $ORBITS_TOKEN"
```

When its `state` is `valid`, Orbits issues the certificate and serves the project there. See [Custom domains](https://docs.orbits.africa/domains/custom-domains).

## Deploy a folder

A project created with `source_kind: "upload"` deploys from a zip instead of a repository. Start an upload, send the zip to the URL it returns, then complete it:

```console
$ curl -X POST "$API/teams/my-team/projects/my-site/uploads" \
    -H "Authorization: Bearer $ORBITS_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{"size": 482133}'
```

Send the file with the method, URL and headers the answer gives, then `POST …/uploads/{upload}/complete` to deploy it. The zip may be up to 100 MB. The CLI's deploy and the SDKs' upload helpers zip a folder and do all three steps. See [Upload a folder](https://docs.orbits.africa/getting-started/upload-a-folder).
