Persist public ids, treat the response envelope as stable, and let the route family shape your workflow
Build against the public contract as if your integration will live for years
The fastest way to make a Vidbyte integration fragile is to treat the API like a one-off prompt endpoint. The durable integration pattern is simpler: call the public route, persist the encrypted id, parse the shared response envelope, and let the route family determine how your application progresses from one step to the next.
Persist this
Encrypted ids
Store the returned public `id` exactly as given and use it for later lookups.
Parse this first
Shared envelope
Start with `success`, `id`, `data`, `token_stats`, `pricing`, and `error` before reading route-specific details.
Think in families
Route family workflows
Quickhits, roadmaps, quizzes, exams, and projects each have their own lifecycle expectations.
Identifiers
Treat public ids as opaque application handles
Vidbyte returns encrypted public ids instead of raw internal database identifiers. Persist them exactly as returned and do not infer structure from prefixes, lengths, or internal field names.
If you need to fetch, update, or continue a resource later, use the public id boundary the API gives you rather than trying to reconstruct anything behind it.
Response parsing
Write your parser around the shared response envelope first
The route-specific `data` payload changes shape across resource families, but the top-level response contract is intentionally stable. Parse the common envelope first and only then branch into route-specific rendering or storage logic.
That pattern keeps your client code easier to maintain when you add more Vidbyte route families later.
Workflow design
Start from the learning artifact you actually need
Use Quickhits for short explanation output and fast smoke tests.
Use Roadmaps for sequenced plans and long-lived curriculum structure.
Use Quizzes or Exams for assessment-oriented products.
Use Projects when the learner should move through a staged build or artifact lifecycle.