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.

It also provides scoped push relay channels for public Marten Server Simple deployments, keeping Firebase credentials exclusively on this central service. The push never contains a subscription URL, configuration, or credentials.

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.
`POST /v1/relay/channels`	Public	Create a scoped channel for a Simple server.
`PUT / DELETE /v1/relay/channels/{id}/devices/{registrationID}`	Bearer relay token	Upsert or remove an opaque relayed device registration.
`POST /v1/relay/channels/{id}/push`	Bearer relay token	Queue a refresh for one relay channel.
`GET /v1/relay/channels/{id}/push-jobs/{jobID}`	Bearer relay token	Read aggregate status for a job in the same channel.
`DELETE /v1/relay/channels/{id}`	Bearer relay token	Delete the scoped relay channel.

Authentication and limits

Owner requests: Authorization: Bearer <owner token>.
Simple relay requests use a separate channel-scoped bearer token.
Creation: up to 5 requests per source IP per hour.
Relay channel creation: up to 60 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.