# List contributors
Source: https://docs.onset.io/api-reference/contributors/list-contributors

https://api.onset.io/v1/openapi.yml get /contributors
Retrieve a paginated list of contributors (workspace members) that can be assigned to releases



# Create a new incoming webhook
Source: https://docs.onset.io/api-reference/incoming-webhooks/create-a-new-incoming-webhook

https://api.onset.io/v1/openapi.yml post /incoming-webhooks
Create a new incoming webhook in the workspace



# Delete incoming webhook
Source: https://docs.onset.io/api-reference/incoming-webhooks/delete-incoming-webhook

https://api.onset.io/v1/openapi.yml delete /incoming-webhooks/{id}
Delete an incoming webhook by its ID



# Get incoming webhook by ID
Source: https://docs.onset.io/api-reference/incoming-webhooks/get-incoming-webhook-by-id

https://api.onset.io/v1/openapi.yml get /incoming-webhooks/{id}
Retrieve a specific incoming webhook by its ID



# List incoming webhooks
Source: https://docs.onset.io/api-reference/incoming-webhooks/list-incoming-webhooks

https://api.onset.io/v1/openapi.yml get /incoming-webhooks
Retrieve a list of incoming webhooks



# Update incoming webhook
Source: https://docs.onset.io/api-reference/incoming-webhooks/update-incoming-webhook

https://api.onset.io/v1/openapi.yml patch /incoming-webhooks/{id}
Update an existing incoming webhook



# List labels
Source: https://docs.onset.io/api-reference/labels/list-labels

https://api.onset.io/v1/openapi.yml get /labels
Retrieve a paginated list of labels in the workspace



# Delete milestone
Source: https://docs.onset.io/api-reference/milestones/delete-milestone

https://api.onset.io/v1/openapi.yml delete /milestones/{id}
Delete a milestone by its ID



# Get milestone by ID
Source: https://docs.onset.io/api-reference/milestones/get-milestone-by-id

https://api.onset.io/v1/openapi.yml get /milestones/{id}
Retrieve a specific milestone by its ID



# List milestones
Source: https://docs.onset.io/api-reference/milestones/list-milestones

https://api.onset.io/v1/openapi.yml get /milestones
Retrieve a paginated list of milestones with optional filtering by status, visibility, project, and other criteria



# Update milestone
Source: https://docs.onset.io/api-reference/milestones/update-milestone

https://api.onset.io/v1/openapi.yml patch /milestones/{id}
Update an existing milestone



# List projects
Source: https://docs.onset.io/api-reference/projects/list-projects

https://api.onset.io/v1/openapi.yml get /projects
Retrieve a paginated list of projects in the workspace



# Create a new release
Source: https://docs.onset.io/api-reference/releases/create-a-new-release

https://api.onset.io/v1/openapi.yml post /releases
Create a new release in the workspace. Releases are always created as drafts — use POST /releases/{id}/publish to publish or schedule one.



# Delete release
Source: https://docs.onset.io/api-reference/releases/delete-release

https://api.onset.io/v1/openapi.yml delete /releases/{id}
Delete a release by its ID



# Get release by ID
Source: https://docs.onset.io/api-reference/releases/get-release-by-id

https://api.onset.io/v1/openapi.yml get /releases/{id}
Retrieve a specific release by its ID



# List releases
Source: https://docs.onset.io/api-reference/releases/list-releases

https://api.onset.io/v1/openapi.yml get /releases
Retrieve a list of releases with optional filtering



# Publish release
Source: https://docs.onset.io/api-reference/releases/publish-release

https://api.onset.io/v1/openapi.yml post /releases/{id}/publish
Publish a draft or scheduled release to the changelog, either immediately or at a future date. Use this to publish a scheduled release early, or to move a scheduled release to a different date. Returns 400 if the release is already published.



# Update release
Source: https://docs.onset.io/api-reference/releases/update-release

https://api.onset.io/v1/openapi.yml patch /releases/{id}
Update the content of an existing release. Cannot publish or unpublish — use POST /releases/{id}/publish for that.



# Create a new subscriber list
Source: https://docs.onset.io/api-reference/subscriber-lists/create-a-new-subscriber-list

https://api.onset.io/v1/openapi.yml post /subscriber-lists
Create a new subscriber list in the workspace



# Delete subscriber list
Source: https://docs.onset.io/api-reference/subscriber-lists/delete-subscriber-list

https://api.onset.io/v1/openapi.yml delete /subscriber-lists/{id}
Delete a subscriber list by its ID



# Get subscriber list by ID
Source: https://docs.onset.io/api-reference/subscriber-lists/get-subscriber-list-by-id

https://api.onset.io/v1/openapi.yml get /subscriber-lists/{id}
Retrieve a specific subscriber list by its ID



# List subscriber lists
Source: https://docs.onset.io/api-reference/subscriber-lists/list-subscriber-lists

https://api.onset.io/v1/openapi.yml get /subscriber-lists
Retrieve a list of subscriber lists



# Update subscriber list
Source: https://docs.onset.io/api-reference/subscriber-lists/update-subscriber-list

https://api.onset.io/v1/openapi.yml patch /subscriber-lists/{id}
Update an existing subscriber list



# Create a new subscriber
Source: https://docs.onset.io/api-reference/subscribers/create-a-new-subscriber

https://api.onset.io/v1/openapi.yml post /subscribers
Create a new subscriber in the workspace



# Delete subscriber
Source: https://docs.onset.io/api-reference/subscribers/delete-subscriber

https://api.onset.io/v1/openapi.yml delete /subscribers/{id}
Delete a subscriber by their ID



# Get subscriber by ID
Source: https://docs.onset.io/api-reference/subscribers/get-subscriber-by-id

https://api.onset.io/v1/openapi.yml get /subscribers/{id}
Retrieve a specific subscriber by their ID



# List subscribers
Source: https://docs.onset.io/api-reference/subscribers/list-subscribers

https://api.onset.io/v1/openapi.yml get /subscribers
Retrieve a list of subscribers, newest first, with optional filtering by subscriber list



# Update subscriber
Source: https://docs.onset.io/api-reference/subscribers/update-subscriber

https://api.onset.io/v1/openapi.yml patch /subscribers/{id}
Update an existing subscriber



# Create a new webhook
Source: https://docs.onset.io/api-reference/webhooks/create-a-new-webhook

https://api.onset.io/v1/openapi.yml post /webhooks
Create a new webhook in the workspace



# Delete webhook
Source: https://docs.onset.io/api-reference/webhooks/delete-webhook

https://api.onset.io/v1/openapi.yml delete /webhooks/{id}
Delete a webhook by its ID



# Get webhook by ID
Source: https://docs.onset.io/api-reference/webhooks/get-webhook-by-id

https://api.onset.io/v1/openapi.yml get /webhooks/{id}
Retrieve a specific webhook by its ID



# List webhooks
Source: https://docs.onset.io/api-reference/webhooks/list-webhooks

https://api.onset.io/v1/openapi.yml get /webhooks
Retrieve a list of webhooks



# Update webhook
Source: https://docs.onset.io/api-reference/webhooks/update-webhook

https://api.onset.io/v1/openapi.yml patch /webhooks/{id}
Update an existing webhook



# Get workspace information
Source: https://docs.onset.io/api-reference/workspace/get-workspace-information

https://api.onset.io/v1/openapi.yml get /workspace
Retrieve information about the current authenticated workspace, including its ID, name, slug, public page URL, and the configured release change types and roadmap status types



# Introduction
Source: https://docs.onset.io/developers/api-reference/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](/developers/webhooks), 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.
</Note>

## 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.


# Incoming Webhooks
Source: https://docs.onset.io/developers/incoming-webhook

Create releases and subscribers in Onset by sending a JSON POST from CI, a deploy script, or any external service.

An incoming webhook gives you a URL that turns an HTTP POST into an object in your
workspace. Point your CI pipeline, deploy script, or any tool that can send a
webhook at it, and Onset creates the release or subscriber for you.

Unlike the [REST API](/developers/api-reference/introduction), there's no API key
to manage. The secret is baked into the URL, so a service that can only send "a
POST to a URL" — GitHub Actions, Zapier, a shell script — can write to Onset.

There are two types:

| Type           | What a POST creates                          |
| -------------- | -------------------------------------------- |
| **Release**    | A new release, saved as a **draft**.         |
| **Subscriber** | A new subscriber, optionally added to lists. |

## Create a webhook

<Steps>
  <Step title="Open developer settings">
    In the dashboard, go to **Settings → Developers → Incoming Webhooks**.
  </Step>

  <Step title="Create the webhook">
    Click **Create webhook**, give it a name, and pick the event type. The type
    can't be changed afterwards — create a second webhook if you need both.
  </Step>

  <Step title="Copy the URL">
    Copy the endpoint from the **Webhook Endpoint** column and store it as a
    secret in whatever service will call it.
  </Step>
</Steps>

Your URL looks like this:

```
https://webhooks.onset.io/v1/{webhook_id}/{secret}
```

<Warning>
  The URL **is** the credential — anyone holding it can write to your workspace.
  Store it as a secret, never commit it, and don't put it in client-side code or
  logs. If it leaks, delete the webhook and create a new one.
</Warning>

## Sending a request

Send a `POST` with a JSON body and `Content-Type: application/json`. No
authentication headers are needed.

The body uses the same field names as the equivalent REST API endpoint, so
anything you can build with the API you can send here.

