API v1 · operational

Marten Subscription Push API

This service connects an existing HTTPS subscription to Marten devices and lets its owner send a data-only silent push requesting a refresh.

The push is only a signal: it never contains the subscription URL, configuration, or credentials. The service does not download or proxy subscription content.

Quick start

Create a subscription channel. The response contains a public install URL and a one-time owner token. Store the token securely.

curl https://api.app.marten.pw/v1/subscriptions \
  -H 'Content-Type: application/json' \
  -d '{"name":"My subscription","url":"https://example.com/sub/token"}'

Request types

Request	Access	Purpose
`POST /v1/subscriptions`	Public	Create a channel and receive its install URL and owner token.
`GET /v1/subscriptions/{id}`	Bearer owner token	Read channel metadata.
`PATCH /v1/subscriptions/{id}`	Bearer owner token	Replace the name or source URL.
`DELETE /v1/subscriptions/{id}`	Bearer owner token	Delete the channel and its registrations.
`POST /v1/subscriptions/{id}/push`	Bearer owner token	Queue a silent refresh push.
`GET /v1/subscriptions/{id}/push-jobs/{jobID}`	Bearer owner token	Read the aggregate push job result.
`POST /v1/subscriptions/{id}/owner-token/rotate`	Bearer owner token	Replace the owner credential.
`POST / DELETE /v1/subscriptions/{id}/devices/push-token`	Device headers	Register or remove a device push token.
`GET /install/{id}`	Public	Open the Marten import link.
`GET /healthz`	Public	Check API availability.

Authentication and limits

Owner requests: Authorization: Bearer <owner token>.
Creation: up to 5 requests per source IP per hour.
Push trigger: one request per subscription every 30 seconds, up to 100 per day.
Rate-limited requests receive 429 with a Retry-After header.