GovTube Coverage API

openapi: 3.2.0
info:
  title: GovTube Coverage API
  description: Per-instance search over what U.S. officials say on camera. The same service is available to agents at /mcp.
  version: 0.1.0
tags:
- name: Coverage
paths:
  /v1/coverage:
    get:
      summary: Coverage
      operationId: coverage_v1_coverage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageInfo'
      tags:
      - Coverage
components:
  schemas:
    CoverageSession:
      properties:
        video_id:
          type: string
          title: Video Id
        title:
          type: string
          title: Title
        event_date:
          type: string
          format: date
          title: Event Date
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
          description: 'Length in milliseconds: VideoMeta.duration_ms when measured at ingest, else the last word''s end_ms (see duration_measured). Null for an official document (timing_granularity document).'
        duration_measured:
          type: boolean
          title: Duration Measured
          description: True when duration_ms is the measured audio length. False means it is the last word's end, which can fall short of the real length (trailing silence or recess), or null.
        timing_granularity:
          type: string
          enum:
          - word
          - segment
          - sentence
          - turn
          - chunk
          - document
          title: Timing Granularity
          description: 'What the timing is attached to (ORTH-177): word = every word has a time (our transcripts); document = no timing at all, the words come from an official document (ADR 0004). Times are null exactly when this is document.'
          default: word
        fidelity:
          type: string
          enum:
          - verbatim
          - clean
          - edited
          title: Fidelity
          description: 'verbatim: what was said, as said (our transcripts). edited: revised after the fact, e.g. a White House transcript; label it ''Official transcript · edited · no timing'' and never certify it as spoken.'
          default: verbatim
        words:
          type: integer
          title: Words
          description: Words in the current transcript revision.
        playable:
          type: boolean
          title: Playable
          description: A playback asset exists and its alignment with the transcript is verified.
        playback_kind:
          anyOf:
          - type: string
            enum:
            - youtube
            - hls
            - mp4
          - type: 'null'
          title: Playback Kind
          description: Kind of playback asset, or null when there is none. Set with playable false means the asset's alignment is not verified yet.
        speaker_labels:
          type: integer
          title: Speaker Labels
          description: Distinct speaker labels (diarization clusters) in the video.
        speakers_confirmed:
          type: integer
          title: Speakers Confirmed
          description: Speaker labels a person has confirmed against the official record.
        transcript_rev:
          type: integer
          title: Transcript Rev
          description: Current transcript revision (1 = first transcript, no corrections).
        collection:
          anyOf:
          - type: string
          - type: 'null'
          title: Collection
          description: Key of the coverage collection this session counts in (CoverageInfo.collections[].key).
        verification:
          anyOf:
          - $ref: '#/components/schemas/SessionVerification'
          - type: 'null'
          description: 'Timed transcripts: how much of it is on hold (ORTH-176). Null for official documents and for a session not republished or checked against its captions since the rule shipped.'
      type: object
      required:
      - video_id
      - title
      - event_date
      - duration_ms
      - duration_measured
      - words
      - playable
      - playback_kind
      - speaker_labels
      - speakers_confirmed
      - transcript_rev
      title: CoverageSession
      description: One indexed video, as the coverage page's sessions table shows it (handoff §5.7).
    CoverageCollection:
      properties:
        key:
          type: string
          title: Key
          description: Stable key, e.g. 'house_floor', 'senate_committees', 'govinfo_dcpd'.
        kind:
          type: string
          enum:
          - video
          - document
          title: Kind
          description: 'video: recorded sessions with word timing. document: official transcripts without timing (ADR 0004); they are not video.'
        source_id:
          type: string
          title: Source Id
          description: Key into the source policy registry.
        label:
          type: string
          title: Label
          description: 'What the collection holds, for display: ''U.S. Senate committee hearings''.'
        unit:
          type: string
          title: Unit
          description: 'One item, for display with a count: ''session'', ''hearing'', ''transcript''.'
        units:
          type: string
          title: Units
          description: 'Several items: ''sessions'', ''hearings'', ''transcripts''.'
        short_name:
          type: string
          title: Short Name
          description: The source's short name, e.g. 'Senate.gov'.
        rights_short:
          type: string
          title: Rights Short
          description: The source's rights in a few words, e.g. 'public record'.
        items:
          type: integer
          minimum: 0.0
          title: Items
          description: Sessions (video) or documents (document) in the collection.
        first_event_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: First Event Date
        last_event_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Last Event Date
        hours:
          anyOf:
          - type: number
          - type: 'null'
          title: Hours
          description: Hours of video, one decimal; null for documents.
        words:
          type: integer
          minimum: 0.0
          title: Words
          description: 'Words in the current transcripts: transcribed by GovTube for video, as printed for documents.'
        speaker_labels:
          type: integer
          minimum: 0.0
          title: Speaker Labels
          description: 'Speaker labels: voice clusters for video; for documents, the speakers the record itself names.'
        speakers_confirmed:
          type: integer
          minimum: 0.0
          title: Speakers Confirmed
          description: Speaker labels a person has confirmed.
        awaiting_review:
          type: integer
          minimum: 0.0
          title: Awaiting Review
          description: Items with at least one speaker label nobody has confirmed.
        days:
          anyOf:
          - items:
              $ref: '#/components/schemas/CoverageDay'
            type: array
          - type: 'null'
          title: Days
          description: 'Set only for a collection counted by day (the Congressional Record: one item per speech, ORTH-209): its days, newest first. Its items are then not listed one by one in CoverageInfo.sessions. Null for every other collection.'
      type: object
      required:
      - key
      - kind
      - source_id
      - label
      - unit
      - units
      - short_name
      - rights_short
      - items
      - first_event_date
      - last_event_date
      - hours
      - words
      - speaker_labels
      - speakers_confirmed
      - awaiting_review
      title: CoverageCollection
      description: 'One kind of material from one source, e.g. U.S. House floor sessions or White House official transcripts

        (ORTH-207). Every session counts in exactly one collection; the video collections add up to CoverageInfo.video

        and the document collections to CoverageInfo.documents.'
    SessionVerification:
      properties:
        words:
          type: integer
          minimum: 0.0
          title: Words
          description: Words in the transcript.
        words_scored:
          type: integer
          minimum: 0.0
          title: Words Scored
          description: Words with a speech-recognizer score (0 for a transcript made before scores were kept).
        words_checked:
          type: integer
          minimum: 0.0
          title: Words Checked
          description: Words the official captions agree with.
        words_held:
          type: integer
          minimum: 0.0
          title: Words Held
          description: Words the rule holds (low_confidence).
        sentences:
          type: integer
          minimum: 0.0
          title: Sentences
          description: Sentences (a word ending in . ? or !, or the last word).
        sentences_held:
          type: integer
          minimum: 0.0
          title: Sentences Held
          description: Sentences with at least one held word.
        held_share:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Held Share
          description: sentences_held / sentences, rounded to 4 places.
        caption_source:
          anyOf:
          - type: string
            enum:
            - house_captions
            - senate_captions
            - dvids_captions
            - reviewer
            - asr_word_confidence
          - type: 'null'
          title: Caption Source
          description: The captions compared (house_captions, ...); null when none are stored.
        conf_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Conf Source
          description: What the word scores are, e.g. phonon2_token_posterior_min; null when no word has one.
        computed_at:
          type: string
          title: Computed At
          description: When these counts were made (ISO 8601, UTC).
      type: object
      required:
      - words
      - words_scored
      - words_checked
      - words_held
      - sentences
      - sentences_held
      - held_share
      - computed_at
      title: SessionVerification
      description: 'How much of one session''s transcript the ORTH-176 rule puts on hold (MEASURED, scope: this transcript revision

        and its stored caption check), so a hold can''t silently swallow a whole session.'
    DocumentCoverage:
      properties:
        count:
          type: integer
          minimum: 0.0
          title: Count
          description: Official transcripts in the archive.
          default: 0
        words:
          type: integer
          minimum: 0.0
          title: Words
          description: Words as printed in the official transcripts (not transcribed by GovTube).
          default: 0
        first_event_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: First Event Date
        last_event_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Last Event Date
      type: object
      title: DocumentCoverage
      description: 'Totals over official transcripts without timing (ORTH-207), all document sources together. Per source:

        CoverageInfo.collections with kind document.'
    VideoCoverage:
      properties:
        sessions:
          type: integer
          minimum: 0.0
          title: Sessions
          default: 0
        hours:
          type: number
          title: Hours
          description: Hours of video, one decimal (includes last-word estimates where sessions[].duration_measured is false).
          default: 0.0
        words:
          type: integer
          minimum: 0.0
          title: Words
          description: Words transcribed by GovTube.
          default: 0
        first_event_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: First Event Date
        last_event_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Last Event Date
        speaker_labels:
          type: integer
          minimum: 0.0
          title: Speaker Labels
          description: Speaker labels (voice clusters) across the videos.
          default: 0
        speakers_confirmed:
          type: integer
          minimum: 0.0
          title: Speakers Confirmed
          description: Of those, the labels a person has confirmed.
          default: 0
        awaiting_review:
          type: integer
          minimum: 0.0
          title: Awaiting Review
          description: Videos with at least one unconfirmed speaker label, or none at all.
          default: 0
      type: object
      title: VideoCoverage
      description: 'Totals over video only (ORTH-207): no official transcript counts here.'
    CoverageInfo:
      properties:
        videos:
          type: integer
          title: Videos
          description: Every item in the archive, video sessions and official transcripts together. For display use video.sessions and documents.count.
        first_event_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: First Event Date
          description: 'Earliest item of either kind. Video only: video.first_event_date.'
        last_event_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Last Event Date
          description: 'Latest item of either kind. Video only: video.last_event_date.'
        sources:
          items:
            type: string
          type: array
          title: Sources
        last_ingested_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Ingested At
        awaiting_review:
          type: integer
          title: Awaiting Review
          description: 'Items of either kind with an unconfirmed speaker label. Video only: video.awaiting_review.'
          default: 0
        known_gaps:
          items:
            type: string
          type: array
          title: Known Gaps
        total_hours:
          type: number
          title: Total Hours
          description: Sum of sessions[].duration_ms in hours, one decimal. Includes last-word estimates where duration_measured is false; official documents (no duration) add nothing.
          default: 0.0
        total_words:
          type: integer
          title: Total Words
          description: 'Sum of sessions[].words, video and official transcripts together. Words transcribed: video.words.'
          default: 0
        video:
          $ref: '#/components/schemas/VideoCoverage'
          description: Totals over video only.
        documents:
          $ref: '#/components/schemas/DocumentCoverage'
          description: Totals over official transcripts (no timing) only.
        collections:
          items:
            $ref: '#/components/schemas/CoverageCollection'
          type: array
          title: Collections
          description: 'One entry per kind of material per source: video first (most items first), then documents. Build source lines from these.'
        sessions:
          items:
            $ref: '#/components/schemas/CoverageSession'
          type: array
          title: Sessions
          description: One entry per video or official transcript, newest first, except the items of a collection counted by day (see collections[].days).
        revised:
          type: integer
          minimum: 0.0
          title: Revised
          description: Items of every collection (the ones counted by day included) whose current transcript revision is above 1.
          default: 0
        corrections:
          items:
            $ref: '#/components/schemas/CorrectionEntry'
          type: array
          title: Corrections
          description: 'The corrections log, newest first: records hidden from search, coverage and their pages, or restored (decision 12), and words corrected at the next transcript revision, itemized (action corrected, ORTH-146). Other revisions (respacing, speaker names) are counted in revised, not listed.'
      type: object
      required:
      - videos
      - first_event_date
      - last_event_date
      - sources
      title: CoverageInfo
      description: 'Shown on every results page (coverage transparency). Video and official transcripts are counted apart

        (ORTH-207): read video and documents (or collections) for display. videos, first/last_event_date,

        awaiting_review and total_* are over everything, video and documents together, and stay for compatibility.'
    CorrectionEntry:
      properties:
        id:
          type: integer
          title: Id
          description: Increasing entry number.
        at:
          type: string
          title: At
          description: When the change was made (ISO 8601, UTC).
        action:
          type: string
          enum:
          - hidden
          - restored
          - corrected
          title: Action
          description: 'hidden: taken out of search, coverage, its pages and its citations (they answer 410). restored: put back exactly as it was. corrected: words changed at the next transcript revision (from_rev -> rev); see changes and citations.'
        video_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Video Id
          description: The record's id. Null when the title is withheld (e.g. a legal request), so the entry does not identify the record.
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: The record's title. Null when withheld.
        event_date:
          type: string
          format: date
          title: Event Date
          description: The record's event date.
        source_id:
          type: string
          title: Source Id
          description: Key into the source policy registry.
        source_name:
          type: string
          title: Source Name
          description: The source, for display, e.g. 'U.S. House Clerk'.
        rev:
          type: integer
          title: Rev
          description: The transcript revision that was hidden or restored; for corrected, the new revision.
        reason:
          type: string
          title: Reason
          description: Why, in plain words, as published.
        from_rev:
          anyOf:
          - type: integer
          - type: 'null'
          title: From Rev
          description: 'corrected only: the revision the words were corrected from (rev - 1).'
        changes:
          items:
            $ref: '#/components/schemas/CorrectionChange'
          type: array
          title: Changes
          description: 'corrected only: each corrected span, before and after, in transcript order. Empty while the record is hidden (its words are in no public read).'
        citations:
          anyOf:
          - $ref: '#/components/schemas/CitationCounts'
          - type: 'null'
          description: 'corrected only: what the correction did to links quoting the corrected words.'
      type: object
      required:
      - id
      - at
      - action
      - video_id
      - title
      - event_date
      - source_id
      - source_name
      - rev
      - reason
      title: CorrectionEntry
      description: 'One entry of the public corrections log (decision 12): a record hidden from search, coverage and its pages, or

        restored; or its words corrected at the next transcript revision (ORTH-146). Written by the admin hide, unhide

        and fix routes in the same transaction as the change itself.'
    CitationCounts:
      properties:
        probes:
          type: integer
          minimum: 0.0
          title: Probes
          description: Quotes resolved (each one-turn quote of 1 to 5 words that includes a corrected word, at most 200 in all).
        reanchored:
          type: integer
          minimum: 0.0
          title: Reanchored
          description: Still found at that moment.
        moved:
          type: integer
          minimum: 0.0
          title: Moved
          description: Found once elsewhere in the video; the link follows it.
        superseded:
          type: integer
          minimum: 0.0
          title: Superseded
          description: 'Replaced: the quoted words are no longer there; the link shows the original quote and the words now at that time.'
        capped:
          type: boolean
          title: Capped
          description: True when there were more than 200 such quotes and only the first 200 were resolved.
          default: false
      type: object
      required:
      - probes
      - reanchored
      - moved
      - superseded
      title: CitationCounts
      description: 'What a correction did to links quoting the corrected words (ORTH-146). GovTube keeps no list of the links

        people shared (a citation is a self-contained token), so these count probes: every quote of 1 to 5 words that

        includes a corrected word, as it read before, resolved against the corrected revision exactly as a shared link

        would be. Links to unchanged words elsewhere in the video all re-anchor (same words, same time).'
    CorrectionChange:
      properties:
        start_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Start Ms
          description: Where the corrected words start in the video, in the revision before.
        end_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: End Ms
          description: Where they end.
        word:
          type: integer
          minimum: 0.0
          title: Word
          description: Position of the first corrected word in the revision before (0-based).
        before:
          type: string
          title: Before
          description: The words as they read before, exactly as shown.
        after:
          type: string
          title: After
          description: The words as they read now. Empty when the words were removed.
      type: object
      required:
      - start_ms
      - end_ms
      - word
      - before
      - after
      title: CorrectionChange
      description: 'One corrected span of words (``govtube-corrections fix``): what it read and what it reads now.'
    CoverageDay:
      properties:
        event_date:
          type: string
          format: date
          title: Event Date
        items:
          type: integer
          minimum: 0.0
          title: Items
          description: 'Items that day (for the Congressional Record: speeches).'
        words:
          type: integer
          minimum: 0.0
          title: Words
          description: Words in those items, as printed.
        parts:
          additionalProperties:
            type: integer
          type: object
          title: Parts
          description: 'Items per part of the day''s record, e.g. {''House'': 120, ''Senate'': 85}.'
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: The day's whole record at its source, e.g. the Congressional Record issue on GovInfo.
      type: object
      required:
      - event_date
      - items
      - words
      title: CoverageDay
      description: One day of a collection counted by day (CoverageCollection.days).