---
title: "Compare Proposal"
method: POST
path: "/analyze/proposal"
tags: ["analysis"]
---

# Compare Proposal

`POST /analyze/proposal`

## Request

- Base URL: `https://api.3gppscout.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.3gppscout.com/analyze/proposal`
- Auth: none declared

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.

## Request body

- ProposalComparisonRequest
  - `text` string, required: 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` string, date, nullable: 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` string, nullable: Restrict every search to one 3GPP series, e.g. '38' (NR), '36' (LTE), '23' (architecture), '33' (security). Omit to search all series.
  - `wait_seconds` integer: How long to wait for the result before returning status 'running' with a comparison_id to poll. Runs usually take 40 to 90 seconds.

## Response `200`

Successful Response

- ProposalComparisonResponse
  - `comparison_id` string, required
  - `status` string, required: 'complete', 'running' (poll get_proposal_comparison after poll_after_seconds) or 'failed'.
  - `poll_after_seconds` integer, nullable
  - `seconds_elapsed` number, required
  - `restarted` boolean, nullable: True when Scout restarted during the run and the comparison started again; the result is still complete.
  - `message` string, nullable
  - `result` ComparisonResult
    - `input_kind` string, nullable: 'structured_statement', 'requirements_list' or 'prose'.
    - `elements` ProposalElement[], required
      - `id` string, required: Stable element ID, e.g. '1pre' for the preamble, then '1a', '1b'.
      - `text` string, required: The element, copied verbatim from the proposal.
      - `is_preamble` boolean, required
      - `is_generic` boolean, required: A bare hardware element (processor, memory) that specifications do not define.
      - `standard_query` string, nullable: The element restated in 3GPP vocabulary, as searched.
      - `rating` string, required: Best clause rating: 'high', 'medium', 'low', 'none', or 'generic'.
      - `rating_label` string, required
      - `coverage` string, required: 'Disclosed (express)', 'Disclosed (interpretive)', 'Partial', 'Not applicable (generic hardware)' or 'Not found (searched: ...)'.
      - `searched` string[], nullable: For elements without a clause worth a closer look: what was searched.
      - `matches` ClauseMatch[], required
        - `doc_number` string, required
        - `doc_type` string
        - `version` string, nullable
        - `release` string, nullable
        - `section_number` string, nullable
        - `section_title` string, nullable
        - `relevance_score` number, nullable: Reranker score of the clause for this proposal's searches, as on /search/text.
        - `also_in` object[], nullable: Other indexed releases and versions with the same section, as on /search/text.
        - `latest_version` string, nullable
        - `latest_release` string, nullable
        - `provenance` object, nullable: When this version was uploaded to the 3GPP archive and the TSG plenary it came from, as on /search/text.
        - `quote` string, nullable: Verbatim excerpt of the clause that corresponds to the element.
        - `quote_withheld` string, nullable: 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` string, nullable: 'mandatory (shall)', 'recommended (should)', 'optional (may)' or 'descriptive', from the quoted text's own wording.
        - `capability_conditional` boolean, nullable: The quoted text applies only when a capability or feature is supported.
        - `rating` string, required: 'high', 'medium', 'low' or 'none'.
        - `rating_label` string, required
        - `note` string, nullable: One sentence on how the clause relates to the element and what differs.
        - `citation` string, required: Attribution line to show with the quote.
        - `official_url` string, required
    - `terminology` TermBridge[], required
      - `proposal_term` string, required
      - `standard_term` string, required
      - `element_ids` string[], required
      - `defined_in` object, nullable: A retrieved clause that defines or normatively uses the 3GPP term.
      - `note` string, nullable
    - `overall` Overall, required
      - `rating` string, required
      - `rating_label` string, required
      - `elements_with_candidates` integer, required
      - `substantive_elements` integer, required
      - `summary` string, required
      - `uncertainty` string[], required
    - `ranked_clauses` object[], required: Up to 10 clauses, most central first.
    - `scope` object, required: Releases, document types and filters searched.
    - `method` object, required
    - `notice` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/3gppscout/apis/3gpp-scout-api.md) · [All operations](https://skmtc.dev/3gppscout/apis/3gpp-scout-api/llms.txt) · [OpenAPI document](https://skmtc.dev/3gppscout/apis/3gpp-scout-api/revisions/60bd6896e5b9?raw)