GovTube Citations API

openapi: 3.2.0
info:
  title: GovTube Citations 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: Citations
paths:
  /v1/citations/{citation_id}:
    get:
      summary: Citation
      description: 'Resolve a citation token. gt2. (older links: gt1.) cites a moment in a video; gd2. (gd1.) cites words in an official transcript (positions instead of times, citation_text, certifies). All re-find the words after corrections: exact, reanchored, moved or superseded. gt2./gd2. ids are signed: 400 when the signature doesn''t match. Unsigned gt1./gd1. ids keep resolving (signed false; see quoted_text and canonical_id).'
      operationId: citation_v1_citations__citation_id__get
      parameters:
      - name: citation_id
        in: path
        required: true
        schema:
          type: string
          title: Citation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitationResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Citations
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CitationResult:
      properties:
        status:
          type: string
          title: Status
          description: exact, reanchored, moved or superseded.
        note:
          type: string
          title: Note
        video_id:
          type: string
          title: Video Id
        timing_granularity:
          type: string
          enum:
          - word
          - segment
          - sentence
          - turn
          - chunk
          - document
          title: Timing Granularity
          description: 'word: a gt2./gt1. citation of a moment in a video. document: a gd2./gd1. citation of words in an official transcript, with positions instead of times (ADR 0004).'
          default: word
        original_start_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Original Start Ms
          description: Null exactly when timing_granularity is document (no made-up times).
        current_start_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Current Start Ms
          description: Null when superseded, or for document citations.
        original_position:
          anyOf:
          - $ref: '#/components/schemas/DocumentPosition'
          - type: 'null'
          description: 'document only: where the cited words were when the link was made.'
        current_position:
          anyOf:
          - $ref: '#/components/schemas/DocumentPosition'
          - type: 'null'
          description: 'document only: where they are now; null when superseded.'
        document_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Document Url
          description: 'document only: the official document.'
        citation_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Citation Text
          description: 'document only: ready-to-paste citation, “{words}” {speaker}, {title}, {date}. Daily Compilation of Presidential Documents, {package}. {url}. Null when superseded.'
        certifies:
          anyOf:
          - type: string
          - type: 'null'
          title: Certifies
          description: 'document only: what the citation certifies. The words appear in the official transcript; it does not certify them as spoken (ORTH-177 rule 1).'
        quoted_text:
          type: string
          title: Quoted Text
          description: 'The words the link originally cited (normalized). Kept after corrections, except for an unsigned link (signed false) that is superseded: then empty, because GovTube can''t confirm words that are no longer in the transcript.'
        signed:
          type: boolean
          title: Signed
          description: 'True for a gt2./gd2. id: GovTube issued it, so quoted_text, cited_rev and the original time or position are what GovTube recorded. False for an older unsigned gt1./gd1. id (ADR 0005): it still resolves, but only the words found in the current transcript are confirmed.'
          default: false
        canonical_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Canonical Id
          description: A signed id for the cited words where they are now (null when superseded, or when the server has no citation key). Share this one instead of an unsigned id.
        transcript_context:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Transcript Context
        cited_rev:
          type: integer
          title: Cited Rev
          description: Transcript revision the citation was made from.
        current_rev:
          type: integer
          title: Current Rev
          description: Transcript revision it was resolved against.
        corrected_at:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Corrected At
          description: 'For reanchored, moved and superseded: the date (UTC) the current revision was published, i.e. the latest correction since the link was made. If current_rev - cited_rev > 1, an earlier revision may have made the change. Null for exact, or when that revision was published before revision dates were recorded.'
        replacement:
          anyOf:
          - $ref: '#/components/schemas/CitationReplacement'
          - type: 'null'
          description: 'superseded only: where the corrected passage lives. Null when it could not be determined; replacement_note then says so.'
        replacement_note:
          anyOf:
          - type: string
          - type: 'null'
          title: Replacement Note
          description: 'superseded only: how the replacement was found, or why it could not be.'
        low_confidence:
          type: boolean
          title: Low Confidence
          description: 'verification is low_confidence: the quoted words, as they stand in the current transcript, are on hold until reviewed (ORTH-176; same rule as search results). False for superseded (no current words) and document citations.'
          default: false
        withheld:
          type: boolean
          title: Withheld
          description: low_confidence and no reviewer has checked these words yet (review state 'unreviewed'). The API still returns the words (quoted_text, transcript_context); the web decides what to hide (share page 'on hold' state).
          default: false
        caption_check:
          type: string
          enum:
          - agrees
          - differs
          - not_checked
          title: Caption Check
          description: 'How the official live captions compare with the words a quote of this result shows: the excerpt and the whole sentence(s) around the matched words, not just the matched words (ORTH-225; HEURISTIC). differs: the captions have different words somewhere in there, so the machine transcript may have misheard them; check the video before quoting and say the transcript is unverified. agrees: the captions have the same words (captions are live stenography, not a verbatim record, so this is not a check by a person). not_checked: no caption check for this video, the captions skip some of these words, or an official transcript (no captions to compare). Always not_checked when superseded (no current words) and for document citations.'
          default: not_checked
        verification:
          anyOf:
          - type: string
            enum:
            - checked
            - unverified
            - low_confidence
          - type: 'null'
          title: Verification
          description: 'Whether the words a quote of this result shows (the excerpt and the sentence(s) around the matched words, as caption_check) were checked against a second source (ORTH-176). checked: the official captions have the same words, or a reviewer checked them; no mark is shown. unverified: nothing to check them against, or the captions differ where the speech recognizer was sure of its words (the captioner''s spelling or mishearing, more often than not); say ''Transcript unverified''. low_confidence: on hold until reviewed; a caption difference where the recognizer''s own word score was under 0.9, or a word scored under 0.5 that the captions can''t check (HEURISTIC thresholds, not yet calibrated by listening). Null for official documents (no machine transcript). Null when superseded (no current words).'
        verification_source:
          anyOf:
          - type: string
            enum:
            - house_captions
            - senate_captions
            - dvids_captions
            - reviewer
            - asr_word_confidence
          - type: 'null'
          title: Verification Source
          description: 'What checked or disputed the words: house_captions, senate_captions, dvids_captions (the official live captions), reviewer (a person, against the video) or asr_word_confidence (the recognizer''s own word score; low_confidence only). Null when unverified.'
        words_checked:
          type: boolean
          title: Words Checked
          description: 'A reviewer checked the cited words against the video (review state confirmed or corrected). False (every citation today): the words are a machine transcript nobody has checked, so end a quoted citation with ''Transcript unverified.'' Always false for document citations (they cite an official transcript).'
          default: false
        source_certainty:
          type: string
          enum:
          - official_record
          - official_channel
          - unverified
          title: Source Certainty
          description: 'The cited video''s. How sure GovTube is about the source material (ADR 0006). official_record: the official recording or record of the proceeding (House and Senate video, the Daily Compilation of Presidential Documents). official_channel: published by the office itself, e.g. on its official YouTube channel; it may be edited or excerpted and is not the complete record. unverified: not confirmed as official. Show source_caveats whenever this is not official_record or source_caveats is not empty.'
          default: unverified
        source_caveats:
          items:
            type: string
          type: array
          title: Source Caveats
          description: The cited video's. Plain sentences about what is uncertain in this source material, to show (and pass along) with any quote, e.g. 'Speakers are identified by machine and not reviewed.' Empty when there is nothing to add.
      type: object
      required:
      - status
      - note
      - video_id
      - original_start_ms
      - current_start_ms
      - quoted_text
      - cited_rev
      - current_rev
      title: CitationResult
    CitationReplacement:
      properties:
        video_id:
          type: string
          title: Video Id
        start_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Start Ms
          description: Null exactly when timing_granularity is document (no made-up times).
        end_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: End Ms
          description: Null exactly when timing_granularity is document (no made-up times).
        play_from_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Play From Ms
          description: Playback start including pre-roll, in playback-asset time. Null exactly when timing_granularity is document (no made-up times).
        position:
          anyOf:
          - $ref: '#/components/schemas/DocumentPosition'
          - type: 'null'
          description: 'document only: where the replacement words start.'
        text:
          type: string
          title: Text
          description: 'The current words at the cited time or position (HEURISTIC: same place, not proven to be the same remark).'
      type: object
      required:
      - video_id
      - start_ms
      - end_ms
      - play_from_ms
      - text
      title: CitationReplacement
      description: Where a superseded citation's moment (or, in an official document, position) lives now.
    DocumentPosition:
      properties:
        paragraph:
          type: integer
          minimum: 1.0
          title: Paragraph
          description: Paragraph of the transcript text, from 1. The document's heading, date line and closing note are not counted.
        word:
          type: integer
          minimum: 1.0
          title: Word
          description: Word within that paragraph, from 1. Words are separated by spaces; the speaker label such as 'The President.' is not counted, a stage note such as '[Applause]' is.
      type: object
      required:
      - paragraph
      - word
      title: DocumentPosition
      description: Where words sit in an official document's transcript text (ADR 0004), counted from 1 as a reader counts.