<Tabs>
  <Tab title="Release">
    ```bash theme={null}
    curl -X POST https://webhooks.onset.io/v1/{webhook_id}/{secret} \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Search and export improvements",
        "slug": "search-and-export-improvements",
        "version": "2.4.0",
        "body": "This release focuses on **search quality** and CSV exports.",
        "changes": [
          { "title": "Added", "content": "CSV export for subscriber lists" },
          { "title": "Fixed", "content": "Search now matches partial words" }
        ],
        "is_public": true
      }'
    ```

    | Field             | Type      | Notes                                                                                                               |
    | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
    | `title`           | string    | **Required.** 3–255 characters.                                                                                     |
    | `slug`            | string    | **Required.** Lowercase letters, numbers and hyphens, 3–255 characters. A suffix is appended if it's already taken. |
    | `body`            | string    | Markdown or HTML.                                                                                                   |
    | `version`         | string    | Free-form version label, e.g. `2.4.0`.                                                                              |
    | `changes`         | array     | Labelled one-liners rendered as badges above the body. See [Change types](#change-types).                           |
    | `is_public`       | boolean   | Defaults to `false`.                                                                                                |
    | `is_pinned`       | boolean   | Defaults to `false`.                                                                                                |
    | `is_pre_release`  | boolean   | Defaults to `false`.                                                                                                |
    | `project_id`      | string    | ID of a [project](/guides/projects).                                                                                |
    | `label_ids`       | string\[] | IDs of [labels](/guides/labels).                                                                                    |
    | `contributor_ids` | string\[] | IDs of [contributors](/guides/releases/contributors).                                                               |
    | `hero`            | object    | `{ "type": "image" \| "video", "url": "..." }`. Omit for none — `null` is not accepted.                             |
    | `attachments`     | array     | File or link attachments.                                                                                           |

    The response is the created release, in the same shape the REST API returns.
  </Tab>

  <Tab title="Subscriber">
    ```bash theme={null}
    curl -X POST https://webhooks.onset.io/v1/{webhook_id}/{secret} \
      -H "Content-Type: application/json" \
      -d '{
        "email": "ada@example.com",
        "list_ids": ["clx1a2b3c4d5e6f7g8h9i0j1"]
      }'
    ```

    | Field      | Type      | Notes                                                                |
    | ---------- | --------- | -------------------------------------------------------------------- |
    | `email`    | string    | **Required.** Must be a valid email address.                         |
    | `list_ids` | string\[] | IDs of [subscriber lists](/guides/subscribers/lists) to add them to. |

    The response is the created subscriber, including the lists they joined.
  </Tab>
</Tabs>

### Releases arrive as drafts

A release created through an incoming webhook is always saved with status
`DRAFT`, even if `is_public` is `true`. Nothing appears on your public page,
and no subscriber emails or Slack/Discord announcements go out, until someone
publishes it from the dashboard or via the API.

That's deliberate: it lets a deploy pipeline stage release notes automatically
while a human still decides when customers see them. See
[Publishing](/guides/releases/publishing).

### Change types

Each entry in `changes` must use the `title` of a change type configured in your
workspace (**Settings → Releases**), matched case-insensitively. The badge colour
comes from that configuration, so it isn't accepted in the payload.

An unrecognised title returns `400` with the list of titles your workspace
accepts, so you can correct the call without a second lookup. If you'd rather not
deal with change types, leave `changes` out and write everything into `body`.

## Responses

A successful call returns `200` with the created object.

| Status | Meaning                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------- |
| `400`  | The payload failed validation. The `errors` object maps each field to its problems.             |
| `402`  | Creating this subscriber would exceed your plan's subscriber limit.                             |
| `404`  | The webhook ID and secret don't match an existing webhook — usually a truncated or rotated URL. |
| `410`  | A milestone webhook. See below.                                                                 |

Errors have a consistent shape:

```json theme={null}
{
  "success": false,
  "message": "Invalid request",
  "errors": {
    "title": ["String must contain at least 3 character(s)"]
  }
}
```

## Example: publish from GitHub Actions

Draft a release in Onset whenever you tag a version:

```yaml theme={null}
name: Draft release notes

on:
  push:
    tags: ['v*']

jobs:
  onset:
    runs-on: ubuntu-latest
    steps:
      - name: Create Onset draft
        run: |
          VERSION="${GITHUB_REF_NAME#v}"
          curl -sSf -X POST "$ONSET_WEBHOOK_URL" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg v "$VERSION" '{
              title: ("Release " + $v),
              slug: ("release-" + ($v | gsub("\\."; "-"))),
              version: $v,
              is_public: true
            }')"
        env:
          ONSET_WEBHOOK_URL: ${{ secrets.ONSET_WEBHOOK_URL }}
```

The draft lands in your dashboard for editing before you publish it.

## Managing webhooks programmatically

Incoming webhooks can also be created, listed, updated and deleted through the
[REST API](/developers/api-reference/introduction) under `/incoming-webhooks`, or
with the Node SDK:

```javascript theme={null}
const webhook = await onset.incomingWebhooks.create({
  name: 'CI deploy notes',
  type: 'RELEASE',
});
```

## Milestone webhooks

Milestone incoming webhooks can no longer be created, and calls to existing ones
return `410 Gone`. The roadmap is being deprecated and will be disabled on
**October 5**. Existing milestone webhooks stay visible in settings so you can
find and delete them.

<Note>
  Incoming webhooks are for sending data **into** Onset. To receive notifications
  **from** Onset when something changes, see [Webhooks](/developers/webhooks).
</Note>


# MCP Server
Source: https://docs.onset.io/developers/mcp

Connect Onset to Claude, Cursor, VS Code, Codex and other AI clients to read and write your changelog in natural language.

The Onset MCP server lets AI assistants and coding agents work with your changelog
directly: listing releases, drafting and publishing new ones, and managing
subscribers, without leaving the chat or your editor.

It implements the [Model Context Protocol](https://modelcontextprotocol.io) over
Streamable HTTP, and authenticates with OAuth 2.1, so you sign in with your normal
Onset account. No API key required.

<Info>
  **Server URL:** `https://mcp.onset.io/mcp`
</Info>

## Connect your client

Any client that supports remote MCP servers over Streamable HTTP with OAuth can
connect. Point it at `https://mcp.onset.io/mcp` — there's no API key to paste.

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Open connector settings">
        In Claude, go to **Settings → Connectors** and click **Add custom connector**.
      </Step>

      <Step title="Add the Onset server">
        Paste `https://mcp.onset.io/mcp` and continue.
      </Step>

      <Step title="Sign in to Onset">
        You'll be redirected to Onset to sign in (or you'll continue with your existing
        session).
      </Step>

      <Step title="Choose a workspace">
        Pick the workspace you want to connect, then click **Authorize**. Access is
        limited to that one workspace.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    Add the server from your terminal:

    ```bash theme={null}
    claude mcp add --transport http onset https://mcp.onset.io/mcp
    ```

    Then run `/mcp` inside Claude Code, pick **onset**, and complete the sign-in
    and workspace selection in your browser. Tokens are stored and refreshed for
    you; use **Clear authentication** in the `/mcp` menu to revoke access.

    Add `--scope project` to share the server with your team through a checked-in
    `.mcp.json`, or `--scope user` to make it available in every project.
  </Tab>

  <Tab title="Cursor">
    Add Onset to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project only):

    ```json theme={null}
    {
      "mcpServers": {
        "onset": {
          "url": "https://mcp.onset.io/mcp"
        }
      }
    }
    ```

    Open **Settings → Features → Model Context Protocol**. Cursor discovers the
    Onset authorization server automatically, registers itself, and opens your
    browser so you can sign in and pick a workspace.
  </Tab>

  <Tab title="VS Code">
    Add Onset to `.vscode/mcp.json` in your project:

    ```json theme={null}
    {
      "servers": {
        "onset": {
          "type": "http",
          "url": "https://mcp.onset.io/mcp"
        }
      }
    }
    ```

    Or run **MCP: Add Server** from the Command Palette and choose **HTTP**, which
    writes the same entry. To make Onset available everywhere instead of one
    project, use **MCP: Open User Configuration**.

    On first use, VS Code opens a browser window for the OAuth flow. Start the
    server with **MCP: List Servers → onset → Start** if it hasn't connected yet.
  </Tab>

  <Tab title="Codex">
    Add the server from your terminal:

    ```bash theme={null}
    codex mcp add onset --url https://mcp.onset.io/mcp
    codex mcp login onset
    ```

    Or edit `~/.codex/config.toml` directly:

    ```toml theme={null}
    [mcp_servers.onset]
    url = "https://mcp.onset.io/mcp"
    ```

    `codex mcp login onset` opens your browser for the OAuth flow. Run `/mcp` in
    the Codex TUI to confirm the server is connected. The CLI and the IDE
    extension share this config, so you only set it up once.
  </Tab>
</Tabs>

Once connected, ask things like *"What did we ship last month?"* or
*"Draft a release for version 2.1 from these notes."*

## Workspace access

Each connection is scoped to a **single workspace**, chosen at the moment you
authorize. The workspace is bound into the access token, and every request is
re-checked against your current membership, so if you're removed from a
workspace, the connection stops working immediately.

To connect a different workspace, authorize again and select it. Each workspace
is granted separately.

Anyone who can access a workspace through the Onset API can use these tools for
that workspace.

## Available tools

### Releases

| Tool              | Description                                                      |
| ----------------- | ---------------------------------------------------------------- |
| `list_releases`   | List releases, optionally filtered by status, project, or labels |
| `get_release`     | Get a single release by id or number                             |
| `create_release`  | Create a new release as a **draft**                              |
| `update_release`  | Update the content of an existing release                        |
| `publish_release` | Publish a release now, schedule it, or reschedule it             |

### Projects, labels & contributors

| Tool                | Description                                      |
| ------------------- | ------------------------------------------------ |
| `list_projects`     | List projects in the workspace                   |
| `list_labels`       | List labels in the workspace                     |
| `list_contributors` | List workspace members available as contributors |

### Subscribers

| Tool                    | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `list_subscribers`      | List changelog subscribers                     |
| `list_subscriber_lists` | List subscriber lists                          |
| `create_subscriber`     | Add a subscriber, optionally to specific lists |

Read tools can run without confirmation. Tools that create or change data will
ask you to confirm before running.

<Warning>
  Creating, updating or publishing a release, and adding a subscriber, fire the
  same [webhooks](/developers/webhooks) as the REST API and dashboard. If your
  workspace has webhook endpoints configured, those requests are sent to your
  external URLs.
</Warning>

## Drafts and publishing

`create_release` always creates a **draft**. Nothing appears on your changelog
until it's published, so you can let an assistant write a release and review it
before anyone sees it.

Publishing is a separate, explicit step (`publish_release`), and most clients ask
you to confirm before running it. You can publish immediately (`RELEASED`) or
schedule it for a future date (`SCHEDULED`, available on plans that include
scheduled releases).

The same tool works on a release that's already scheduled, so you can ask to
publish it early or move it to a different date. Once a release is live, use
`update_release` to change its content.

This mirrors the [REST API](/developers/api-reference/introduction), where
releases are also created as drafts and published through a separate endpoint.

<Note>
  **Notifications are never sent over MCP.** Publishing through an AI assistant
  does not send subscriber emails or Slack and Discord messages. To notify people,
  publish from the Onset dashboard, where you choose the channels.
</Note>

## Prompts and resources

Alongside tools, the server exposes:

* **`draft_release_notes`** is a prompt that turns a list of changes into
  structured release notes. Provide your highlights plus an optional version and
  tone.
* **`onset://releases/{id}`** exposes your releases as readable Markdown, so clients
  that support resources can pull a release into context directly.

<Note>
  Support for prompts and resources varies by AI client. All clients support tools.
</Note>

## Plan limits

MCP requests count toward the same plan limits as the REST API. For example,
adding a subscriber fails once you reach your plan's subscriber limit.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client can't connect to the server">
    Confirm the URL is exactly `https://mcp.onset.io/mcp`. Web clients like Claude
    connect from their own servers, so the endpoint must be reachable from the
    public internet.
  </Accordion>

  <Accordion title="The sign-in window never opens">
    Some clients don't start the OAuth flow until the server is running. In VS Code
    use **MCP: List Servers → onset → Start**, in Claude Code run `/mcp`, and in
    Codex run `codex mcp login onset`.
  </Accordion>

  <Accordion title="Tools return a workspace error">
    Your connection may point at a workspace you're no longer a member of.
    Remove the server and add it again, selecting a current workspace.
  </Accordion>

  <Accordion title="Wrong workspace connected">
    Reconnect and pick the workspace you want on the authorization screen. Each
    connection covers exactly one workspace.
  </Accordion>

  <Accordion title="Tools don't show up after connecting">
    Restart the server or reload the client. In VS Code, run **MCP: Reset Cached
    Tools**. In Cursor, check **Output → MCP Logs** for connection errors.
  </Accordion>
</AccordionGroup>


# Webhooks
Source: https://docs.onset.io/developers/webhooks



Onset provides webhooks which allow you to receive HTTP push notifications whenever data is created, updated or removed. This allows you to build integrations that respond to changes in real time, such as triggering CI builds, updating external systems, or sending messages based on release activity.

## Payload

The webhook HTTP payload will include information both in its HTTP headers and its request body.

### Header

<ParamField type="string">
  HMAC signature of the webhook payload.
</ParamField>

<ParamField type="string">
  Event which triggered this webhook request.
</ParamField>

<ParamField type="string">
  Onset workspace Id.
</ParamField>

### Body

<ParamField type="string">
  Event which triggered this webhook request.
</ParamField>

<ParamField type="string">
  The actor who triggered the action. Could be a User, Visitor, or API.
</ParamField>

<ParamField type="string">
  Workspace ID
</ParamField>

<ParamField type="string">
  Webhook ID
</ParamField>

<ParamField type="string">
  UNIX timestamp when the webhook was sent.
</ParamField>

<ParamField type="string">
  Payload of the entity
</ParamField>

## Securing Webhooks

You should ensure that webhooks you received were sent by Onset. You can do this by verifying the webhook request signature and timestamp.

