Jockey by TwelveLabs

Add one or more videos/images to a knowledge store in a single call. Each item in ``items`` provides exactly one of: - ``source``: a media URL the platform fetches server-side — a direct-download link reachable from the public internet, up to 4 GB each. YouTube links are also accepted; the media is retrieved for you. Or - ``asset_id``: an asset you already hold (e.g. from a prior add), registered directly into this store, no re-upload. Plus optional ``asset_type`` (video/image) and ``metadata``. Prefer one batched call over many single-item calls. If the user's files are only on their own device (no public URL, no existing ``asset_id``), use ``jockey_request_upload_link`` instead. Each input is registered as a KS item (a ``source`` is first created as an asset, then waited on until it finishes processing) — reported per item via an ``outcome`` field (branch on it, not on ``error`` prose): - ``added``: registered (``item_id`` set; poll ``jockey_list_knowledge_store_items`` with ``item_ids`` until ``ready`` before querying). - ``asset_pending``: the asset is still being processed and is not yet registered (``asset_id`` set). Retry ``jockey_add_media`` with that ``asset_id`` after a short wait — an immediate retry may defer again while it is still processing. Expected deferral, not a failure. - ``registration_pending``: the asset reached ready and registration was attempted but did not resolve in time (``asset_id`` set). Retry ``jockey_add_media`` with that ``asset_id`` NOW — the asset is ready and re-registering is idempotent (usually succeeds immediately). Expected deferral, not a failure. - ``registration_failed``: registration rejected — see ``error_code`` / ``retriable``. - ``asset_failed``: the media failed processing (terminal). - ``rejected``: the source could not be turned into an asset — read ``error`` for which case. A fixable URL problem (e.g. an expired link) is worth correcting and re-adding; an unsupported source or media that could not be retrieved (e.g. private/removed) won't change on a re-add of the same URL. Each result echoes its ``input_index`` (0-based) and ``source`` (the URL or asset_id given) so every outcome ties back to the exact input. ``counts`` is the authoritative per-outcome tally and ``summary`` a one-line recap. One bad input does not fail the batch. Required scopes: jockey:read, jockey:write, jockey:ingest.

jockey_add_media

Ask a natural-language question and get a grounded answer with inline citations to the items and video clips it draws from. Use this when the client model must build an explicit downstream deliverable such as custom HTML or JSON, or when the user explicitly asks for text or prose only, even when that output cites playable media. Returns no interactive widget. For multi-turn, pass back the ``session_id`` from a prior response to continue; history is kept server-side per session, so you need not resend earlier turns. For quick, simple semantic visual or audio retrieval, or raw ranked match rows, use ``jockey_search``. If the answer is expected to reference specific clips, moments, or images and the user did not request an explicit downstream or text-only output, use ``jockey_render_response``.

jockey_query

Create a new Jockey knowledge store for the authenticated tenant. Accepts a ``name`` (human-readable label) and optional ``description`` and ``metadata``; the new KS starts empty. Follow up with ``jockey_add_media`` to add media (videos or images). Required scopes: jockey:read, jockey:write.

jockey_create_knowledge_store

Quickly retrieve ranked items and clips for a simple semantic visual or audio query. Each hit includes its item id and ``asset_type``. Use this for quick find or locate requests with no synthesized answer, or for raw ranked match rows to process yourself. This is retrieval only. For explicit text or prose-only output, or downstream custom HTML or JSON, use ``jockey_query``, even when that output cites playable media. ``caller_context`` optionally carries provenance (the end-user's original message, calling app/model) for analytics; it does not change results. Required scopes: jockey:read. For a synthesized answer expected to reference specific clips, moments, or images, use ``jockey_render_response``.

jockey_search

Get a web link the user can open to upload their own local files (e.g. photos and videos from a phone's camera roll or a computer) into a knowledge store. Use this when the files are on the user's own device and can't be reached by a public URL — and you don't already have an ``asset_id`` for them — so ``jockey_add_media`` can't take them. Returns an ``upload_url`` — present it to the user as a link to open. It opens directly to this knowledge store's upload page (nothing to pick); the user signs in with their TwelveLabs account and uploads there. Multiple files and large files are supported, and uploads are added to this knowledge store as items. The link is stable — calling again for the same store returns the same URL. This call only produces the link — it does not transfer any files itself, and this server never receives the bytes. After the user has uploaded, confirm by calling ``jockey_list_knowledge_store_items`` for this knowledge store and waiting for the new items to reach ``ready``. Required scopes: jockey:read, jockey:write, jockey:ingest.

jockey_request_upload_link

List items in a knowledge store, or fetch specific items by id. Each item comes pre-enriched with its backing asset's descriptive metadata under ``asset``: ``title``, ``duration_sec``, ``file_type``, ``size_bytes``, a preview ``thumbnail_url`` and a playable ``hls_url`` — so you can answer 'what's in this store, how long, what can I watch' from one call, with no per-item follow-up and no grounded query. (``asset`` is ``None`` only when it could not be resolved.) Omit ``item_ids`` to page the store; pass ``item_ids`` to fetch just those items — use this to poll an item's status after ``jockey_add_media`` until it is ``ready``. Required scopes: jockey:read.

jockey_list_knowledge_store_items

List knowledge stores for the authenticated tenant, or fetch one by id. Omit ``knowledge_store_id`` to page the list (``page`` 1-based, ``page_limit``) — use this to discover existing store ids before querying or adding media. Pass ``knowledge_store_id`` to fetch just that store (returned as a one-element list); add ``include_readiness=true`` to attach a per-status readiness summary (queued / pending / processing / ready / failed, plus total) so you can tell whether it is ready to query without listing its items. Required scopes: jockey:read.

jockey_list_knowledge_stores

Record a viewer's reaction to a rendered result: a thumbs up/down, an optional written comment, or a dismissal. Invoked by the result widget itself when the viewer interacts with its feedback prompt.

jockey_record_feedback

Answer a natural-language question as a native interactive visual for playback or browsing, such as a gallery, comparison, timeline, highlight reel, breakdown, or grouped view. PREFER THIS whenever the answer is expected to reference one or more specific clips, moments, or images. Show them here instead of only describing them in text. This covers ordinary show, play, browse, find, pull up, where does X happen, reel, montage, and gallery requests in any language, including Korean 보여줘 or 틀어줘. It also covers enumerations, summaries, and explanations that draw on specific media. HIGHER-PRIORITY EXCEPTION. Use ``jockey_query`` instead when the user explicitly requests text or prose only, or a downstream deliverable such as custom HTML or JSON, even when it cites playable media. For multi-turn, pass back the ``session_id`` from a prior response to continue. ``intent_hint`` / ``title`` / ``ks_name`` tune the rendered layout. Use ``jockey_search`` for quick, simple semantic visual or audio retrieval, or raw ranked match rows.

jockey_render_response