Changelog

Material changes to the NU Signal Partners API. The version is fixed in the path (/v1); entries track revisions to openapi/partner-api.yaml.

0.6.0

  • Secure application claim — new applications return a reference and one-time status token. After approval, partners atomically claim one 72-hour bootstrap token. Public applications require explicit privacy consent.
  • Commercial-terms agreement axis — usage type, MG/RS, flat, API and data-license fees, scope, and contract snapshots are fixed on each deal; settlements consume those terms directly.
  • Read-only Partner Portal — signed sessions that never store the raw API key expose catalog, deals, and Production settlements.
  • Stronger environment isolation — financial settlement APIs require Production keys; Sandbox calls return production_key_required.

0.5.0

  • Type-safe JS/TS SDK — packages/sdk-js provides concrete request and response types for every Partner API route, including public application and first-key bootstrap. Parity tests block missing or stale SDK methods.
  • Precise OpenAPI response contracts — success/error envelopes and required/nullable definitions now match actual responses; agreement and settlement details consistently include an updated_at watermark.
  • Session-revocation consistency — active sessions return revoked; ended sessions keep their real final state. allowed_ips applies only to token issuance, not the viewer’s media IP.
  • Refund sign normalization — REFUND.revenue_amount is always normalized negative in the ledger and consistently subtracts from settlement net revenue.

0.4.0

  • Hosted webview playback — POST /playback/tokens now returns hosted webview_url alongside manifest. Open it in a WebView or iframe with no player integration; both are bound to one session (Playback API).
  • Viewer preferences — optional non-PII preferences personalize the webview and are stored on the session (returned by GET /playback/sessions/{id}). The schema is strict; values containing @ or spaces are rejected with validation_failed (422).
  • Public application deduplication — resubmitting POST /partner-applications with the same contact email within 24 hours returns the existing application with 200 and deduped: true, without creating a new row.

0.3.0

  • Stronger integrity guards — known Prisma errors map to clean 4xx responses: P2002 → conflict (409), P2003 → validation_failed, and P2025 → resource_not_found (Error codes).
  • Request-size caps — event payloads are limited to 4 KB and request string fields have explicit length limits.
  • Public-route rate limits — unauthenticated POST /partner-applications and POST /v1/api-keys/bootstrap are limited to 20/min per client IP.
  • Idempotency conflicts — retrying an in-progress X-NU-Request-Id for playback-token or license-request creation returns conflict (409) instead of a duplicate write. Completed requests replay their original response.

0.2.0

  • Standard error envelope — every error returns { "error": { code, message, request_id, details? } } with a fixed code set (Error codes).
  • Request headers — formalized Authorization, X-NU-Partner-Id, and optional X-NU-Request-Id (Authentication).
  • Event taxonomy — canonical EventType values from which settlement eligibility is derived (Event API).
  • Settlement disputes and adjustments — POST /settlements/{id}/dispute plus expanded settlement fee and share fields (Settlement API).
  • Cursor pagination — list endpoints accept cursor and return next_cursor alongside page/limit (Catalog API).

0.1.0 — Initial Sandbox API

Initial MVP scaffold: catalog, licensing, playback, and event APIs targeting an isolated Sandbox environment.