Onset sends a `Onset-Signature` HTTP header with every webhook request. This header contains a hex-encoded HMAC-SHA256 signature of the raw body contents, signed using the webhook's signing secret. You can find the signing secret on the webhook's detail page.

The parsed JSON body has a `webhookTimestamp` field with a UNIX timestamp, in milliseconds, indicating the time when the webhook was sent. We recommend that you verify it's within a minute of the time your system sees it to guard against replay attacks.

To verify the webhook, you need to compute the signature of the request body using the webhook's signing secret and compare it against the `Onset-Signature` header. It's strongly recommended to use raw request body rather than restringifying a parsed JSON body, otherwise the signature may differ. Once the signature has been validated, check to ensure that the webhook timestamp is reasonably current before processing the request:

```javascript theme={null}
// Express example:
const crypto = require('node:crypto');
const express = require('express');

const ONSET_WEBHOOK_SECRET = process.env.ONSET_WEBHOOK_SECRET;

function verifySignature(headerSignatureString, rawBody) {
  if (typeof headerSignatureString !== 'string') {
    return false;
  }
  const headerSignature = Buffer.from(headerSignatureString, 'hex');
  const computedSignature = crypto
    .createHmac('sha256', ONSET_WEBHOOK_SECRET)
    .update(rawBody)
    .digest();

  return crypto.timingSafeEqual(computedSignature, headerSignature);
}

const app = express();

app.post(
  '/webhook',
  express.json({
    verify: (req, _res, buf) => {
      // Capture the raw body for signature verification.
      req.rawBody = buf;
    },
  }),
  (req, res) => {
    if (!verifySignature(req.get('onset-signature'), req.rawBody)) {
      return res.sendStatus(401);
    }

    if (Math.abs(Date.now() - req.body.webhookTimestamp) > 60 * 1000) {
      // Reject any webhooks not within 60 seconds of the current time to prevent replay attacks.
      return res.sendStatus(401);
    }

    try {
      // ... Handle verified webhook ...
      return res.sendStatus(200);
    } catch (err) {
      // Indicate to Onset that there was a server error so the webhook is retried later.
      return res.sendStatus(500);
    }
  },
);

app.listen(8080, () => console.log('Serving on port 8080'));
```


# Configuration
Source: https://docs.onset.io/developers/widget/configuration



## Options

<ParamField type="string">
  Onset page domain without `https://`
</ParamField>

<ParamField type="boolean">
  Enable debug logs
</ParamField>

<ParamField type="'light' | 'dark' | 'system'">
  Widget theme
</ParamField>

<ParamField type="string">
  Widget title
</ParamField>

<ParamField type="boolean">
  Show latest unseen release popup on load
</ParamField>

<ParamField type="'left' | 'right'">
  Placement of popup window
</ParamField>

<ParamField type="'left' | 'right' | 'center'">
  Placement of widget window
</ParamField>

## Callbacks

<ParamField>
  Called when the widget is ready

  ```typescript theme={null}
  {
    //..options
    callbacks: {
      onReady() {
        
      }
    }
  }
  ```
</ParamField>

<ParamField>
  Called when the widget has loaded data

  ```typescript theme={null}
  {
    //..options
    callbacks: {
      onLoaded(releases: Releases[]) {
        
      }
    }
  }
  ```
</ParamField>

<ParamField>
  Called when the widget is opened

  ```typescript theme={null}
  {
    //..options
    callbacks: {
      onWidgetOpen() {
        
      }
    }
  }
  ```
</ParamField>

<ParamField>
  Called when the widget is closed

  ```typescript theme={null}
  {
    //..options
    callbacks: {
      onWidgetClose() {
        
      }
    }
  }
  ```
</ParamField>

<ParamField>
  Called when the widget popup is opened

  ```typescript theme={null}
  {
    //..options
    callbacks: {
      onPopupOpen() {
        
      }
    }
  }
  ```
</ParamField>

<ParamField>
  Called when the widget popup is closed

  ```typescript theme={null}
  {
    //..options
    callbacks: {
      onPopupOpen() {
        
      }
    }
  }
  ```
</ParamField>


# Install
Source: https://docs.onset.io/developers/widget/install

It only takes a few minutes to install Onset widget on your website.

## How to install

There are two ways to install the Onset widget:

1. Using the **NPM** package
2. Using the **embed** script

Both methods give you access to the same widget API.

### 1. Install via npm

