OrbitsDocs
esc
    Open Orbits
    API reference · Using the APIExamples

    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.

    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; from a terminal, the CLI does each in one command.

    Terminal
    $ 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:

    Terminal
    $ 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:

    Terminal
    $ 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:

    Terminal
    $ 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:

    Terminal
    $ 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.

    Set a variable and redeploy

    Terminal
    $ 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:

    Terminal
    $ 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

    Terminal
    $ 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:

    Terminal
    $ 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.

    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:

    Terminal
    $ 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.

    Was this page helpful?

    Updated