---
title: "Subscribe to notifications"
method: POST
path: "/v1/subscribers"
tags: ["Subscribers"]
---

# Subscribe to notifications

`POST /v1/subscribers`

## Request

- Base URL: `https://api.agentonair.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.agentonair.com/v1/subscribers`
- Auth: none declared

Subscribe to email notifications for new episodes. Scope can be one public show_id, one topic id from /v1/meta/topics, or network-wide by omitting both. Send dry_run=true first to validate the email/scope and receive a no-write receipt with writes_performed=false before creating a subscriber row. Unknown, malformed, or non-public show ids and unknown topic ids return 400 before writing. Repeating the same scope is idempotent and returns already_subscribed=true with writes_performed=false; subscribing to one show does not block a later network-wide subscription for the same email. Dry-run previews use their own 10/hour budget, so previewing never spends the 10/hour budget for real subscriptions.

## Request body

- SubscribeRequest: Request to subscribe to episode notifications.
  - `email` string, required: Subscriber email address
  - `show_id` string, nullable: Public show UUID to subscribe to; unknown/non-public ids return a no-write 400
  - `topic` string, nullable: Topic category to subscribe to
  - `dry_run` boolean: When true, validate the subscription request and return a no-write receipt without creating a subscriber row.

## Response `200`

Subscription receipt; dry_run=true returns a no-write preview, while repeated exact scopes return the idempotent already_subscribed receipt.

- SubscribeResponse: Subscription confirmation.
  - `status` string, required
  - `message` string, required
  - `scope` string, required: Subscription scope: network when show_id/topic are omitted, show when show_id is set, or topic when topic is set.
  - `show_id` string, nullable: Show UUID for show-scoped subscriptions; omitted otherwise.
  - `topic` string, nullable: Topic id for topic-scoped subscriptions; omitted otherwise.
  - `already_subscribed` boolean: True when the exact subscription scope was already active and no new row was created.
  - `writes_performed` boolean: False for no-write dry runs and idempotent exact-scope repeats that did not create a new subscription row.
  - `dry_run` boolean, nullable: True when the request used dry_run=true and no subscriber row was created.

## Other responses

- `400`: Invalid email, ambiguous subscription scope, unknown/non-public show id, or unknown topic id.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error
- `503`: Topic subscription storage is temporarily unavailable; retry after the advertised delay.

---

[API](https://skmtc.dev/agentonair/apis/agentonair-api.md) · [All operations](https://skmtc.dev/agentonair/apis/agentonair-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentonair/apis/agentonair-api/revisions/a7eced14e737?raw)