PlayNotes API

{
  "email": string,         // required
  "device": string        // optional, default "api" — "ios" | "mac" | "api"
}

{
  "message": "Code sent"
}

429 — Rate limited (1 request per 2 min per email/device)

{
  "email": string,         // required
  "code": string,          // required — 6-digit code
  "device": string        // optional, default "api" — must match the request call
}

{
  "api_key": string,       // "po_..." — save this
  "created": boolean      // true if a new account was created
}

401 — Invalid code or too many attempts (max 5)
404 — No pending code — request a new one

{
  "api_key": string       // new key
}

{
  "revoked": integer      // number of keys revoked
}

{
  "id": string,
  "email": string,
  "settings": {
    "email_transcripts": boolean | null
  },
  "created_at": string,    // ISO 8601
  "active_keys": [
    {
      "id": string,
      "name": string,       // e.g. "ios-26-04-02-15-30-00"
      "created_at": string
    }
  ]
}

{
  "email_transcripts": boolean  // optional
}

{
  "email_transcripts": boolean | null
}

audio: file               // required — M4A, WAV, MP3, FLAC, OGG
source: string             // required — "mac_system" | "mac_mic" | "ios_mic"
recorded_at: string        // required — ISO 8601 datetime
timezone: string           // required — IANA timezone
idempotency_key: string   // required — UUID, unique per user
duration_seconds: float   // optional

{
  "recording_id": string,
  "status": "queued",
  "source": string,
  "duration_seconds": float | null,
  "timezone": string,
  "recorded_at": string,
  "created_at": string,
  "title": null,
  "description": null
}

200 — Idempotent hit (same idempotency_key returns cached result)
413 — File too large (max 500MB)
422 — Invalid source or audio format

source: string             // required — "mac_system" | "mac_mic" | "ios_mic"
recorded_at: string        // required — ISO 8601
timezone: string           // required — IANA timezone
idempotency_key: string   // required — UUID

{
  "recording_id": string,
  "status": "uploading",
  ...                        // same shape as upload response
}

index: integer            // required — chunk sequence number
file: file                // required — audio/mp4

{}

409 — Recording not in "uploading" status
413 — Chunk too large (max 50MB)

confirmed_chunks: integer // required — number of chunks uploaded
duration_seconds: float   // required — total duration

{
  "recording_id": string,
  "status": "queued",
  ...
}

cursor: string            // optional — pagination cursor from previous response
limit: integer            // optional, default 20, max 100
status: string            // optional — filter by status
speaker_id: string        // optional — filter recordings containing speaker

{
  "recordings": [
    {
      "id": string,
      "status": string,
      "source": string,
      "duration_seconds": float | null,
      "timezone": string,
      "recorded_at": string,
      "created_at": string,
      "title": string | null,
      "description": string | null
    }
  ],
  "next_cursor": string | null
}

{
  "id": string,
  "status": string,
  "source": string,
  "duration_seconds": float | null,
  "timezone": string,
  "recorded_at": string,
  "created_at": string,
  "title": string | null,
  "description": string | null,
  "transcript": [
    {
      "speaker_id": string | null,
      "speaker_name": string | null,
      "start": float,          // seconds
      "end": float,            // seconds
      "text": string
    }
  ]
}

format: string            // optional, default "json" — "json" | "text"

{
  "transcript": [ ... ]    // same shape as above
}

[0] Speaker 1: First segment text
[1] Speaker 2: Second segment text

409 — Recording not in "uploading" status

[
  {
    "id": string,
    "name": string | null,
    "name_is_user_set": boolean,
    "sample_count": integer,
    "created_at": string
  }
]

{
  "id": string,
  "name": string | null,
  "name_is_user_set": boolean,
  "sample_count": integer,
  "created_at": string,
  "recording_count": integer,
  "recording_ids": [string]
}

{
  "name": string           // required
}

{
  "share_url": string       // public URL
}

{
  "share_url": string
}

404 — No active share link

{
  "recorded_at": string,    // local timezone
  "duration_seconds": float | null,
  "timezone": string,
  "transcript": [
    {
      "speaker_id": string | null,
      "speaker_name": string | null,
      "start": float,
      "end": float,
      "text": string
    }
  ]
}

{
  "url": string            // required — https:// URL, no private/loopback
}

{
  "id": string,
  "url": string,
  "secret": string         // only returned on creation — save this
}

{
  "id": string,
  "url": string,
  "created_at": string
}
// or null if no webhook configured

[
  {
    "id": string,
    "recording_id": string | null,
    "event": string,
    "status": string,          // "pending" | "delivered" | "failed"
    "attempts": integer,
    "last_attempted_at": string | null
  }
]

event: recording.complete
data: {"recording_id": "rec_..."}

event: recording.empty
data: {"recording_id": "rec_..."}

event: recording.failed
data: {"recording_id": "rec_..."}

{
  "balance_cents": integer,
  "auto_topup_enabled": boolean,
  "auto_topup_threshold_cents": integer | null,
  "auto_topup_amount_cents": integer | null
}

{
  "amount_cents": integer  // required — min 399
}

{
  "checkout_url": string  // Stripe Checkout URL — redirect user here
}

{
  "enabled": boolean,               // required
  "threshold_cents": integer,       // required if enabled — min 100
  "amount_cents": integer          // required if enabled — min 399
}

{
  "auto_topup_enabled": boolean,
  "auto_topup_threshold_cents": integer | null,
  "auto_topup_amount_cents": integer | null
}

cursor: string            // optional
limit: integer            // optional, default 20, max 100

{
  "transactions": [
    {
      "id": string,
      "amount_cents": integer,
      "balance_after_cents": integer,
      "type": string,           // "purchase" | "usage" | "admin_grant" | "auto_topup"
      "recording_id": string | null,
      "description": string | null,
      "created_at": string
    }
  ],
  "next_cursor": string | null
}