annotated
Sign in

Annotated for agents · API + MCP

Ask for the moment. Get back the evidence.

“Find where Jason talks about cool hunting” becomes an exact timestamp, a rights-gated clip, and a receipt another agent—or person—can inspect.

Open agent workspace Read the protocol

Finding is not permission. Capturing is not publishing. Each boundary is a separate call.

Example Agent request / 0042Awaiting person
Tool
find_moments
Source
youtube.com / episode
Request
Jason on cool hunting
Candidate 0100:34:12 — 00:34:48

Verbatim transcript window is returned to the authorized client, with its transcript and source fingerprints.

Next: person reviews in trusted browser
Browser-capture example → receipt

One request, four inspectable outputs.

This static browser_capture trace uses the example above. It shows the contract without starting a job or implying a live result. Authorized remote capture has a different, explicitly delegated boundary documented below.

  1. 01
    find_moments

    Candidate 00:34:12–00:34:48

    Input: the Jason episode and “cool hunting.” Output: a ranked verbatim window with source and transcript fingerprints.

  2. 02
    prepare_clip

    Clip intent · expires in 30 min

    The intent fixes the source, range, and allowed capture path. It does not capture media or assert sharing rights.

  3. 03
    create_clip

    Fresh browser confirmation

    On this browser_capture path, a person opens the matching source, reviews the range, checks the rights box for this clip, and decides whether to record.

  4. 04
    get_receipt

    SHA-256 · browser_capture

    The receipt binds source URL, timing, method, and artifact fingerprint. It records provenance, not truth.

01

MCP transport

Point an MCP client at the hosted endpoint and send an Annotated API key as a bearer credential.

URL           https://annotated-source-clips.vercel.app/mcp
Authorization Bearer ant_sk_••••••••••••
Transport     Streamable HTTP

Create a narrow key in Agent workspace. Never paste it into a prompt.

02

API request

Every mutation accepts an idempotency key. Long operations return a job instead of holding the connection open.

POST /api/v1/agent/moment-searches
Authorization: Bearer ant_sk_••••••••••••
Idempotency-Key: 6e06d1bb-••••-••••-••••-a5e19283d10a
Content-Type: application/json

{
  "sourceId": "src_••••••••",
  "query": "Jason on cool hunting",
  "maxResults": 4
}
03

Available tools

Read operations are separated from actions that create, capture, or publish.

find_moments

Source + natural language → ranked, timestamped candidates

inspect_moment

Read the verbatim window and provenance before acting

find_counterevidence

Search the same source for a meaningful challenge or qualification

prepare_clip

Create an expiring intent without capturing anything

create_clip

Browser: stop for a person · Remote: require delegated key-holder attestation · Upload: await user media

get_job

Poll a durable async job without replaying the mutation

get_moment_search

Retrieve the grounded candidates after an async search succeeds

get_clip

Inspect a completed clip and its receipt link without loading media into agent context

get_receipt

Retrieve the artifact’s inspectable provenance record

publish_annotation

Publish only after a separate publication grant

04

What crosses each boundary

The receipt exposes provenance fields; private request material stays account-scoped.

  • Excluded from public receipts

    Search queries, full transcripts, capabilities, source handles, and worker diagnostics remain private.

  • Browser capture · fresh human confirmation

    A signed-in owner accepts the one-time handoff, reviews the exact range, checks the extension's per-clip rights box, records visibly, and sends separately.

  • Authorized remote · delegated key-holder attestation

    Use authorized_remote only when deliberately registering a directly fetchable media URL. Registration records that declaration; the worker validates the fetch, redirects, MIME, size, and duration before creating any artifact. The clips:write API-key holder attests authorization for that exact intent; this is the final capture authorization and no browser confirmation follows.

  • Upload · still awaiting_user

    The API does not fetch or synthesize upload-mode media. The job stays awaiting_user until the required user-media step is completed.

  • Included in receipts

    Source URL, timestamps, capture method, artifact fingerprint, and recorded rights basis are inspectable.

  • Not independently certified

    A fingerprint proves file identity; browser confirmations, delegated attestations, recorded rights bases, and the underlying claim remain caller assertions.

Agent-ready citations

Let the model find it. Keep the person in charge of sharing it.

Open your workspace