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.
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.
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.
Stable fields
Shared response envelope
{
"success": true,
"id": "resource_public_id",
"message": null,
"data": { "...": "route-specific payload" },
"token_stats": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 },
"pricing": { "total_cost": 0.0 },
"error": null
}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.
Assume every create route can become a later retrieval or follow-up step
A durable integration does not stop at the first generated payload. Store the public id, keep the shared usage fields, and decide how your product will list, fetch, or continue the resource later.
That is especially important for roadmaps, quizzes, exams, and projects because the first generation call is often only the first step in the user workflow.