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, TikTok, and Instagram links to one video or post are also accepted; profile, channel, and playlist links are not. Google Drive URLs are not fetched; use an available Drive data connector. 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``), or they want to import from Google Drive, 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. When ``retriable`` is true, re-add the same input. Otherwise a re-add of the same URL won't change the result: correct a fixable URL problem (e.g. an expired link) first; an unsupported source or media that could not be retrieved (e.g. private/removed) needs a different source. 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 in the user's own account, or in an organization they belong to when ``organization`` is given. 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, 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

Grant one video on a saved page again. Invoked by the saved-page widget when the video's playback grant is about to expire.

jockey_refresh_artifact_media

List the metadata keys a search on one knowledge store can filter by, with each key's value types, operators, and an example value. Read it before setting a search's ``metadata_filter`` or ``enrichment_filter``: a value must match the key's stored type. A key carried by few items may be missing here and still filter. Required scopes: jockey:read.

jockey_list_filterable_fields

List items in a knowledge store, or fetch specific items by id. Each item comes with its backing asset's descriptive metadata under ``asset``: ``title``, ``duration_sec`` and ``size_bytes``, so you can answer 'what's in this store and how long is each item' from one call, with no per-item follow-up and no grounded query. Omit ``item_ids`` to page the store; pass ``item_ids`` to fetch just those items — use this to poll an item's status until it is ``ready``. After ``jockey_add_media``, pass its ``job_id`` as ``add_job_id`` to see each input's progress under ``add_job``, matched to the add result by ``job_position``. An input is ``added`` with its ``item_id`` as soon as it is in the store: poll those ids with ``item_ids`` until they are ``ready``. Poll the job until ``add_job.done``. Required scopes: jockey:read.

jockey_list_knowledge_store_items

List the knowledge stores the user can use, or fetch one by id. The list holds the user's own stores, stores shared with them, and the stores of every organization they belong to; each store's ``owner`` is ``personal`` or the organization's name, and its ``access`` is ``owned`` or ``shared``. When presenting the list, group stores by owner, and don't describe a shared store as the user's own. 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

List the user's saved pages, newest first, with each page's share_id and title. Use it when they want to see or reopen something they saved earlier, then pass the share_id to jockey_open_artifact. It does not show a page. Required scopes: jockey:read.

jockey_list_artifacts