Skip to content
Open Podcast API

Add a new subscription

POST
/v1/subscriptions

Enables clients to add a new subscription to the system and register the authenticated user as a subscriber.

The operation is idempotent. If the subscription already exists, the server MAY return a 200 OK.

Request Body required

Section titled “Request Body required ”
object
data
required
object
type
required
string
Allowed values: subscription
Example
subscription
id
required

UUIDv5 identifying the feed.

string format: uuid
Example
ce510f4d-9046-5590-846e-58619ab8b353
attributes
required
object
feedUrl
required
string format: uri
Example
https://example.com/rss1

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Subscription already existed; confirmed.

object
jsonapi
object
version
string
Example
1.1
data
object
type
required
string
Allowed values: subscription
id
required
string format: uuid
Example
ce510f4d-9046-5590-846e-58619ab8b353
attributes
required
object
feedUrl
string format: uri
Example
https://example.com/rss1
userSubscribedAt
string format: date-time
Example
2025-08-24T16:00:00Z
links
required
object
self
required
string
Example
/v1/subscriptions/ce510f4d-9046-5590-846e-58619ab8b353
unsubscribe
required
object
href
required
string
Example
/v1/subscriptions/ce510f4d-9046-5590-846e-58619ab8b353
method
required
string
Allowed values: DELETE
Example
DELETE
Example
{
  "jsonapi": {
    "version": "1.1"
  },
  "data": {
    "type": "subscription",
    "id": "ce510f4d-9046-5590-846e-58619ab8b353",
    "attributes": {
      "feedUrl": "https://example.com/rss1",
      "userSubscribedAt": "2025-08-24T16:00:00Z"
    },
    "links": {
      "self": "/v1/subscriptions/ce510f4d-9046-5590-846e-58619ab8b353",
      "unsubscribe": {
        "href": "/v1/subscriptions/ce510f4d-9046-5590-846e-58619ab8b353",
        "method": "DELETE"
      }
    }
  }
}

201

Section titled “201 ”

Subscription successfully created.

object
jsonapi
object
version
string
Example
1.1
data
object
type
required
string
Allowed values: subscription
id
required
string format: uuid
Example
ce510f4d-9046-5590-846e-58619ab8b353
attributes
required
object
feedUrl
string format: uri
Example
https://example.com/rss1
userSubscribedAt
string format: date-time
Example
2025-08-24T16:00:00Z
links
required
object
self
required
string
Example
/v1/subscriptions/ce510f4d-9046-5590-846e-58619ab8b353
unsubscribe
required
object
href
required
string
Example
/v1/subscriptions/ce510f4d-9046-5590-846e-58619ab8b353
method
required
string
Allowed values: DELETE
Example
DELETE
Example
{
  "jsonapi": {
    "version": "1.1"
  },
  "data": {
    "type": "subscription",
    "id": "ce510f4d-9046-5590-846e-58619ab8b353",
    "attributes": {
      "feedUrl": "https://example.com/rss1",
      "userSubscribedAt": "2025-08-24T16:00:00Z"
    },
    "links": {
      "self": "/v1/subscriptions/ce510f4d-9046-5590-846e-58619ab8b353",
      "unsubscribe": {
        "href": "/v1/subscriptions/ce510f4d-9046-5590-846e-58619ab8b353",
        "method": "DELETE"
      }
    }
  }
}

Headers

Section titled “Headers ”
Location
string

URI of the created resource