Vucos Logo

API-First Integrations

Every capability on the platform is a contract — REST, GraphQL, and webhooks — published first as an OpenAPI specification and distributed as typed SDKs. Your engineering team integrates Vucos the same way they integrate Stripe or Twilio.

400+
Public REST endpoints across the platform
99.95%
API availability SLO
6
First-party SDK languages
12 mo
Minimum deprecation overlap window

The Platform Is the API

Vucos is built API-first, which means every screen in the operator console and every action in the consumer app is backed by a public, documented endpoint. There is no hidden internal API surface, no data that can only be reached through the UI. REST endpoints cover the bulk of integration work, GraphQL exposes flexible query composition for catalog and analytics, and a webhook event stream pushes state changes in real time. Everything is versioned, rate-limited, and observable.

Why this matters

OTT platforms sold as black boxes become liabilities the moment the business needs something the vendor roadmap does not include. Every custom flow — a unique onboarding, a carrier billing integration, a loyalty program, a partner portal — either waits for the vendor or gets wired around the platform with brittle scraping and polling. Those shortcuts accumulate, and in 18 months the integration debt exceeds the license cost.

An API-first platform inverts that dynamic. Because the same endpoints Vucos uses internally are exposed externally, nothing the product does is out of reach. Operator engineering teams ship features in days rather than quarters, partners plug in through the same contract, and the platform keeps working when the business case changes shape.

What the API surface covers

REST APIs

Resource-oriented REST for content, subscribers, entitlements, billing, and operations. Consistent pagination, filtering, and error contracts across every endpoint.

GraphQL gateway

Single GraphQL endpoint that composes catalog, user, and analytics graphs. Clients fetch exactly the fields they need, with persisted queries and field-level authorization.

Webhook event stream

Signed, retryable webhooks for subscription events, playback lifecycle, content state, and billing transitions. At-least-once delivery with exponential backoff and a replay API.

OpenAPI-first spec

Every REST endpoint is defined in OpenAPI 3.1 before it ships. The same spec drives server stubs, client SDKs, and the interactive documentation portal — no drift between code and docs.

Typed SDKs

First-party SDKs for TypeScript, Python, Go, Java, Kotlin, and Swift, generated from the spec. Typed responses, built-in retry and auth, and end-to-end trace propagation.

Rate limiting & versioning

Per-tenant rate limits with burst allowance, response headers exposing remaining quota, explicit API versioning, and deprecation policies with a minimum 12-month overlap.

How operators use it

Telco operator

Carrier billing integration

Subscription purchase, upgrade, and cancellation flow through the operator's mobile app, which posts to Vucos billing APIs while charging via the carrier BSS. Webhook events reconcile state when the carrier confirms the transaction.

Content studio

Automated content delivery pipeline

The studio's MAM pushes finished masters and metadata to Vucos via REST, which triggers transcoding, DRM packaging, and publication. Status webhooks feed back into the studio dashboard so producers see go-live status without logging into the Vucos console.

Loyalty partner

Reward redemption & entitlement grants

A travel rewards platform calls the Vucos entitlement API to grant free months of SVOD access when members hit milestones. The same webhook stream reports activation and usage back so the loyalty program can score engagement.

Technical details

API styles
  • REST (JSON:API flavored)
  • GraphQL gateway
  • Webhook event stream
  • gRPC for high-throughput internal
Specification
  • OpenAPI 3.1
  • GraphQL schema with directives
  • AsyncAPI for webhooks
  • JSON Schema for payloads
SDKs
  • TypeScript / JavaScript
  • Python
  • Go
  • Java
  • Kotlin
  • Swift
Auth
  • OAuth 2.1 with PKCE
  • Machine-to-machine JWTs
  • API keys for partner integrations
  • Fine-grained scopes
Rate & versioning
  • Per-tenant token bucket
  • Burst + sustained limits
  • Semantic API versioning
  • 12-month deprecation overlap
Reliability
  • 99.95% API SLO
  • Regional read replicas
  • Idempotency keys on writes
  • Async job queue for long tasks

Key Takeaways

  • OpenAPI 3.1 specification published before every endpoint ships
  • REST for operations, GraphQL for composition, webhooks for events
  • Typed SDKs for TypeScript, Python, Go, Java, Kotlin, and Swift
  • Signed, retryable webhooks with at-least-once delivery and a replay API
  • Per-tenant rate limits with headers exposing remaining quota
  • Async job queue for long-running operations with status polling

Frequently Asked Questions

How stable are the APIs — will they change under us?
Stable by design. Every API is semantically versioned; breaking changes ship as a new version with a minimum 12-month overlap window where both versions run in parallel. Non-breaking additions (new fields, new optional parameters) happen continuously without a version bump. Deprecation is communicated through response headers, the changelog, and direct developer contact.
REST or GraphQL — which should we use?
Both are available for most domains. Use REST for transactional operations (create subscription, issue entitlement, start transcode) where clear verbs and idempotency matter. Use GraphQL for read-heavy UI composition (rendering a catalog screen with partial fields from 5 resources) where over-fetching would hurt. The SDKs expose both.
How do webhooks handle failures?
Every webhook is signed with a rotating secret and retried with exponential backoff for up to 72 hours. If delivery keeps failing, events sit in a dead-letter queue and are replayable through a first-class API — you can ask Vucos to redeliver any event from the last 30 days by ID or by time range, useful after a receiver outage.
What's the rate limit posture?
Default per-tenant limits are generous — typical integrations never see them. Limits are published in response headers (X-RateLimit-Remaining, X-RateLimit-Reset), and enterprise tenants can negotiate higher ceilings or dedicated capacity. Critical endpoints (playback entitlement, DRM license issuance) have separate, higher-priority quotas.
Can we sandbox against a non-production instance?
Yes. Every tenant gets a sandbox environment that mirrors the production API surface with test data and test billing flows. SDKs accept a base URL, so switching between sandbox and production is a configuration change, not a code fork.
How are long-running operations modeled?
Asynchronously. Operations like bulk transcoding, mass entitlement issuance, or catalog reindexing return a job ID immediately and expose a job status endpoint plus completion webhooks. This avoids long-held HTTP connections and keeps progress observable for hours-long workflows.

Related

Modular OTT Architecture

Buy the whole platform and it works on day one. Replace any piece with your own — billing, DRM, recommendations, analytics — and it keeps working. Modular by contract, composable in production.

Read more

Observability & Monitoring

Traces, metrics, and logs — correlated, queryable, and owned by you. The observability spine that turns a 3 AM incident into a 9-minute mean time to diagnose instead of a war-room hunt through five vendor consoles.

Read more

Whitelabel OTT Platform

One core engine for every part of your streaming business — subscribers, content, entitlements, billing, ads, and device apps — operated from a single admin console and driven by a consistent API across every region, tenant, and monetization model.

Read more

Ready to learn more?

Talk to an architect about how this fits your deployment.

Book a CallDownload Whitepaper