Scanner quickstart

Find your first video moments in five steps.

This path uses a video find_moments scanner: the API route intended for clipping and highlight discovery.

Create a server-side key

In Console → API Keys, create a credential and copy it immediately. Store it in your secret manager.

Shell

export CCT_API_KEY="cct_your_secret_key"

Create a private video upload

Production scanner runs accept a completed, account-owned upload. Create the ticket, send the raw bytes to the returned signed PUT target using every returned upload_headers entry, then mark it complete.

cURL

curl -X POST https://api.chatclipthat.com/v1/uploads \
  -H "Authorization: Bearer $CCT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"recording.mp4","content_type":"video/mp4","size_bytes":12345678}'

# Use upload_method, upload_url, and every upload_headers entry from the response.
curl -X PUT "$CCT_UPLOAD_URL" -H "Content-Type: video/mp4" --upload-file recording.mp4

curl -X POST https://api.chatclipthat.com/v1/uploads/upl_YOUR_ID/complete \
  -H "Authorization: Bearer $CCT_API_KEY"

Wait for status: "ready" and confirm media_kind: "video". Failed system processing is refunded. The signed PUT expiry is only the upload deadline, not ready-source retention.

Create a saved moment scanner

Describe the moments you want, including what makes them useful. Video find_moments uses ChatClipThat's production moment-selection behavior.

cURL

curl -X POST https://api.chatclipthat.com/v1/scanners \
  -H "Authorization: Bearer $CCT_API_KEY" \
  -H "Idempotency-Key: quickstart-scanner-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-signal conversation clips",
    "type": "find_moments",
    "instructions": "Find decisions, disagreements, commitments, strong questions, and explanations that stand alone as useful clips.",
    "profile": "conversation",
    "max_observations": 10,
    "min_seconds": 10,
    "max_seconds": 60,
    "output": {"fields": ["title", "summary", "start_ms", "end_ms", "relevance_score"]},
    "metadata": {"workflow": "clip-review"}
  }'

The response returns a scanner_id and version 1. Later edits create new versions without rewriting old run provenance.

Run the scanner

Each run snapshots the current scanner version. Provide both window fields to analyze only that part of the video, or omit both to analyze the full upload.

cURL

curl -X POST https://api.chatclipthat.com/v1/scanners/scn_YOUR_ID/runs \
  -H "Authorization: Bearer $CCT_API_KEY" \
  -H "Idempotency-Key: quickstart-run-001" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "upl_YOUR_READY_UPLOAD",
    "analysis_start_seconds": 900,
    "analysis_end_seconds": 2700,
    "metadata": {"recording_id": "rec_1842"}
  }'

Poll GET /v1/runs/{run_id} every 5–10 seconds until completed or failed. queued is accepted and waiting fairly, dispatched is assigned to capacity, and processing is active execution. No run has an instant-start guarantee.

One upload, several saved questions? Reuse the ready upload in a durable POST /v1/scanner-batches request with one independently billed item per scanner. Batch items analyze their full upload; use the single-run endpoint for selected windows.

Read and optionally render the moments

cURL

curl https://api.chatclipthat.com/v1/runs/run_YOUR_ID/observations \
  -H "Authorization: Bearer $CCT_API_KEY"

# Each completed video find_moments observation includes value.moment_id.
curl -X POST https://api.chatclipthat.com/v1/renders \
  -H "Authorization: Bearer $CCT_API_KEY" \
  -H "Idempotency-Key: quickstart-render-001" \
  -H "Content-Type: application/json" \
  -d '{"analysis_id":"ana_FROM_THE_RUN","moment_ids":["mom_FROM_THE_OBSERVATION"]}'

Review the timestamp, title, summary, and relevance before deciding whether to render. Scanner completion itself stays JSON-only and never publishes media.

Rendering is explicit. Only Moment IDs returned by completed video find_moments runs are accepted from this scanner flow. Other observation IDs and all audio scanner results are not renderable.