<Steps>
  <Step title="Install the Onset widget package">
    <CodeGroup>
      ```shell npm theme={null}
      npm install @onsetio/widget
      ```

      ```shell yarn theme={null}
      yarn add @onset/widget
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a widget client instance">
    ```typescript theme={null}
    import { OnsetWidget } from "@onsetio/widget";

    const widget = new OnsetWidget({
      page: "PAGE_DOMAIN",
    });
    ```
  </Step>

  <Step title="Use the instance">
    You can now control the widget using the exposed methods.

    ```typescript theme={null}
    widget.openWidget();
    widget.closeWidget();
    ```

    Refer to the Methods section for the full API.
  </Step>
</Steps>

### 2. Install via embed script

<Steps>
  <Step title="Copy the embed snippet">
    Go to your Onset **Dashboard -> Settings -> Widget** and copy the provided `<script>` snippet. Paste it into your site's HTML, right before the closing `</body>` tag.
  </Step>

  <Step title="Use the global instance">
    The embed script exposes a global onsetWidget instance.

    ```typescript theme={null}
    widget.openWidget();
    widget.closeWidget();
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget does not appear">
    Check the following:

    * The script snippet or NPM import is included on every page where the widget should load.
    * `page` domain is correct.
  </Accordion>

  <Accordion title="onsetWidget is undefined">
    This means the embed script did not load.

    Verify that the `<script>` tag is placed before the closing `</body>` tag, not in the `<head>`.
  </Accordion>

  <Accordion title="Open or close methods do nothing">
    Usually caused by initialization issues.

    Make sure the widget is created before calling its methods.
  </Accordion>

  <Accordion title="Widget loads but shows the wrong workspace">
    Double-check the `page` domain in:

    * The NPM initialization config
    * The embed snippet you copied from the dashboard
  </Accordion>

  <Accordion title="How to find my page URL">
    Page domain is a URL to your public onset release notes page without the `https://`

    **Examples:**\
    [example.onset.io](http://example.onset.io) - Onset page domain\
    [releases.example.com](http://releases.example.com) - Custom domain page
  </Accordion>
</AccordionGroup>


# Methods
Source: https://docs.onset.io/developers/widget/methods



Loading the Onset JavaScript library provides a JavaScript object that responds to several methods.

## Show Widget

Show the widget window.

```typescript theme={null}
widget.openWidget();
```

## Hide Widget

Hide the widget window if it is open.

```typescript theme={null}
widget.closeWidget();
```

## Show Popup

Show the pop up window.

<ParamField type="string | latest">
  ID of a release note to show in pop-up. Use "latest" to show the latest release.
</ParamField>

<CodeGroup>
  ```typescript latest theme={null}
  widget.openPopup('latest');
  ```

  ```typescript specific release theme={null}
  widget.openPopup(RELEASE_ID);
  ```
</CodeGroup>

## Hide Popup

Hide the popup window if it is open.

```typescript theme={null}
widget.closePopup();
```


# Overview
Source: https://docs.onset.io/developers/widget/overview

Show your release notes inside your own app.

The widget puts your release notes inside your product, where customers already are, instead of hoping they visit your page. Attach it to a "What's new" button or a bell icon, and new releases surface automatically.

## What it does

* Shows your published releases in a panel inside your app
* Automatically pops up the latest release a visitor hasn't seen yet
* Follows a light, dark, or system theme
* Can be opened, closed, and positioned programmatically from your own UI

## Set it up

<Steps>
  <Step title="Get your script">
    Go to **Settings → Widget**. You'll find your widget script and a preview.
  </Step>

  <Step title="Install it">
    Add the script to your app, or install the SDK via npm, yarn, or CDN. Full
    instructions in [Widget install](/developers/widget/install).
  </Step>

  <Step title="Configure and control it">
    Set appearance and behavior options with
    [configuration](/developers/widget/configuration), and open or close the
    widget and popup with the [methods](/developers/widget/methods).
  </Step>
</Steps>

## How "seen" state works

The widget does not identify users, and there is no user or identity option to pass to it.

Instead, it tracks which releases have already been shown in an `onset:latest` cookie on your own domain, holding a comma-separated list of release IDs. On load, the widget compares your latest release against that cookie:

* **Not in the cookie**: the release popup opens, and the ID is added to the cookie.
* **Already in the cookie**: nothing happens.
* **No cookie at all**: the current latest release ID is recorded and no popup is shown, so a first-time visitor isn't interrupted by an announcement they have no context for.

Set `showLatestPopup: false` in your [configuration](/developers/widget/configuration) to disable the popup entirely and open the widget only when the user asks for it.

<Note>
  Because seen state lives in a cookie, it is per browser and per domain. The same person on a second device, in a different browser, or after clearing cookies will be treated as new. If you need per-user read state, track it yourself and call [`openPopup`](/developers/widget/methods) when you decide it's warranted.
</Note>

## What appears in the widget

The same published, public releases that appear on your page. [Private releases](/guides/releases/visibility) and drafts are excluded.

<Tip>
  Put the widget trigger somewhere persistent, like a nav bar or user menu, rather
  than in a modal users close and never open again.
</Tip>


# Custom From Address
Source: https://docs.onset.io/email/custom-from-address

Send release notifications from your own email address to match your brand identity.

## Description

You can customize the **From address** used in release notification emails to reflect your own domain or brand name.\
This helps improve trust and deliverability when communicating with your audience.

## How to enable

<Steps>
  <Step title="Navigate to Settings page">
    Go to **Settings → Email** in your workspace.
  </Step>

  <Step title="Enter your From address">
    Enter your preferred **From email address** (e.g. [updates@yourcompany.com](mailto:updates@yourcompany.com)).
  </Step>

  <Step title="Save">
    Once verified, click **Save Changes** to activate your custom From address.
  </Step>

  <Step title="Verify ownership">
    A confirmation email will be sent to the address you entered.\
    Open the email and click the verification link to confirm ownership.
  </Step>
</Steps>

### How it works

After verification, all outgoing release notification emails will use your custom address in the "**From**" field.\
If verification isn't completed, Onset will continue sending from the default address.


# Custom Subject
Source: https://docs.onset.io/email/custom-subject

Personalize your email subject line with dynamic placeholders for better engagement.

You can define a custom subject format for all release notification emails.\
Use dynamic variables to automatically include relevant information in each message.

## Supported Variables

<ParamField type="string">
  The release title
</ParamField>

<ParamField type="string">
  The release version (if available)
</ParamField>

<ParamField type="string">
  The project name (if available)
</ParamField>

<ParamField type="string">
  Your workspace name
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Settings page">
    Go to **Settings → Email** in your workspace.
  </Step>

  <Step title="Enter your subject format">
    Enter a subject template using any of the supported variables.\
    Example: `[{workspace}] {title} ({version})`
  </Step>

  <Step title="Save">
    Click **Save Changes** to apply your new subject format.
  </Step>
</Steps>

### How it works

Each time a release email is sent, Onset replaces the variables with actual values.\
For example:\
`[{workspace}] {title} ({version})` → `[Onset] API Improvements (v2.3.0)`


# Billing
Source: https://docs.onset.io/guides/billing

Plans, limits, upgrading, and what happens when you downgrade.

Manage your subscription under **Settings → Workspace → Billing**. Only the workspace **Owner** can access it.

Current prices are on the [pricing page](https://www.onset.io/pricing). Paid plans are billed monthly or yearly, with a **30-day free trial**.

## Limits

|                    | Free      | Team      | Business  |
| ------------------ | --------- | --------- | --------- |
| Team members       | 1         | 5         | Unlimited |
| Subscribers        | 1,000     | Unlimited | Unlimited |
| Releases, projects | Unlimited | Unlimited | Unlimited |

## Features by plan

| Feature                                                                                                                                       | Free | Team | Business |
| --------------------------------------------------------------------------------------------------------------------------------------------- | :--: | :--: | :------: |
| Public page, [custom domain](/page/custom-domains), [widget](/developers/widget/overview), [REST API](/developers/api-reference/introduction) |   ✓  |   ✓  |     ✓    |
| [AI writing tools](/guides/releases/ai-assistant)                                                                                             |   -  |   ✓  |     ✓    |
| [AI release summaries](/guides/releases/ai-assistant)                                                                                         |   -  |   ✓  |     ✓    |
| [Scheduled releases](/guides/releases/publishing)                                                                                             |   -  |   ✓  |     ✓    |
| [Password-protected page](/page/privacy/password-protected)                                                                                   |   -  |   ✓  |     ✓    |
| Remove Onset branding                                                                                                                         |   -  |   ✓  |     ✓    |
| [Custom sender address](/email/custom-from-address)                                                                                           |   -  |   -  |     ✓    |
| [Custom email subject](/email/custom-subject)                                                                                                 |   -  |   -  |     ✓    |
| [Email-whitelisted page](/page/privacy/email-whitelisted-page)                                                                                |   -  |   -  |     ✓    |
| Approved email domains for sign-up                                                                                                            |   -  |   -  |     ✓    |

Enterprise includes everything in Business. Contact [support@onset.io](mailto:support@onset.io) for terms.

## Trials

Starting a trial gives you the full plan immediately. A trialing subscription is treated exactly like an active one. If a trial ends without payment, the workspace reverts to Free and the downgrade rules below apply.

## Upgrading

Upgrades take effect as soon as payment succeeds, and are prorated, so you pay only the difference for the remainder of the billing cycle.

## Downgrading and canceling

**Canceling** keeps your plan active until the end of the paid period. At that point the workspace moves to Free.

**Switching to a lower plan** takes effect when the subscription changes in Stripe, and downgrade credits are applied to your next invoice.

Your content is never deleted. Releases and subscribers all stay. But Onset automatically turns off settings your new plan doesn't include:

<Warning>
  **Page privacy is changed, not just disabled.**

  * Downgrading to **Free** with a [password-protected page](/page/privacy/password-protected): privacy switches to **private**.
  * Downgrading to **Free or Team** with an [email-whitelisted page](/page/privacy/email-whitelisted-page): privacy switches to **private**.

  A private page is not publicly reachable. If you were relying on password protection to gate a page that customers use, they will lose access at downgrade. Set privacy back to public first if that's what you want.
</Warning>

Downgrading to **Free or Team** also clears your email customizations:

* The [custom sender address](/email/custom-from-address) is removed and its domain verification is reset. Re-adding it later means verifying the domain again.
* The [custom release subject](/email/custom-subject) is removed and notifications fall back to the default subject line.

## Exceeding limits after a downgrade

Existing data stays put if you end up over a limit, so you keep your subscribers and members. You'll need to get back under the limit before adding new ones or publishing new updates.

## Invoices and payment method

Past invoices and your payment method are available under **Settings → Workspace → Billing**.

## Deleting a workspace

Canceling a plan does not delete anything. To remove a workspace entirely, use **Settings → Workspace → General → Delete workspace**.

<Warning>
  Deleting a workspace is permanent and removes your releases and subscribers. Export anything you need via the [REST API](/developers/api-reference/introduction) first.
</Warning>


# Labels
Source: https://docs.onset.io/guides/labels

Tag releases so customers can filter for what matters to them.

Labels are short tags like **New**, **Improved**, **Fixed**, or **Breaking change**. They show up on your public page and visitors can filter by them.

## Create a label

<Steps>
  <Step title="Open Labels">
    Go to **Settings → Workspace → Labels**.
  </Step>

  <Step title="Add a label">
    Click **Create label**, enter a name, and pick a color.
  </Step>
</Steps>

## Apply labels

Open a release and choose labels in the details panel. A release can have multiple labels.

## Suggested set

Keeping the list short makes filtering useful. A common starting point:

| Label        | Use for                                        |
| ------------ | ---------------------------------------------- |
| **New**      | New functionality.                             |
| **Improved** | Changes to existing functionality.             |
| **Fixed**    | Bug fixes.                                     |
| **Breaking** | Changes that require action from the customer. |

<Tip>
  Deleting a label removes it from every release that used it. Renaming is safe.
</Tip>


# Appearance
Source: https://docs.onset.io/guides/page/appearance

Brand your public page with logos, colors, and social previews.

Configure this under **Settings → Page → Appearance**.

| Setting              | What it does                                                  |
| -------------------- | ------------------------------------------------------------- |
| **Favicon**          | The icon browsers show in the URL bar and on tabs.            |
| **Light theme logo** | Shown when your page is in light mode.                        |
| **Dark theme logo**  | Shown when your page is in dark mode.                         |
| **Social preview**   | The image used when someone shares your page on social media. |
| **Accent color**     | Your brand color, used for links, buttons, and highlights.    |
| **Onset branding**   | Show or hide "Powered by Onset" on your page.                 |

## Logos and dark mode

Upload both a light and a dark logo. Onset switches between them automatically based on the visitor's theme. A single dark-text logo will disappear against a dark background.

## Social previews

The social preview image is the fallback used when your page is shared. Individual releases also get automatically generated Open Graph images based on their title, so links to specific releases look right without extra work.

## Removing Onset branding

Hiding the Onset branding is available on the Team plan and above. See [Billing](/guides/billing).

## Related

* [Custom domains](/page/custom-domains) for hosting the page on your own domain
* [Preferences](/guides/page/preferences) for language, SEO, and default views


# Feeds
Source: https://docs.onset.io/guides/page/feeds

RSS, Atom, and JSON feeds for your releases.

Every Onset page exposes machine-readable feeds. Use them to pipe your updates into readers, internal dashboards, Zapier-style automations, or your own site.

Replace `yourpage.onset.io` with your own subdomain or [custom domain](/page/custom-domains).

## Combined feeds

| Feed        | URL                                     |
| ----------- | --------------------------------------- |
| RSS         | `https://yourpage.onset.io/feed.xml`    |
| Atom        | `https://yourpage.onset.io/atom.xml`    |
| JSON        | `https://yourpage.onset.io/data.json`   |
| Latest item | `https://yourpage.onset.io/latest.json` |

## Releases

| Feed | URL                                           |
| ---- | --------------------------------------------- |
| RSS  | `https://yourpage.onset.io/releases/feed.xml` |
| Atom | `https://yourpage.onset.io/releases/atom.xml` |
| JSON | `https://yourpage.onset.io/releases.json`     |

## llms.txt

Onset also publishes an `llms.txt` at `https://yourpage.onset.io/llms.txt`, a plain-text index of your updates for AI assistants and crawlers that support the convention.

## What's included

Feeds contain published, public items only. [Private releases](/guides/releases/visibility) and drafts never appear. If your page is password protected or email restricted, the feeds are protected too.

<Tip>
  `latest.json` is handy for showing "What's new" inline on your own marketing site without embedding the full [widget](/developers/widget/overview).
</Tip>

## Need more control?

For filtering, pagination, and write access, use the [REST API](/developers/api-reference/introduction) or [webhooks](/developers/webhooks) instead of feeds.


# Page Preferences
Source: https://docs.onset.io/guides/page/preferences

Language, SEO, and default views for your public page.

Configure this under **Settings → Page → Preference**.

## Page language

Sets the default language for your public page. The default is English. This controls Onset's own interface strings (buttons, labels, dates), not the content you write.

## SEO crawling

Controls whether search engines index your page.

* **Enabled** lets your releases appear in search results. Usually what you want: release notes rank well for "does *product* support X" queries.
* **Disabled** adds `noindex, nofollow` to every page. Use this for internal or pre-launch pages.

<Note>
  If your page is [password protected](/page/privacy/password-protected) or [email restricted](/page/privacy/email-whitelisted-page), search engines can't index the content regardless of this setting.
</Note>

## Default views

Under **Settings → Page → Releases** you can set the default view for the releases section.

Visitors can change the view themselves; this just controls what they land on.


# Projects
Source: https://docs.onset.io/guides/projects

Group releases that belong to the same product or initiative.

If you ship more than one product, or one product with distinct areas like *Web*, *iOS*, and *API*, projects let you keep their updates separate while managing everything in a single workspace.

## Create a project

<Steps>
  <Step title="Open Projects">
    Go to **Settings → Workspace → Projects**.
  </Step>

  <Step title="Add a project">
    Click **Create project** and give it a name.
  </Step>
</Steps>

## Assign a project

When creating or editing a release, pick a project in the details panel. A release can belong to one project.

## How projects appear publicly

Visitors can filter your releases by project on your public page, so someone who only cares about your API updates can narrow the feed to just those.

<Tip>
  Use **projects** for *which product this belongs to* and [labels](/guides/labels) for *what kind of change this is* (feature, fix, improvement). They work well together.
</Tip>


# Quickstart
Source: https://docs.onset.io/guides/quickstart

Set up your workspace and publish your first release in a few minutes.

Onset gives you two places to communicate with customers: a **release notes** feed and an in-app **widget**. They both share the same public page.

## Create your workspace

<Steps>
  <Step title="Sign up">
    Create an account at [app.onset.io](https://app.onset.io/signup). No credit card required.
  </Step>

  <Step title="Name your workspace">
    Your workspace name and slug decide your default public URL: `yourslug.onset.io`. You can change both later in **Settings → Workspace → General**, and point a [custom domain](/page/custom-domains) at it.
  </Step>

  <Step title="Invite your team">
    Go to **Settings → Workspace → Members** and invite teammates. See [Team members](/guides/team-members) for what each role can do.
  </Step>
</Steps>

## Publish your first release

<Steps>
  <Step title="Create a release">
    From the dashboard, go to **Releases → New release**. Give it a title and write the body. See [Writing releases](/guides/releases/writing).
  </Step>

  <Step title="Add structure (optional)">
    Add a [version number](/guides/releases/versioning), [labels](/guides/labels), a [project](/guides/projects), or [contributors](/guides/releases/contributors).
  </Step>

  <Step title="Publish">
    Publish immediately or [schedule](/guides/releases/publishing) it. In the publish dialog you can also notify subscribers by email and post to Slack or Discord.
  </Step>
</Steps>

Your release is now live on your public page, in your RSS/JSON [feeds](/guides/page/feeds), and in the [widget](/developers/widget/overview) if you've installed it.

## Where to go next

<Columns>
  <Card title="Grow your audience" icon="users" href="/guides/subscribers/overview">
    Collect subscribers and segment them into lists.
  </Card>

  <Card title="Brand your page" icon="palette" href="/guides/page/appearance">
    Logos, colors, social previews, and dark mode.
  </Card>

  <Card title="Install the widget" icon="window-alt" href="/developers/widget/install">
    Show release notes inside your own app.
  </Card>
</Columns>


# AI Assistant
Source: https://docs.onset.io/guides/releases/ai-assistant

Turn pull requests and issues into a first draft, and generate release summaries.

Onset's AI tools help with the two slowest parts of release notes: starting the draft, and condensing it afterwards.

<Note>
  AI writing tools and AI release summaries are available on the Team plan and above. See [Billing](/guides/billing).
</Note>

## Draft from your issue tracker

Connect [GitHub](/integrations/github), [Linear](/integrations/linear), or [Jira](/integrations/jira), then use the assistant inside the release editor to pull in merged pull requests or completed issues and turn them into a customer-facing draft.

<Steps>
  <Step title="Connect an integration">
    Go to **Settings → Integrations** and connect GitHub, Linear, or Jira.
  </Step>

  <Step title="Open the assistant">
    In the release editor, open the AI assistant.
  </Step>

  <Step title="Select the work to include">
    Pick the pull requests or issues this release covers.
  </Step>

  <Step title="Review and edit">
    The assistant produces a draft. Treat it as a starting point. It doesn't know your customers' context or which changes actually matter to them.
  </Step>
</Steps>

## Rewrite and improve

Select text in the editor and use the assistant to rephrase, shorten, or adjust tone. Useful for turning a commit-message-flavored sentence into something a customer would read.

## Release summaries

Onset can generate a short summary of a release to show above the full notes on your public page. Turn this on under **Settings → Page → Releases → Release summaries**.

<Warning>
  Always read AI output before publishing, especially for anything involving pricing, security, or breaking changes.
</Warning>


# Contributors
Source: https://docs.onset.io/guides/releases/contributors

Credit the teammates behind each release.

Contributors attach names and avatars to a release, so the people who did the work get visible credit on the update your customers actually read.

## Add contributors

Open a release and select contributors in the details panel. You can pick any [member of your workspace](/guides/team-members). The picker is limited to your members, so everyone credited is someone on your team.

A release can have as many contributors as you like. Their avatars appear together on the release.

<Tip>
  Credit everyone who touched the release, not just whoever wrote the notes. Design, support, and QA rarely show up in a changelog otherwise, and this is the one place customers see them.
</Tip>

## Show them publicly

Contributors are only displayed if the page setting is on. Go to **Settings → Page → Releases** and enable **Release contributors**: *"When enabled release contributor names and avatars are displayed."*

Turn it off if you'd rather present releases as coming from the company rather than from individuals.

## Via the API

Contributors can also be set programmatically when creating or updating a release, using workspace member IDs. See the [Releases API](/developers/api-reference/introduction).


# Import from AnnounceKit
Source: https://docs.onset.io/guides/releases/import/announcekit

Bring your AnnounceKit posts into Onset from your public JSON feed.

The AnnounceKit importer reads your public JSON feed. No API key needed, but it also means Onset only sees what's publicly visible.

<Warning>
  This importer is in **beta**. Review the imported releases before pointing customers at your new page.
</Warning>

## What you'll need

Your **AnnounceKit URL**, e.g. `yourcompany.announcekit.app`.

Before starting, confirm the feed is reachable by opening `https://yourcompany.announcekit.app/jsonfeed.json` in a browser. If that returns posts, the import will work. If it 404s or is empty, your feed isn't public and there's nothing for Onset to read.

## Run the import

<Steps>
  <Step title="Open Imports">
    Go to **Settings → Workspace → Import**.
  </Step>

  <Step title="Start the AnnounceKit import">
    Find **AnnounceKit Import** in the list and click **Start import**.
  </Step>

  <Step title="Enter your URL">
    Type the host only, e.g. `yourcompany.announcekit.app`. The `https://` is added for you.
  </Step>

  <Step title="Wait for the email">
    The import runs in the background. Onset emails you when it's finished, so you don't need to keep the tab open.
  </Step>
</Steps>

## What comes across

|                       |                                                                             |
| --------------------- | --------------------------------------------------------------------------- |
| **Title and content** | Post HTML is converted into the Onset editor format.                        |
| **Images**            | Re-uploaded to Onset, so they keep working after you shut down AnnounceKit. |
| **Dates**             | Taken from the feed's last-modified date for each post.                     |
| **Status**            | Everything in the feed arrives published and public.                        |
| **URLs**              | The slug from the AnnounceKit post URL is reused, so paths carry over.      |

Not imported: drafts and anything not in the public feed, labels, projects, reactions, feedback, segments, and your AnnounceKit audience. [Import subscribers separately](/guides/subscribers/import) from a CSV.

<Note>
  Because dates come from when a post was **last modified**, an old post you edited recently will import with the recent date. Sort your releases by date afterwards and fix any that look out of order.
</Note>

## Re-running the import

Safe. Releases are matched on their slug, and anything already in your workspace is skipped rather than duplicated.

## Next steps

See [After importing](/guides/releases/import/overview#after-importing) for what's worth cleaning up before you announce the move.


# Import from Beamer
Source: https://docs.onset.io/guides/releases/import/beamer

Bring your Beamer posts into Onset using your Beamer API key.

The Beamer importer reads your posts through the Beamer API, so it can see drafts as well as published posts.

<Warning>
  This importer is in **beta**. Review the imported releases before pointing
  customers at your new page.
</Warning>

## What you'll need

Your **Beamer API key**. Find it in your Beamer account under **Settings → API**, or go straight to [app.getbeamer.com/settings#api](https://app.getbeamer.com/settings#api).

<Note>
  The key gives full access to your Beamer account, so treat it like a password.
  You can rotate it in Beamer once the import is done.
</Note>

## Run the import

<Steps>
  <Step title="Open Imports">Go to **Settings → Workspace → Import**.</Step>

  <Step title="Start the Beamer import">
    Find **Beamer Import** in the list and click **Start import**.
  </Step>

  <Step title="Paste your API key">Enter the key and submit.</Step>

  <Step title="Wait for the email">
    The import runs in the background. Onset emails you when it's finished, so
    you don't need to keep the tab open.
  </Step>
</Steps>

## What comes across

|                       |                                                                                   |
| --------------------- | --------------------------------------------------------------------------------- |
| **Title and content** | Post HTML is converted into the Onset editor format.                              |
| **Images**            | Re-uploaded to Onset, so they keep working after you shut down Beamer.            |
| **Dates**             | The original post date becomes the release date.                                  |
| **Status**            | Published posts arrive as published releases; unpublished posts arrive as drafts. |
| **Pinned posts**      | Stay pinned.                                                                      |
| **URLs**              | The slug from the Beamer post URL is reused, so paths carry over.                 |

Not imported: labels, projects, reactions, feedback, comments, segments and targeting rules, and your Beamer audience. [Import subscribers separately](/guides/subscribers/import) from a CSV.

## Translations

Beamer posts can hold several translations. Onset imports one version per post: the **English** translation if there is one, otherwise the first translation on the post. Other languages are skipped, so check any posts you maintain in multiple languages.

## Re-running the import

Safe. Releases are matched on their slug, and anything already in your workspace is skipped rather than duplicated. If a first pass only caught part of your history, run it again.

## Next steps

See [After importing](/guides/releases/import/overview#after-importing) for what's worth cleaning up before you announce the move.


# Import from Changelogfy
Source: https://docs.onset.io/guides/releases/import/changelogfy

Bring your Changelogfy posts into Onset from your public RSS feed.

The Changelogfy importer reads your public changelog RSS feed. No API key needed, but it also means Onset only sees what's publicly visible.

<Warning>
  This importer is in **beta**. Review the imported releases before pointing
  customers at your new page.
</Warning>

## What you'll need

Your **Changelogfy URL** — either the Changelogfy subdomain, e.g. `yourcompany.changelogfy.com`, or the custom domain you point at it.

Before starting, confirm the feed is reachable by opening `https://yourcompany.changelogfy.com/changelog/rss` in a browser. If that returns posts, the import will work.

## Run the import

<Steps>
  <Step title="Open Imports">Go to **Settings → Workspace → Import**.</Step>

  <Step title="Start the Changelogfy import">
    Find **Changelogfy Import** in the list and click **Start import**.
  </Step>

  <Step title="Enter your URL">
    Type the host only, e.g. `yourcompany.changelogfy.com`. The `https://` and
    the feed path are added for you.
  </Step>

  <Step title="Wait for the email">
    The import runs in the background. Onset emails you when it's finished, so
    you don't need to keep the tab open.
  </Step>
</Steps>

## What comes across

|                       |                                                                             |
| --------------------- | --------------------------------------------------------------------------- |
| **Title and content** | Post HTML is converted into the Onset editor format.                        |
| **Images**            | Re-uploaded to Onset, so they keep working after you shut down Changelogfy. |
| **Dates**             | The original publish date becomes the release date.                         |
| **Status**            | Everything in the feed arrives published and public.                        |
| **URLs**              | The slug from the Changelogfy post URL is reused.                           |

Not imported: drafts and anything not in the public feed, categories, projects, reactions, feedback, knowledge base articles, and your Changelogfy audience. [Import subscribers separately](/guides/subscribers/import) from a CSV.

<Note>
  Changelogfy post categories — **Improvement**, **Fix**, **New Feature** — don't
  come across. Set up [labels](/guides/labels) in Onset and apply them to the
  imported releases afterwards.
</Note>

## Post URLs

Changelogfy post URLs include a language segment, like `/en/your-post-title`. Onset takes only the last part of the URL for the slug, so the language prefix is dropped and your Onset paths come out clean.

## Re-running the import

Safe. Releases are matched on their slug, and anything already in your workspace is skipped rather than duplicated.

## Next steps

See [After importing](/guides/releases/import/overview#after-importing) for what's worth cleaning up before you announce the move.


# Import from Noticeable
Source: https://docs.onset.io/guides/releases/import/noticeable

Bring your Noticeable publications into Onset from your Newspage JSON feed.

The Noticeable importer reads the JSON feed published by your Newspage. No API key needed, but it also means Onset only sees what's publicly visible.

<Warning>
  This importer is in **beta**. Review the imported releases before pointing
  customers at your new page.
</Warning>

## What you'll need

Your **Newspage URL** — either the Noticeable subdomain, e.g. `yourcompany.noticeable.news`, or the custom domain you point at it, e.g. `updates.yourcompany.com`.

Before starting, confirm the feed is reachable by opening `https://updates.yourcompany.com/feed.json` in a browser. If that returns publications, the import will work.

<Note>
  Each Newspage publishes its own feed. If you run more than one Noticeable
  project, import them one at a time using each project's own URL.
</Note>

## Run the import

<Steps>
  <Step title="Open Imports">Go to **Settings → Workspace → Import**.</Step>

  <Step title="Start the Noticeable import">
    Find **Noticeable Import** in the list and click **Start import**.
  </Step>

  <Step title="Enter your URL">
    Type the host only, e.g. `updates.yourcompany.com`. The `https://` is added
    for you.
  </Step>

  <Step title="Wait for the email">
    The import runs in the background. Onset emails you when it's finished, so
    you don't need to keep the tab open.
  </Step>
</Steps>

## What comes across

|                       |                                                                              |
| --------------------- | ---------------------------------------------------------------------------- |
| **Title and content** | Publication HTML is converted into the Onset editor format.                  |
| **Images**            | Re-uploaded to Onset, so they keep working after you shut down Noticeable.   |
| **Dates**             | The original publish date becomes the release date.                          |
| **Status**            | Everything in the feed arrives published and public.                         |
| **URLs**              | The slug from the Noticeable publication URL is reused, so paths carry over. |

Not imported: drafts and anything not in the public feed, labels, projects, reactions, feedback, and your Noticeable audience. [Import subscribers separately](/guides/subscribers/import) from a CSV.

<Note>
  Publication **labels** don't come across. Noticeable labels are a per-page
  taxonomy that rarely lines up with how you'll organize things in Onset, so
  it's worth setting up [labels](/guides/labels) fresh and applying them
  afterwards.
</Note>

## Feed pagination

The feed returns 100 publications per request and Onset follows the cursor through the rest, so a long history comes across in full rather than stopping at the most recent page. Larger archives take proportionally longer.

## Re-running the import

Safe. Releases are matched on their slug, and anything already in your workspace is skipped rather than duplicated. If a first pass only caught part of your history, run it again.

## Next steps

See [After importing](/guides/releases/import/overview#after-importing) for what's worth cleaning up before you announce the move.


# Overview
Source: https://docs.onset.io/guides/releases/import/overview

Migrate your existing release notes from Beamer, AnnounceKit, Changelogfy, Noticeable, or ReleaseNotes.io.

If you're moving to Onset from another release notes tool, you can bring your published history with you rather than starting from an empty page.

Imports live under **Settings → Workspace → Import**.

## Supported tools

<CardGroup>
  <Card title="Beamer" icon="file-import" href="/guides/releases/import/beamer">
    Needs your Beamer API key. Brings across drafts as well as published posts.
  </Card>

  <Card title="AnnounceKit" icon="file-import" href="/guides/releases/import/announcekit">
    Needs your public URL, e.g. `yourcompany.announcekit.app`.
  </Card>

  <Card title="Changelogfy" icon="file-import" href="/guides/releases/import/changelogfy">
    Needs your public URL, e.g. `yourcompany.changelogfy.com`.
  </Card>

  <Card title="Noticeable" icon="file-import" href="/guides/releases/import/noticeable">
    Needs your Newspage URL, e.g. `yourcompany.noticeable.news`.
  </Card>

  <Card title="ReleaseNotes.io" icon="file-import" href="/guides/releases/import/releasenotesio">
    Needs your public URL, e.g. `yourcompany.releasenotes.io`.
  </Card>
</CardGroup>

<Note>
  These importers bring across **release notes only**, not your subscribers. Import those separately from a CSV; see [Importing subscribers](/guides/subscribers/import).
</Note>

## How imports work

They all behave the same way once started:

* **They run in the background.** Onset emails you when the import finishes, so you can close the tab.
* **Content is converted.** Post HTML becomes Onset editor content, and images are re-uploaded to Onset so they keep working after you shut down your old tool.
* **URLs carry over.** Each release reuses the slug from its original post URL.
* **Re-running is safe.** Releases already in your workspace are matched on slug and skipped rather than duplicated.

<Warning>
  These importers are in **beta**. Review the imported releases before pointing customers at your new page. Check formatting, embedded media, and publish dates in particular.
</Warning>

## After importing

A few things worth doing before you announce the move:

* Add [labels](/guides/labels) and [projects](/guides/projects) to imported releases. These don't come across, since they're specific to how you organize things in Onset.
* Set up [redirects](/page/custom-domains) from your old page if it lived on a domain you control.
* Check that publish dates look right, so your archive reads in the correct order.

## Migrating from something else

Not on the list? Email [support@onset.io](mailto:support@onset.io), or create releases in bulk yourself through the [Releases API](/developers/api-reference/introduction).


# Import from ReleaseNotes.io
Source: https://docs.onset.io/guides/releases/import/releasenotesio

Bring your ReleaseNotes.io posts into Onset from your public RSS feed.

The ReleaseNotes.io importer reads your public RSS feed. No API key needed, but it also means Onset only sees what's publicly visible.

<Warning>
  This importer is in **beta**. Review the imported releases before pointing
  customers at your new page.
</Warning>

## What you'll need

Your **ReleaseNotes.io URL**, e.g. `yourcompany.releasenotes.io`.

Before starting, confirm the feed is reachable by opening `https://yourcompany.releasenotes.io/feed` in a browser. If that returns posts, the import will work.

## Run the import

<Steps>
  <Step title="Open Imports">Go to **Settings → Workspace → Import**.</Step>

  <Step title="Start the ReleaseNotes.io import">
    Find **ReleaseNotes.io Import** in the list and click **Start import**.
  </Step>

  <Step title="Enter your URL">
    Type the host only, e.g. `yourcompany.releasenotes.io`. The `https://` is
    added for you.
  </Step>

  <Step title="Wait for the email">
    The import runs in the background. Onset emails you when it's finished, so
    you don't need to keep the tab open.
  </Step>
</Steps>

## What comes across

|                       |                                                                                 |
| --------------------- | ------------------------------------------------------------------------------- |
| **Title and content** | Post HTML is converted into the Onset editor format.                            |
| **Images**            | Re-uploaded to Onset, so they keep working after you shut down ReleaseNotes.io. |
| **Dates**             | The original publish date becomes the release date.                             |
| **Status**            | Everything in the feed arrives published and public.                            |
| **URLs**              | The slug from the ReleaseNotes.io post URL is reused, so paths carry over.      |

Not imported: drafts and anything not in the public feed, labels, projects, reactions, feedback, and your ReleaseNotes.io audience. [Import subscribers separately](/guides/subscribers/import) from a CSV.

## Feed pagination

The RSS feed serves about 10 posts per page, and Onset walks through the pages until it runs out. Long histories take longer, and the importer stops at 1,000 releases. If you have more than that, email [support@onset.io](mailto:support@onset.io) before you start.

## Re-running the import

Safe. Releases are matched on their slug, and anything already in your workspace is skipped rather than duplicated. If a first pass only caught part of your history, run it again.

## Next steps

See [After importing](/guides/releases/import/overview#after-importing) for what's worth cleaning up before you announce the move.


# Overview
Source: https://docs.onset.io/guides/releases/overview

How release notes work in Onset, from draft to published.

A **release** is a single update you publish to your customers. Each one has a title, a body, and optional extras like a version number, labels, contributors, and a change list.

## Release states

| State         | What it means                                                       |
| ------------- | ------------------------------------------------------------------- |
| **Draft**     | Only visible to your team. Not on the public page, not in feeds.    |
| **Scheduled** | Written and queued to publish automatically at a set date and time. |
| **Released**  | Live on your public page, in your feeds, and in the widget.         |

## Where a published release shows up

* Your **public page** (`yourslug.onset.io` or your [custom domain](/page/custom-domains))
* Your **RSS, Atom, and JSON [feeds](/guides/page/feeds)**
* The in-app **[widget](/developers/widget/overview)**, if installed
* **Email**, **Slack**, and **Discord**, if you enable those notifications when publishing

## Anatomy of a release

<AccordionGroup>
  <Accordion title="Title and permalink">
    The title is what customers see first. Onset generates a permalink from it,
    which you can edit under **Permalink**. Worth setting deliberately if you
    plan to link to the release from elsewhere.
  </Accordion>

  <Accordion title="Body">
    The main content. Supports rich text, Markdown, images, and media embeds.
    See [Writing releases](/guides/releases/writing).
  </Accordion>

  <Accordion title="Change list">
    A structured list of individual changes, each tagged with a change type like
    **New**, **Fixed**, or **Security**. Good for long releases where the body
    is a summary and the change list carries the detail. Change types are
    customizable; see [Writing releases](/guides/releases/writing).
  </Accordion>

  <Accordion title="Version">
    An optional version number and pre-release flag. See
    [Versioning](/guides/releases/versioning).
  </Accordion>

  <Accordion title="Contributors">
    Workspace members to credit on the release. See
    [Contributors](/guides/releases/contributors).
  </Accordion>

  <Accordion title="Projects and labels">
    Used to organize and filter releases. See [Projects](/guides/projects) and
    [Labels](/guides/labels).
  </Accordion>

  <Accordion title="Attachments and related items">
    Files and links related to this release.
  </Accordion>
</AccordionGroup>

## Publishing settings for the whole page

Some options are page-wide rather than per-release. Under **Settings → Page → Releases** you can turn the releases section on or off, choose the default view, and toggle whether contributors, reactions, and AI summaries are shown.


# Publishing & Scheduling
Source: https://docs.onset.io/guides/releases/publishing

Publish now or later, and notify subscribers, Slack, and Discord in one step.

## Publish a release

Click **Publish** in the release editor. The publish dialog is where you decide who gets told:

* **Email notification** sends to your subscribers. Choose which [subscriber lists](/guides/subscribers/lists) to notify.
* **Slack notification** posts to a channel in your connected [Slack](/integrations/slack) workspace.
* **Discord notification** posts to a channel in your connected [Discord](/integrations/discord) server.

Notifications are opt-in per release, so a typo fix doesn't have to email everyone.

## Schedule for later

In the publish dialog, choose **Schedule** and set a date and time. The release stays in **Scheduled** state and publishes automatically, including any notifications you enabled.

<Note>
  Scheduled releases are available on the Team plan and above. See [Billing](/guides/billing).
</Note>

### Timezones

There is no workspace timezone setting. The time you pick is interpreted in **your own browser's timezone** at the moment you set it, then stored as an absolute point in time.

So a release scheduled for 9:00 AM by someone in Berlin goes out at 9:00 AM Berlin time. It will show as 3:00 AM to a teammate in New York looking at the same release. The release goes out at one fixed instant for everyone; only the displayed local time differs.

<Tip>
  If you're coordinating a launch with someone in another region, agree on the absolute moment rather than the wall-clock time. "9:00 Berlin" is unambiguous, "9:00" is not.
</Tip>

### Scheduling window

* The earliest you can schedule is **tomorrow**. You can't schedule a release for later today; publish immediately instead.
* The latest is **two months out**.

### Changing a schedule

You can change or clear the scheduled time at any point before it goes out.

<Warning>
  Clearing the date on an already-scheduled release publishes it immediately. To keep it unpublished, move it back to **Draft** first.
</Warning>

## Customizing notification emails

The sender address and subject line are configured workspace-wide:

* [Custom from address](/email/custom-from-address) sends from your own domain
* [Custom subject](/email/custom-subject) uses dynamic placeholders in the subject line

## Republishing

Editing an already-published release updates it everywhere immediately. It does **not** resend email, Slack, or Discord notifications, so you can fix a typo without a second announcement.


# Reactions
Source: https://docs.onset.io/guides/releases/reactions

Let readers react to releases and see what actually lands.

Reactions are the lowest-friction feedback you can collect. A reader doesn't have to write anything. One click tells you whether a change resonated.

## Enable reactions

Go to **Settings → Page → Releases** and enable **Release reactions**: *"Allow users to react to releases."*

Reactions then appear at the bottom of each release on your public page and in the widget.

## Reading the results

Reaction counts show up on each release in your dashboard. What to look for:

* High reactions and no support tickets: the change was clear and welcome.
* Lots of traffic but almost no reactions: either it didn't matter to readers, or the notes didn't explain why it should.
* A negative skew on a change you thought was minor: worth a follow-up post or a docs page.

<Note>
  Reactions are anonymous signal rather than a survey. Use them to decide what to look into, and confirm with something more specific before acting.
</Note>


# Versioning
Source: https://docs.onset.io/guides/releases/versioning

Attach version numbers to releases and flag pre-releases.

If your product has version numbers, showing them on your release notes makes it easy for customers to tell which build a change landed in.

## Enable versioning

<Steps>
  <Step title="Turn on the version field">
    Go to **Settings → Workspace → Releases** and enable **Version**: *"Include a version number in the release notes."*
  </Step>

  <Step title="Set a version per release">
    A **Version number** field appears in the release editor. Enter whatever scheme you use. It's a free-text field, so `2.4.0`, `2026.7`, and `v14` all work.
  </Step>
</Steps>

## Pre-releases

Enable **Pre-release** in the same settings section to get a pre-release toggle on each release. Marking a release as a pre-release labels it publicly, which is useful for betas, release candidates, and early-access rollouts that shouldn't be read as generally available.

<Tip>
  Pair pre-releases with a [label](/guides/labels) like **Beta** so customers can filter them out of the main feed.
</Tip>


# Visibility & Sharing
Source: https://docs.onset.io/guides/releases/visibility

Private releases, share links, and pinning important updates.

Not every release should be public, and not every public release deserves equal billing. Onset gives you three controls.

## Private releases

A private release is published inside your workspace but hidden from your public page, feeds, and widget. Use it for internal changelogs or for updates that aren't announced yet.

Toggle visibility in the release editor's settings panel.

## Private share links

You can share a release with specific people without making it public. Onset generates a secret link that renders the release for anyone who has it.

<Steps>
  <Step title="Open the release">
    Go to the release in your dashboard.
  </Step>

  <Step title="Create a share link">
    Open the share option and generate a link.
  </Step>

  <Step title="Send it">
    Anyone with the link can view the release. Revoke it at any time to cut off access.
  </Step>
</Steps>

Common uses: previewing an announcement with a customer before launch, or sharing an internal release with a stakeholder who isn't in your workspace.

<Warning>
  A share link is a secret URL, not an authenticated page. Anyone who has the link can open it, so don't use it for anything you'd need to prove access control over.
</Warning>

## Pinning

Pin a release to keep it at the top of your public page regardless of date. Good for a major launch, a migration notice, or a status update you want everyone to see first.

Unpin it when it stops being the most important thing. A permanently pinned release stops being read.

## Locking down the whole page

To restrict who can see your page at all, use [password protection](/page/privacy/password-protected) (Team plan and above) or [email whitelisting](/page/privacy/email-whitelisted-page) (Business plan and above).

<Note>
  If you downgrade below the required plan, the page privacy setting switches to **private** rather than reverting to public. See [Billing](/guides/billing).
</Note>


# Writing Releases
Source: https://docs.onset.io/guides/releases/writing

Use the editor, Markdown, images, and media embeds to write clear updates.

## The editor

The release body uses a rich text editor. Use the toolbar, or type Markdown and it converts as you go:

| You type     | You get                             |
| ------------ | ----------------------------------- |
| `# Heading`  | Heading                             |
| `**bold**`   | **bold**                            |
| `_italic_`   | *italic*                            |
| `` `code` `` | inline code                         |
| ` ```lang `  | code block with syntax highlighting |
| `- item`     | bulleted list                       |
| `1. item`    | numbered list                       |
| `> quote`    | blockquote                          |
| `---`        | divider                             |

Pasting Markdown from another tool works too. It converts on paste.

## Images

Drag an image into the editor, paste it from your clipboard, or use the toolbar to upload one.

## Media embeds

Paste a link on its own line and Onset embeds the player:

* YouTube
* Loom
* Vimeo

<Tip>
  A short Loom walking through a feature usually outperforms three paragraphs describing it.
</Tip>

## Change lists

For releases with many small changes, use the **change list** instead of stuffing everything into the body.

Each entry is a **change type** plus its content. There's no separate title field. You pick the type from a dropdown and write the change itself in the editor, with the same formatting available as the main body. Entries can be reordered by dragging.

A good pattern: the body explains *why this release matters*, the change list covers *everything that changed*.

### Change types

Onset ships with a default set, following the [Keep a Changelog](https://keepachangelog.com) convention:

| Type           | Use for                                            |
| -------------- | -------------------------------------------------- |
| **New**        | Functionality that didn't exist before.            |
| **Changed**    | Existing behavior that works differently now.      |
| **Deprecated** | Still works, but scheduled for removal.            |
| **Fixed**      | Bug fixes.                                         |
| **Removed**    | Functionality that's gone.                         |
| **Security**   | Vulnerability fixes and security-relevant changes. |

### Customize the types

The list isn't fixed. Go to **Settings → Workspace → Releases** to add your own types, rename existing ones, change their color, or reorder them. Each type has a title and a color, and the order you set is the order shown in the editor dropdown.

<Tip>
  Marking a change as **Deprecated** or **Removed** is the cheapest migration warning you can give customers, far cheaper than the support thread that follows a silent removal.
</Tip>

## Writing tips

* Lead with what the customer can now do, not what you built.
* Link to the relevant docs page rather than re-explaining it.
* Publish one release per meaningful change rather than a weekly dump. Your feeds and notifications get more useful that way.
* If you're stuck on the first draft, the [AI assistant](/guides/releases/ai-assistant) can generate one from your GitHub, Linear, or Jira activity.


# Importing Subscribers
Source: https://docs.onset.io/guides/subscribers/import

Bring your existing email subscribers into Onset from a CSV.

Imports live under **Settings → Workspace → Import**.

<Note>
  This page covers subscriber imports. To bring across your existing release notes from another tool, see [Importing release notes](/guides/releases/import/overview).
</Note>

## Import subscribers from a file

<Steps>
  <Step title="Prepare your file">
    A `.csv`, `.xls`, or `.xlsx` file with **no header row**, and **one email address per row**. Nothing else: no name column, no extra fields.
  </Step>

  <Step title="Upload it">
    Go to **Settings → Workspace → Import**, choose **CSV Subscriber Import**, and upload the file.
  </Step>

  <Step title="Wait for the email">
    The import runs in the background. Onset emails you when it's finished, so you don't need to keep the tab open.
  </Step>
</Steps>

Duplicate addresses are skipped rather than added twice, so re-running an import with overlapping data is safe.

<Warning>
  Only import addresses that opted in to hear from you. Importing a purchased or scraped list will hurt your deliverability and may violate anti-spam laws in your customers' jurisdictions.
</Warning>

## Assigning imported subscribers to a list

The CSV import doesn't ask which [list](/guides/subscribers/lists) to use. Imported subscribers land in your workspace and can be organized afterwards from **Audience → Subscribers**.

If you need subscribers placed on a specific list at creation time, use the [Subscribers API](/developers/api-reference/introduction) instead.

## Other sources

Subscribers can also reach your workspace by subscribing on your public page, being added manually, or through the API. See [Subscribers overview](/guides/subscribers/overview).


# Subscriber Lists
Source: https://docs.onset.io/guides/subscribers/lists

Segment your audience so the right people get the right updates.

Lists let you split your subscribers into groups and notify only the relevant ones when publishing a release.

## Create a list

<Steps>
  <Step title="Open Subscriber Lists">
    Go to **Settings → Workspace → Subscriber Lists**.
  </Step>

  <Step title="Add a list">
    Click **Create list** and name it.
  </Step>

  <Step title="Set the default (optional)">
    Under **Settings → Page → Subscribers**, choose the **Default subscriber list** that public sign-ups are added to.
  </Step>
</Steps>

## Useful segmentations

* **By product** mirrors your [projects](/guides/projects), so API customers don't get mobile app updates.
* **By audience** splits customers from your internal team and partners.
* **By depth** sends major launches to everyone and everything else to a smaller "all updates" list.

## Sending to specific lists

In the [publish dialog](/guides/releases/publishing), enable the email notification and select which lists to notify. Leaving a list out means those subscribers see the release on your page and feeds, but don't get an email.

<Tip>
  Two lists solve most segmentation problems. Start there and split further only when you find yourself deciding not to send an email because it would annoy part of the audience.
</Tip>


# Overview
Source: https://docs.onset.io/guides/subscribers/overview

Collect people who want to hear about your updates.

Subscribers are the email addresses that receive your release notifications. They arrive from several places:

| Source        | How they got there                                                                          |
| ------------- | ------------------------------------------------------------------------------------------- |
| **Page**      | Subscribed from your public page.                                                           |
| **Dashboard** | Added manually by your team.                                                                |
| **Import**    | Brought in from a CSV file. See [Importing subscribers](/guides/subscribers/import).        |
| **API**       | Created programmatically via the [Subscribers API](/developers/api-reference/introduction). |

## Let visitors subscribe

Go to **Settings → Page → Subscribers** and enable **Subscribers**: *"Let your visitors subscribe to receive updates via email."*

Two related settings:

* **Default subscriber list** sets which [list](/guides/subscribers/lists) new public subscribers are added to.
* **Anonymous subscribers** allows subscribing without creating an account.

## Managing subscribers

Find them under **Audience → Subscribers**. You can search, add subscribers manually, move them between lists, and remove them.

## What subscribers receive

Subscribers can be notified when a release is published. Notifications are opt-in per release. You choose in the [publish dialog](/guides/releases/publishing) whether to send email and to which lists.

## Subscriber limits

The Free plan includes up to 1,000 subscribers. Team, Business, and Enterprise are unlimited.

If you go over the limit, usually after a downgrade, you keep every subscriber you already have, but you can't add new ones until you upgrade or remove some.

## Unsubscribes

Every notification email includes an unsubscribe link. Unsubscribed addresses stop receiving mail immediately and are retained so they aren't accidentally re-added by a later import.


# Team Members
Source: https://docs.onset.io/guides/team-members

Invite teammates to your workspace and choose what they can do.

Manage your team in **Settings → Workspace → Members**.

## Roles

| Role       | Can do                                                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**  | Everything an admin can, plus transferring and deleting the workspace.                                                                      |
| **Admin**  | Full access, including workspace settings, billing, integrations, API keys, webhooks, projects, labels, and members.                        |
| **Member** | Write, edit and publish releases, and manage subscribers. Read-only on projects, labels and integrations. No workspace settings or billing. |
| **Viewer** | Read-only access to releases, projects and labels, plus reactions. Cannot create or edit anything, and cannot see subscribers.              |

There is exactly one owner per workspace. To hand it over, use **Settings → Workspace → General → Transfer workspace**.

### What each role can access

|                                            | Viewer | Member | Admin | Owner |
| ------------------------------------------ | :----: | :----: | :---: | :---: |
| View releases                              |    ✓   |    ✓   |   ✓   |   ✓   |
| React to releases                          |    ✓   |    ✓   |   ✓   |   ✓   |
| Write and publish releases                 |        |    ✓   |   ✓   |   ✓   |
| Manage subscribers                         |        |    ✓   |   ✓   |   ✓   |
| Manage projects and labels                 |        |        |   ✓   |   ✓   |
| Manage integrations, API keys and webhooks |        |        |   ✓   |   ✓   |
| Workspace settings, billing and members    |        |        |   ✓   |   ✓   |
| Transfer or delete the workspace           |        |        |       |   ✓   |

<Note>
  Viewers never see subscribers — the Subscribers section is hidden from them entirely. Use this role for people who need visibility into what's shipping without touching your audience data.
</Note>

## Invite a teammate

<Steps>
  <Step title="Open Members">
    Go to **Settings → Workspace → Members**.
  </Step>

  <Step title="Send the invite">
    Click **Invite member**, enter their email address, and pick a role. Each role in the dropdown shows a short summary of what it grants. New invites default to **Member**.
  </Step>

  <Step title="They accept">
    They'll get an email with a join link. Pending invites appear in the members list, where you can change the role or revoke the invite.
  </Step>
</Steps>

## Approved email domains

Instead of inviting people one by one, you can let anyone with an email address at your company domain join the workspace. Set this up under **Settings → Workspace → General → Approved email domains**.

<Note>
  Approved email domains are available on the Business plan and above. See [Billing](/guides/billing).
</Note>

## Member limits

The Free plan includes 1 member; Team includes 5; Business and Enterprise are unlimited. If a downgrade puts you over the limit, existing members keep their access. You just can't add new ones until you're back under it.

## Remove a member

Open the member's row in **Settings → Workspace → Members** and choose **Delete workspace member**. Their releases stay in the workspace.


# Discord
Source: https://docs.onset.io/integrations/discord

Get notified in Discord channels when new releases are published.

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Connect** next to **Discord**.
  </Step>

  <Step title="Authorize Onset app">
    Authorize Onset to access your Discord server.
  </Step>
</Steps>

## How to use

When publishing a new release, you'll see an option to send a notification to the Discord server you connected. Select a channel and publish. Onset will post the release update automatically.


# Fathom
Source: https://docs.onset.io/integrations/fathom

Track page views on your release notes with simple, privacy-first analytics from Fathom.

## Required Field

<ParamField type="string">
  The Site ID from your Fathom dashboard (e.g. ABCDEFG).
</ParamField>

## Optional Field

<ParamField type="string">
  Set this only if you serve the script from a Fathom custom domain. Leave blank to use `cdn.usefathom.com`.
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Configure** next to **Fathom**.
  </Step>

  <Step title="Fill out your details">
    Enter your **Site ID** and, if needed, a custom **Script host**.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to enable the integration.
  </Step>
</Steps>

## How it works

Once connected, Onset loads the Fathom tracking script on your public release notes so page views are recorded in your Fathom dashboard. Fathom is cookieless and privacy-first, so it does not require cookie consent before loading.


# GitHub
Source: https://docs.onset.io/integrations/github

Automatically create release notes from pull requests.

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Connect** next to **GitHub**.
  </Step>

  <Step title="Authorize Onset app">
    Authorize Onset to access your GitHub workspace.
  </Step>
</Steps>

## How to use

When you create a new release in Onset, it can automatically include summaries of these pull requests, making it easy to keep your customers informed about what's new.


# Google Analytics
Source: https://docs.onset.io/integrations/google-analytics

Measure release note engagement by tracking page views in your existing analytics.

## Required Field

<ParamField type="string">
  Your Google Analytics property ID (e.g. G-XXXXXXX).
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Configure** next to **Google Analytics**.
  </Step>

  <Step title="Fill out your details">
    Enter your **Tracking ID**.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to enable the integration.
  </Step>
</Steps>

## How it works

Once connected, Onset automatically sends page view events to your Google Analytics account whenever visitors view your public release notes.


# incident.io
Source: https://docs.onset.io/integrations/incidentio

Share live status and incidents from incident.io together with your product communications.

## Required Fields

<ParamField type="string">
  The full URL to your incident.io page.
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Configure** next to incident.io.
  </Step>

  <Step title="Fill out your details">
    Enter your **Page URL**.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to enable the integration.
  </Step>
</Steps>

## How it works

Onset embeds your incident.io system status directly into your public page so users can see reliability information alongside your product communications.


# Instatus
Source: https://docs.onset.io/integrations/instatus

Connect Instatus to keep customers informed of service reliability next to your updates.

## Required Field

<ParamField type="string">
  The public URL of your Instatus status page.
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Configure** next to **Instatus**.
  </Step>

  <Step title="Fill out your details">
    Enter your **Page URL**.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to connect your status page.
  </Step>
</Steps>

## How it works

When connected, your Instatus status indicators will appear alongside your release notes, allowing visitors to see current service health in real time.


# Jira
Source: https://docs.onset.io/integrations/jira

Automatically create release notes from Jira issues.

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Connect** next to **Jira**.
  </Step>

  <Step title="Authorize Onset app">
    Authorize Onset to access your Jira workspace.
  </Step>
</Steps>

## How to use

When you create a new release in Onset, it can automatically include summaries of these issues, making it easy to communicate what's changed to your audience.


# Linear
Source: https://docs.onset.io/integrations/linear

Automatically create release notes from Linear issues.

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Connect** next to **Linear**.
  </Step>

  <Step title="Authorize Onset app">
    Authorize Onset to access your Linear workspace.
  </Step>
</Steps>

## How to use

When you create a new release in Onset, it can automatically include summaries of these issues, making it easy to communicate what's changed to your audience.


# Plausible
Source: https://docs.onset.io/integrations/plausible

Track page views on your release notes with privacy-friendly, cookieless analytics.

## Required Field

<ParamField type="string">
  The domain you added in Plausible (e.g. updates.yourcompany.com).
</ParamField>

## Optional Field

<ParamField type="string">
  Set this only if you self-host or proxy Plausible. Leave blank to use `plausible.io`.
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Configure** next to **Plausible**.
  </Step>

  <Step title="Fill out your details">
    Enter your **Domain** and, if needed, a custom **Script host**.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to enable the integration.
  </Step>
</Steps>

## How it works

Once connected, Onset loads the Plausible tracking script on your public release notes so page views are recorded in your Plausible dashboard. Plausible is cookieless and privacy-friendly, so it does not require cookie consent before loading.


# Slack
Source: https://docs.onset.io/integrations/slack

Get notified in Slack channels when new releases are published.

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Connect** next to **Slack**.
  </Step>

  <Step title="Authorize Onset app">
    Authorize Onset to access your Slack workspace.
  </Step>
</Steps>

## How to use

When publishing a new release, you'll see an option to send a notification to the Slack workspace you connected. Select a channel and publish. Onset will post the release update automatically.


# Status.io
Source: https://docs.onset.io/integrations/statusio

Display system health and downtime from Status.io directly on your Onset page.

## Required Fields

<ParamField type="string">
  The unique identifier of your Status.io page.
</ParamField>

<ParamField type="string">
  The public URL of your Status.io page.
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Configure** next to **Status.io**.
  </Step>

  <Step title="Fill out your details">
    Enter your **Page ID** and **Page URL**.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to enable the integration.
  </Step>
</Steps>

## How it works:

Onset fetches live status data from your Status.io page and displays it near your release notes for better transparency with your users.


# Statuspage
Source: https://docs.onset.io/integrations/statuspage

Show real-time uptime and incidents from Statuspage alongside your product updates.

## Required Field

<ParamField type="string">
  The public URL of your Statuspage page.
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Configure** next to **Statuspage**.
  </Step>

  <Step title="Fill out your details">
    Enter your **Page URL**.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to connect the integration.
  </Step>
</Steps>

## How it works

After connecting, Onset automatically displays your current Statuspage component status and incidents next to your product updates.


# Statuspal
Source: https://docs.onset.io/integrations/statuspal

Share live status and incidents from StatusPal together with your product communications.

## Required Fields

<ParamField type="string">
  The subdomain of your Statuspal instance (e.g. yourcompany.statuspal.io).
</ParamField>

<ParamField type="string">
  The full URL to your Statuspal page.
</ParamField>

## How to enable

<Steps>
  <Step title="Navigate to Integrations page">
    Go to **Settings → Integrations** in your workspace.
  </Step>

  <Step title="Find your integration">
    Click **Configure** next to **Statuspal**.
  </Step>

  <Step title="Fill out your details">
    Enter your **Page Subdomain** and **Page URL**.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to enable the integration.
  </Step>
</Steps>

## How it works

Onset embeds your Statuspal system status directly into your public page so users can see reliability information alongside your product communications.


# Zapier
Source: https://docs.onset.io/integrations/zapier

Connect Onset to thousands of apps and automate your release workflow.

<Note>
  The Onset Zapier app is in beta. Zapier hasn't listed it publicly yet, so you
  need the invite link below to add it to your account.
</Note>

Zapier connects Onset to thousands of other tools without writing code. Announce
releases where your team already works, log them in a spreadsheet, or add
subscribers from the forms and CRMs you already use.

## How to enable

<Steps>
  <Step title="Create an API key">
    Go to **Settings → Developers → API Keys** in your workspace and create a
    key. Copy it — you'll only see it once.
  </Step>

  <Step title="Open the Onset Zapier app">
    Go to **Settings → Integrations** and click **Connect** on **Zapier**. That
    opens the [invite link](https://zapier.com/developer/public-invite/149791/7913ed05f71e7fa3e651a251c8749968/)
    that adds Onset to your Zapier account.
  </Step>

  <Step title="Sign in to Onset">
    When Zapier asks you to connect an Onset account, paste your API key. Zapier
    validates it against your workspace right away.
  </Step>
</Steps>

## Triggers

Triggers start a Zap when something happens in Onset. They run on
[webhooks](/developers/webhooks), so they fire within seconds instead of waiting
for a polling interval.

| Trigger          | Fires when                                                 |
| ---------------- | ---------------------------------------------------------- |
| New Release Note | A release is created in your workspace (`release.created`) |
| New Subscriber   | Someone subscribes to your updates (`subscriber.created`)  |

<Note>
  **New Release Note** fires on creation, not publication. A draft you're still
  writing will start the Zap, so add a filter step if you only want to act on
  releases that have gone live.
</Note>

## Actions

Actions let another app write into Onset.

| Action               | What it does                                          |
| -------------------- | ----------------------------------------------------- |
| Create Release Note  | Creates a release as a draft in your workspace        |
| Update Release Note  | Edits an existing release — title, body, or changes   |
| Publish Release Note | Publishes a draft, immediately or at a scheduled date |
| Create Subscriber    | Adds a subscriber, optionally to a specific list      |

<Warning>
  **Publish Release Note** doesn't send subscriber emails or Slack and Discord
  announcements — the same limitation applies to
  [publishing over the API](/developers/api-reference/introduction). Publish from
  the dashboard when you want to pick notification channels. See
  [Publishing](/guides/releases/publishing).
</Warning>

## Example Zaps

* **New Release Note → Slack/Teams/Discord.** Post an internal heads-up when a
  release is drafted, so the team can review before it ships.
* **New Release Note → Google Sheets.** Keep a running log of every release for
  reporting.
* **Typeform/HubSpot → Create Subscriber.** Add people to your changelog
  audience from wherever they sign up.
* **Jira/GitHub → Create Release Note.** Draft a release automatically when a
  version is cut, then edit and publish it in Onset.
* **Scheduled by Zapier → Publish Release Note.** Ship a prepared draft at a
  fixed time without anyone opening the dashboard.

## Working with your API key

The key you paste into Zapier has the same privileges as any other Onset API
key. Create a dedicated key for Zapier rather than reusing one, so you can
revoke it from **Settings → Developers → API Keys** without breaking your other
integrations.

If you'd rather build against Onset directly, the same data is available through
the [API](/developers/api-reference/introduction) and
[webhooks](/developers/webhooks).


# Custom Domains
Source: https://docs.onset.io/page/custom-domains



Your page is available through **onset.io** by default. Your URL will look like this: `yoursubdomain.onset.io`.

If you'd like to use a different URL, you can create one by setting up a **custom domain**.

### Enable custom domain

1. Go to **Settings -> Page -> Domain**
2. Under the **Domain**, enter your custom domain.\
   Example:\
   \- `releases.example.com`\
   \- `releasenotes.examples.com`

### Create a custom CNAME record

* Go to your **DNS** provider's website (e.g., [GoDaddy](https://ie.godaddy.com/help/add-a-cname-record-19236) or [Cloudflare](https://www.cloudflare.com/dns/)).
* Create a **CNAME** ("canonical name") record for your custom domain.
* Point it at Onset's custom host domain, `custom.onset.io`

### SSL Certificate

After you set up a custom domain, Onset will automatically issue a certificate and apply it to your domain. Please allow a few minutes for the SSL certificates to be issued and deployed before attempting to connect via your custom domain.


# Email Whitelisted Page
Source: https://docs.onset.io/page/privacy/email-whitelisted-page



Email whitelisting lets you restrict access to your public page so that only users with approved email domains can view it. When someone requests access, Onset verifies their email address and sends them a magic link to sign in.

<Steps>
  <Step title="Navigate to settings page">
    Go to Settings → Page → Privacy
  </Step>

  <Step title="Select privacy option">
    In the Page visibility dropdown, select Email Protected
  </Step>

  <Step title="Enter your domain">
    Under Allowed email domains, enter one or more domains you want to allow (for example: onset.io, company.com)
  </Step>
</Steps>

Only users with email addresses from the listed domains will be able to access your page.

<Warning>
  Do not add public email providers (such as [gmail.com](http://gmail.com), [outlook.com](http://outlook.com), or [yahoo.com](http://yahoo.com)). Doing so would make your page accessible to anyone using those domains.
</Warning>


# Password Protected
Source: https://docs.onset.io/page/privacy/password-protected



You can restrict access to your public page by requiring visitors to enter a password before viewing it. This is a simple way to keep your content private while still sharing it with selected users.

<Steps>
  <Step title="Navigate to settings page">
    Go to Settings → Page → Privacy
  </Step>

  <Step title="Select privacy option">
    In the Page visibility dropdown, select Password Protected
  </Step>

  <Step title="Enter your password">
    Under Password, enter a password of your choice
  </Step>
</Steps>

Anyone visiting your page will need to enter this password to gain access.

<Warning>
  You'll need to share this password with others, so be sure not to use anything
  sensitive to **you**.
</Warning>