API reference · v1

The Norsolia API

A JSON API for shows, episodes, feeds and stats. This page is generated from the same OpenAPI document the server returns at /api/v1/openapi.json.

Basics

  • Base URL: https://api.norsolia.com in the Core region. Each region is independent, with its own accounts and data.
  • Auth: send Authorization: Bearer <token>, or sign in and use the session cookie (then add X-CSRF-Token on writes).
  • Errors: one shape everywhere — {"error":{"code","message"},"request_id"} — plus an X-Request-Id header.
  • Unknown paths under /api/ return 404 as JSON, including unknown versions. The retired /api/v0/ returns 410 Gone.

A first call

curl -X POST https://api.norsolia.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"a-long-passphrase","name":"Your name"}'

curl https://api.norsolia.com/api/v1/shows \
  -H "Authorization: Bearer nk_live_..."

Endpoints

Auth

POST /api/v1/auth/register
Create an account (public)
POST /api/v1/auth/login
Sign in (public)
POST /api/v1/auth/logout
Sign out (token or session)

Account

GET /api/v1/me
Current account (token or session)
PATCH /api/v1/me
Update profile (token or session)
DELETE /api/v1/me
Delete account (token or session)
POST /api/v1/me/password
Change password (token or session)
GET /api/v1/sessions
Active sessions (token or session)
DELETE /api/v1/sessions/{id}
End a session (token or session)
GET /api/v1/migration
Read migration checklist (token or session)
PUT /api/v1/migration
Save migration checklist (token or session)
GET /api/v1/export
Export all data (token or session)
POST /api/v1/waitlist
Join a plan waitlist (public)
POST /api/v1/contact
Send a message (public)

Tokens

GET /api/v1/tokens
List API tokens (token or session)
POST /api/v1/tokens
Create an API token (token or session)
DELETE /api/v1/tokens/{id}
Revoke a token (token or session)

Shows

GET /api/v1/shows
List your shows (token or session)
POST /api/v1/shows
Create a show (token or session)
GET /api/v1/shows/{slug}
Get a show (public)
PATCH /api/v1/shows/{slug}
Update a show (token or session)
DELETE /api/v1/shows/{slug}
Delete a show (token or session)
PUT /api/v1/shows/{slug}/cover
Upload a show cover (token or session)

Episodes

GET /api/v1/shows/{slug}/episodes
List episodes (public)
POST /api/v1/shows/{slug}/episodes
Create an episode (metadata) (token or session)
GET /api/v1/episodes/{id}
Get an episode (public)
PATCH /api/v1/episodes/{id}
Update an episode (token or session)
DELETE /api/v1/episodes/{id}
Delete an episode (token or session)
PUT /api/v1/episodes/{id}/audio
Upload episode audio (token or session)
GET /api/v1/episodes/{id}/stats
Episode play stats (token or session)
GET /api/v1/episodes/{id}/chapters
Episode chapters (public)

Status

GET /health
Service health (public)
GET /api/v1/health
Service health (public)
GET /api/v1/status
Public status (public)
GET /api/v1/openapi.json
This specification (public)