Extend
The Extend section groups the contracts you use to push your own data into the Hub — detections, classifications and other producer-side integrations that sit alongside the internal pipeline. Each one lets a producer you control contribute data to a recording without modifying the Hub itself.
Two ways to get data in
Every extension contract can be fed through one of two transports. They deliver the same data to the same place — they differ only in who triggers the work, where the producer runs, and which deployments can use them.
| API push (available now) | In-pipeline stage (advanced, deployment-gated) | |
|---|---|---|
| Transport | Authenticated POST to the Hub API | A worker container running as a stage of the internal analysis pipeline |
| Who triggers it | Your service, whenever it has data | The pipeline, automatically on ingest / re-analysis |
| Where it runs | Your own infrastructure, anywhere | Inside (or attached to) the Kerberos cluster |
| Delivery | Synchronous request/response | Queue-backed (retries, ordering, backpressure) |
| Availability | Any deployment (cloud or self-hosted) | Self-hosted deployments that can run custom stages |
| Best for | Bring-your-own models, offline/batch jobs, annotation imports, corrections | Always-on detection that must be part of every recording’s analysis |
For most integrators the API push is the right starting point: it works on every deployment, needs no cluster access, and lets you stand up your own producer immediately. The in-pipeline stage is an optimization for deployments that want a capability to run automatically as a built-in step.
The contract is the stable part
What makes the two transports interchangeable is that the data model is shared — the same typed run (e.g. a detection run) is defined once in @uug-ai/models and consumed by both paths. The transport is just the envelope. Because of this:
- The code that builds your output (boxes, tracks, classifications) is identical regardless of method.
- Switching a producer from API push to an in-pipeline stage later changes only the sink, not the payload.
- The Hub validates, normalises and stores every contribution the same way no matter how it arrived.
So when these pages describe a contract, they describe the data first; the transport is a delivery choice layered on top.
How these docs are organized
These pages are grouped by capability — what you are contributing — rather than by transport. Each capability page documents its data contract and notes which transports are available for it:
- Detections — third-party detection tracks (boxes per frame) for a recording, stored in the
detectionscollection. Available now via API push; in-pipeline stage planned.
New capabilities slot in as sibling pages here; the two transports above apply to each.
Choosing a method
- Start with API push if you’re bringing your own model, running offline or batch jobs, importing from an annotation tool, or operating on a managed/cloud deployment. It’s the universal door.
- Consider an in-pipeline stage only when you control the deployment and want the capability to run automatically as part of every recording’s analysis, with queue-level delivery guarantees.
- You don’t have to choose permanently: a deployment can use the API today and add an in-pipeline stage later as a second front door to the same collection.