3GPP Scout Analysis API

openapi: 3.2.0
info:
  title: 3gppscout Com Analysis API
  version: 0.2.0
  description: 'Operations tagged analysis 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: Analysis
paths:
  /analyze/proposal:
    post:
      tags:
      - Analysis
      summary: Compare Proposal
      description: 'Compare a technical proposal with the 3GPP specifications, element by element (private preview).


        Splits the text into numbered elements, searches every indexed release (Rel-15 to Rel-20) for each one, and returns per element the candidate clauses with a verbatim quote, document, section, version and release (the same citation fields as /search/text), a coverage value, the normative status of the quoted text, and a terminology bridge from the proposal''s wording to 3GPP terms. Elements without a clause worth a closer look say what was searched. Set available_before to search only versions uploaded before a date.


        A run takes about a minute. If it is not finished within wait_seconds, the response has status ''running'' and a comparison_id: call get_proposal_comparison with it. Ratings are a first pass for a qualified reviewer, not conclusions.'
      operationId: compare_proposal
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProposalComparisonRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposalComparisonResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /analyze/proposal/{comparison_id}:
    get:
      tags:
      - Analysis
      summary: Get Proposal Comparison
      description: Get the result of a proposal comparison started with compare_proposal (private preview). Polling is free. Results are kept for one hour.
      operationId: get_proposal_comparison
      parameters:
      - name: comparison_id
        in: path
        required: true
        schema:
          type: string
          title: Comparison Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposalComparisonResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TermBridge:
      properties:
        proposal_term:
          type: string
          title: Proposal Term
        standard_term:
          type: string
          title: Standard Term
        element_ids:
          items:
            type: string
          type: array
          title: Element Ids
        defined_in:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Defined In
          description: A retrieved clause that defines or normatively uses the 3GPP term.
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
      type: object
      required:
      - proposal_term
      - standard_term
      - element_ids
      title: TermBridge
    ClauseMatch:
      properties:
        doc_number:
          type: string
          title: Doc Number
        doc_type:
          type: string
          title: Doc Type
          default: TS
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        release:
          anyOf:
          - type: string
          - type: 'null'
          title: Release
        section_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Section Number
        section_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Section Title
        relevance_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Relevance Score
          description: Reranker score of the clause for this proposal's searches, as on /search/text.
        also_in:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Also In
          description: Other indexed releases and versions with the same section, as on /search/text.
        latest_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Version
        latest_release:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Release
        provenance:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Provenance
          description: When this version was uploaded to the 3GPP archive and the TSG plenary it came from, as on /search/text.
        quote:
          anyOf:
          - type: string
          - type: 'null'
          title: Quote
          description: Verbatim excerpt of the clause that corresponds to the element.
        quote_withheld:
          anyOf:
          - type: string
          - type: 'null'
          title: Quote Withheld
          description: 'Why no quote is shown: ''not_verbatim'' (the proposed quote is not in the clause text), ''excerpt_cap'' (the response reached its excerpt limit) or ''wording''.'
        normative_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Normative Status
          description: '''mandatory (shall)'', ''recommended (should)'', ''optional (may)'' or ''descriptive'', from the quoted text''s own wording.'
        capability_conditional:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Capability Conditional
          description: The quoted text applies only when a capability or feature is supported.
        rating:
          type: string
          title: Rating
          description: '''high'', ''medium'', ''low'' or ''none''.'
        rating_label:
          type: string
          title: Rating Label
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
          description: One sentence on how the clause relates to the element and what differs.
        citation:
          type: string
          title: Citation
          description: Attribution line to show with the quote.
        official_url:
          type: string
          title: Official Url
      type: object
      required:
      - doc_number
      - rating
      - rating_label
      - citation
      - official_url
      title: ClauseMatch
    ProposalElement:
      properties:
        id:
          type: string
          title: Id
          description: Stable element ID, e.g. '1pre' for the preamble, then '1a', '1b'.
        text:
          type: string
          title: Text
          description: The element, copied verbatim from the proposal.
        is_preamble:
          type: boolean
          title: Is Preamble
        is_generic:
          type: boolean
          title: Is Generic
          description: A bare hardware element (processor, memory) that specifications do not define.
        standard_query:
          anyOf:
          - type: string
          - type: 'null'
          title: Standard Query
          description: The element restated in 3GPP vocabulary, as searched.
        rating:
          type: string
          title: Rating
          description: 'Best clause rating: ''high'', ''medium'', ''low'', ''none'', or ''generic''.'
        rating_label:
          type: string
          title: Rating Label
        coverage:
          type: string
          title: Coverage
          description: '''Disclosed (express)'', ''Disclosed (interpretive)'', ''Partial'', ''Not applicable (generic hardware)'' or ''Not found (searched: ...)''.'
        searched:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Searched
          description: 'For elements without a clause worth a closer look: what was searched.'
        matches:
          items:
            $ref: '#/components/schemas/ClauseMatch'
          type: array
          title: Matches
      type: object
      required:
      - id
      - text
      - is_preamble
      - is_generic
      - rating
      - rating_label
      - coverage
      - matches
      title: ProposalElement
    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
    ProposalComparisonResponse:
      properties:
        comparison_id:
          type: string
          title: Comparison Id
        status:
          type: string
          title: Status
          description: '''complete'', ''running'' (poll get_proposal_comparison after poll_after_seconds) or ''failed''.'
        poll_after_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Poll After Seconds
        seconds_elapsed:
          type: number
          title: Seconds Elapsed
        restarted:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Restarted
          description: True when Scout restarted during the run and the comparison started again; the result is still complete.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
        result:
          anyOf:
          - $ref: '#/components/schemas/ComparisonResult'
          - type: 'null'
      type: object
      required:
      - comparison_id
      - status
      - seconds_elapsed
      title: ProposalComparisonResponse
    Overall:
      properties:
        rating:
          type: string
          title: Rating
        rating_label:
          type: string
          title: Rating Label
        elements_with_candidates:
          type: integer
          title: Elements With Candidates
        substantive_elements:
          type: integer
          title: Substantive Elements
        summary:
          type: string
          title: Summary
        uncertainty:
          items:
            type: string
          type: array
          title: Uncertainty
      type: object
      required:
      - rating
      - rating_label
      - elements_with_candidates
      - substantive_elements
      - summary
      - uncertainty
      title: Overall
    ComparisonResult:
      properties:
        input_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Kind
          description: '''structured_statement'', ''requirements_list'' or ''prose''.'
        elements:
          items:
            $ref: '#/components/schemas/ProposalElement'
          type: array
          title: Elements
        terminology:
          items:
            $ref: '#/components/schemas/TermBridge'
          type: array
          title: Terminology
        overall:
          $ref: '#/components/schemas/Overall'
        ranked_clauses:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Ranked Clauses
          description: Up to 10 clauses, most central first.
        scope:
          additionalProperties: true
          type: object
          title: Scope
          description: Releases, document types and filters searched.
        method:
          additionalProperties: true
          type: object
          title: Method
        notice:
          type: string
          title: Notice
      type: object
      required:
      - elements
      - terminology
      - overall
      - ranked_clauses
      - scope
      - method
      - notice
      title: ComparisonResult
    ProposalComparisonRequest:
      properties:
        text:
          type: string
          maxLength: 12000
          minLength: 20
          title: Text
          description: 'The proposal to compare: a requirement list, a design description, a draft contribution, or a structured statement with a preamble and numbered or semicolon-separated features. 20 to 12,000 characters; split longer documents.'
        available_before:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Available Before
          description: Only search specification versions uploaded to the 3GPP archive before this date (YYYY-MM-DD, the day itself excluded). Same rule as available_before on /search/text.
        filter_series:
          anyOf:
          - type: string
            pattern: ^\d{2}$
          - type: 'null'
          title: Filter Series
          description: Restrict every search to one 3GPP series, e.g. '38' (NR), '36' (LTE), '23' (architecture), '33' (security). Omit to search all series.
        wait_seconds:
          type: integer
          maximum: 55.0
          minimum: 0.0
          title: Wait Seconds
          description: How long to wait for the result before returning status 'running' with a comparison_id to poll. Runs usually take 40 to 90 seconds.
          default: 45
      type: object
      required:
      - text
      title: ProposalComparisonRequest
    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