Social Data PlaneAPI reference

Field note 002 / Reference memory

YouTube route · experimental

Reference memory for AI creative agents.

Give an agent a public URL and get back a structured reference: verified metadata, a transcript-ready analysis proxy, a poster frame, and provenance. Delivered through a REST API and an MCP server, neutral across whichever generator comes next.

See what a reference holds Read the storage model
INITIAL ADMISSION LIMITS2 GiBmaximum bytes4 Hmaximum duration480 Panalysis default · 1080 P on request
01

What a reference holds

One public URL in. One citable, generator-ready reference out.

INPUT

A public URL

Submit one public, unauthenticated source URL through the API or an MCP tool. Recognition, policy, idempotency, and durable progress begin before slow media work. Accepting a brief instead of a URL is planned, not shipped.

OUTPUT

A structured reference

Verified source metadata, a 480p analysis proxy sized for transcription and shot analysis, a poster frame, and machine-derived facts—plain JSON shaped for an agent, not a browser tab.

PROVENANCE

Evidence you can cite

Content hash, capture timestamp, and route version travel with every reference, so anything a generator consumes can be traced back to what was observed and when.

Creative spec · planned

A generation-ready creative spec—hook, shots, pacing, call to action, and a generation prompt—is on the roadmap and reserved in the contract. It returns null today. AI-provenance signals share the same status.

02

One owned route

Five boundaries. Every transition leaves evidence.

  1. 01

    Recognize

    Normalize one supported public URL into a stable source identity.

  2. 02

    Acquire

    Resolve metadata and an analysis proxy through project-operated tooling. 480p by default; 1080p only when the request asks for it.

  3. 03

    Quarantine

    Stream within hard duration, size, quality, and disk limits.

  4. 04

    Verify

    Probe tracks, inspect type, measure bytes, and calculate identity.

  5. 05

    Commit

    Finalize one durable reference with its poster and provenance. Media bytes enter a time-boxed hold.

The first route accepts a deliberately narrow public YouTube video contract and runs on project-operated tooling—no hosted scraper in the production path. Wider source coverage comes route by route, never through a hidden provider fallback.

03

Storage model

Derivatives are durable. Bytes are time-boxed.

  1. TIER A

    Durable derivatives

    Canonical source rows, observed history, the poster frame, machine-derived facts, and provenance—content hash, capture timestamp, route version. These never expire by default.

    Kept
  2. TIER B

    Media hold

    The committed video object is retained only while a hold you requested is active. A successful ingestion opens one for 30 days; the API can extend it up to 365 or release it early. When the last hold lapses, the bytes are deleted and the reference reports its media as expired.

    30 days by default
  3. TIER C

    Permanent bulk library

    There is no standing archive of third-party video. Every byte on disk traces back to a specific request and a specific window.

    Not built

Only public, unauthenticated sources are accepted. A reference stays readable after its media expires; what disappears is the video object, not the memory of it.

04

For agents

Two surfaces. One contract. No generator lock-in.

REST API / served from the API origin

Read the contract before you write a client.

  • GET /openapi.jsonThe machine-readable contract for every /v1 route.
  • GET /docsA rendered API reference generated from that same document.

Every route under /v1 is described in the OpenAPI document. References are plain JSON, so any image, video, or audio generator can consume them without a vendor-specific format.

MCP server / stdio by default

The same operations as tools an agent can call.

  • resolve_referenceSubmit a public URL; returns an ingestion id.
  • get_ingestionRead durable ingestion state and stage progress.
  • list_referencesPage through workspace references with filters.
  • get_referenceFetch one reference with provenance and media status.
  • update_referenceWrite title, notes, and tags with revision checks.
  • delete_referenceRemove a reference from the workspace.
  • get_media_accessObtain bounded, authorized access to held media.
  • extend_media_holdExtend the time-boxed hold on media bytes.
  • list_source_routesInspect which source routes exist and their state.

The MCP server is a thin client over /v1 authenticated with a workspace API key. It never logs keys and never exposes raw source URLs beyond what the API returns.

Open openapi.json Browse the rendered docs
05

Operating principles

Built for truth after the happy-path demo ends.

  1. A

    The queue is not the truth

    PostgreSQL owns accepted work, attempts, and outcomes. Redis can disappear; reconciliation brings delivery back.

  2. B

    Derivatives are durable, bytes are time-boxed

    Metadata, poster, machine-derived facts, and provenance persist. The video object itself lives only inside a customer-requested hold and expires when that hold does.

  3. C

    Failure stays specific

    Unsupported, unavailable, policy-blocked, retrying, expired, and disabled are different states with different actions.

Current truth / Route 001

Experimental by design.

The system is under active construction. The public YouTube route starts disabled, supports no login-required or protected content, and makes no availability promise until corpus, canary, durability, and security gates pass. Nothing on this page describes a customer, a metric, or a source that does not exist yet.

Live acquisition is off by default