3GPP Scout Documents API

openapi: 3.2.0
info:
  title: 3gppscout Com Documents API
  version: 0.2.0
  description: 'Operations tagged documents across 2 of this provider''s published API definitions: 3gppscout-com-openapi.json, api.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Documents
paths:
  /documents:
    get:
      tags:
      - Documents
      summary: List Documents
      description: 'List 3GPP documents available in the search index with metadata (doc_number, title, release, series, chunk counts).


        Without filters, returns all ~3,200 documents. Use doc_number to check if a specific document is indexed (fast: only fetches 1-2 status files instead of scanning all).


        Each version carries `provenance`: when it was uploaded to the 3GPP archive (UTC) and the TSG plenary it was approved at, with sources. With doc_number and available_before, this answers which indexed versions of a spec were in the 3GPP archive before a date.'
      operationId: list_documents_documents_get
      parameters:
      - name: doc_number
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by document number, e.g. '38.811'. Returns only versions of that document.
          title: Doc Number
        description: Filter by document number, e.g. '38.811'. Returns only versions of that document.
      - name: release
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by 3GPP release, e.g. 'Rel-19'.
          title: Release
        description: Filter by 3GPP release, e.g. 'Rel-19'.
      - name: series
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by series, e.g. '38'.
          title: Series
        description: Filter by series, e.g. '38'.
      - name: doc_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by document type: ''TS'' or ''TR''.'
          title: Doc Type
        description: 'Filter by document type: ''TS'' or ''TR''.'
      - name: available_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Only versions uploaded to the 3GPP archive before this date (YYYY-MM-DD; before 00:00 UTC, so the day itself is excluded), e.g. a patent application's priority date. A version whose upload time is unknown is left out. Usually one version per release of each spec is indexed (the newest in that release, Rel-15 onward), so a release appears only if that version predates the cutoff; older versions are in the 3GPP archive but not searchable here.
          title: Available Before
        description: Only versions uploaded to the 3GPP archive before this date (YYYY-MM-DD; before 00:00 UTC, so the day itself is excluded), e.g. a patent application's priority date. A version whose upload time is unknown is left out. Usually one version per release of each spec is indexed (the newest in that release, Rel-15 onward), so a release appears only if that version predates the cutoff; older versions are in the 3GPP archive but not searchable here.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentInfo'
                title: Response List Documents Documents Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /documents/{document_id}:
    get:
      tags:
      - Documents
      summary: Get Document
      description: Get metadata for a single 3GPP document by its numeric ID (from search results or list_documents). Returns title, doc_number, release, series, chunk counts, and `provenance` (when the version was uploaded to the 3GPP archive and the TSG plenary it was approved at).
      operationId: get_document_documents__document_id__get
      parameters:
      - name: document_id
        in: path
        required: true
        schema:
          type: integer
          title: Document Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentInfo'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SpecProvenance:
      properties:
        statement:
          anyOf:
          - type: string
          - type: 'null'
          title: Statement
          description: 'The known facts as plain sentences, ready to quote, e.g. ''Uploaded to the 3GPP archive on 2026-09-24 at 16:47 UTC. Approved at TSG SA #113 (2026-09-15 to 2026-09-18).'' It says ''uploaded to the 3GPP archive'' and ''approved at'', never ''published'': no source states a publication date.'
        archive_uploaded_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Archive Uploaded At
          description: When this version's zip was uploaded to the 3GPP archive (ISO 8601, UTC), as the 3GPP FTP folder listing at archive_url shows it. If 3GPP re-uploaded the file, the earliest time seen. Null when not found; see unknown_reasons.
        archive_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Archive Url
          description: The zip on the 3GPP FTP server whose folder listing gives archive_uploaded_at; open its folder to verify the time.
        archive_date_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Archive Date Source
          description: '''ftp_archive_listing'' (the spec''s folder under /ftp/Specs/archive/) or ''ftp_plenary_folder_listing'' (a dated plenary folder that showed an earlier time).'
        plenary_batch:
          anyOf:
          - type: string
          - type: 'null'
          title: Plenary Batch
          description: YYYY-MM of the plenary round whose batch of specifications includes this version (3GPP's dated folders, /ftp/Specs/YYYY-MM/).
        plenary_batch_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Plenary Batch Source
          description: '''tsg_spec_list'' (stated in 3GPP''s list of specifications arising from that TSG round), ''tsg_meeting_start'' (the month the plenary in tsg_meeting started) or ''ftp_plenary_folder'' (the earliest dated folder holding the zip).'
        tsg_meeting:
          anyOf:
          - type: string
          - type: 'null'
          title: Tsg Meeting
          description: 'Plenary meeting ID: ''SP-113'' (TSG SA #113), ''RP-109'' (TSG RAN), ''CP-110'' (TSG CT); a trailing ''-e'' marks an electronic meeting.'
        tsg_meeting_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Tsg Meeting Name
          description: 'The meeting as 3GPP names it, e.g. ''TSG SA #113''.'
        tsg_meeting_relation:
          anyOf:
          - type: string
          - type: 'null'
          title: Tsg Meeting Relation
          description: '''approved'': change requests approved at this meeting created this version (3GPP CR database). ''arising_from'': 3GPP lists this version among the specifications arising from this meeting. ''presented'': a draft (below version 3.0.0) presented to this meeting.'
        tsg_meeting_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Tsg Meeting Start
          description: First day of the plenary meeting.
        tsg_meeting_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Tsg Meeting End
          description: Last day of the plenary meeting.
        tsg_meeting_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Tsg Meeting Source
          description: '''cr_database'' (3GPP change request database export) or ''tsg_spec_list'' (3GPP''s list of specifications arising from that TSG round).'
        tsg_meeting_source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Tsg Meeting Source Url
          description: The 3GPP file that names the meeting.
        unknown_reasons:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Unknown Reasons
          description: 'Why a field is null, by field name. archive_uploaded_at: ''not_in_archive_listing''. tsg_meeting: ''before_tsg_lists_no_approved_cr'' (uploaded before March 2023, when 3GPP''s per-round spec lists start, and created by no approved change request, e.g. a release upgrade), ''draft_not_listed'', or ''not_in_cr_database_or_tsg_lists''. Nothing is guessed.'
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
          description: Anything a reviewer should know, e.g. the file was re-uploaded or two sources name different meetings.
      type: object
      title: SpecProvenance
      description: 'When this spec version reached the public 3GPP archive, and the TSG plenary it came from.


        Every value comes from the 3GPP FTP server: archive and dated plenary folder listings, 3GPP''s lists of

        specifications arising from each TSG round, and the 3GPP change request database. Unknown values stay null.'
    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
    DocumentInfo:
      properties:
        id:
          type: integer
          title: Id
        doc_number:
          type: string
          title: Doc Number
        doc_type:
          type: string
          title: Doc Type
        version:
          type: string
          title: Version
        release:
          type: string
          title: Release
        series:
          type: string
          title: Series
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        filename:
          type: string
          title: Filename
        total_text_chunks:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Text Chunks
        total_image_chunks:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Image Chunks
        status:
          type: string
          title: Status
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
          description: When Scout indexed this version, not a 3GPP date; see provenance for those.
        provenance:
          anyOf:
          - $ref: '#/components/schemas/SpecProvenance'
          - type: 'null'
          description: When this version was uploaded to the 3GPP archive and the TSG plenary it came from, with sources. Null when the version has no provenance row yet.
      type: object
      required:
      - id
      - doc_number
      - doc_type
      - version
      - release
      - series
      - filename
      - status
      title: DocumentInfo
      description: Document metadata.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
x-refined-from:
- 3gppscout-com-openapi.json
- api.json