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

# Introduction

The Onset API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)ful API accessed by an HTTP client such as `curl` or the HTTP library, which is part of most modern programming languages. You can use this API to build custom integrations or automate even more of your organization's workflow.

## Authentication

The Onset API uses API keys to authenticate requests. You can view and manage your API keys in the Onset Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Provide your API key as the basic auth username value. You do not need to provide a password.

```shell theme={null}
curl https://api.onset.io/v1/workspace \
-u {API_KEY}:
```

If you need to authenticate via bearer auth use `-H "Authorization: Bearer API_KEY"` instead of `-u API_KEY`.

```sh theme={null}
curl https://api.onset.io/v1/workspace \
-H 'Authorization: Bearer {API_KEY}'
```

## Creating and publishing releases

Releases are created and edited as **drafts**, then published in a separate
step. `POST /v1/releases` and `PATCH /v1/releases/{id}` never change a release's
status — publishing goes through a dedicated endpoint:

```sh theme={null}
# 1. Create a draft
curl https://api.onset.io/v1/releases \
-H 'Authorization: Bearer {API_KEY}' \
-H 'Content-Type: application/json' \
-d '{ "title": "Version 2.1", "slug": "version-2-1", "body": "<p>What is new</p>" }'

# 2. Publish it
curl https://api.onset.io/v1/releases/{id}/publish \
-H 'Authorization: Bearer {API_KEY}' \
-H 'Content-Type: application/json' \
-d '{ "status": "RELEASED" }'
```

To publish at a future date, send `{"status": "SCHEDULED", "scheduled_at":
"2026-08-01T09:00:00.000Z"}` instead. The same endpoint publishes a scheduled
release early (`RELEASED`) or moves it to a different date.

Publishing is what emits the `release.published` and `release.scheduled`
[webhooks](https://onset.io/docs/developers/webhooks.md), so integrations get an accurate signal of when
a release actually went live.

> [!NOTE]
>
> Publishing over the API does not send subscriber emails or Slack and Discord
> announcements. Publish from the Onset dashboard to choose notification
> channels.

## Versioning

The API is versioned with a single number, which is currently 1. This number symbolizes the major version number, as described by [SemVer](https://semver.org/). Because of this, backward-incompatible changes require this version number to change.

The minor version isn't explicit, which allows for a stable API endpoint. New features can be added to the API in the same version number.

API requests must be made over HTTPS and include the API version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.