---
title: "Search Text"
method: POST
path: "/search/text"
tags: ["search"]
---

# Search Text

`POST /search/text`

## 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/search/text`
- Auth: none declared

Search 3GPP specification text by natural language query. This is your primary research tool.

Covers 8,700+ 3GPP document versions across all indexed releases (Rel-15 through Rel-20). Returns semantically matched text passages, reranked for precision.

**Typical workflow:**
1. Start with a broad search (e.g. query="handover procedure in NR", filter_series="38")
2. Identify the relevant document (e.g. doc_number 38.331) and section from results
3. Narrow with filter_doc_number for deeper exploration of that spec
4. Use the sections/toc tool to browse the document structure
5. Fetch full sections with the get_sections tool

**Filter strategy:** Use filter_series to scope by domain (38=NR, 23=architecture, 33=security). Use filter_doc_number when you know the spec. Use filter_release to compare evolution across releases (e.g. Rel-15 vs Rel-20). Filters are optional — omit all for the broadest search.

**Exact identifiers:** ASN.1 type, IE, AVP and Diameter command names in the query (e.g. "Ellipsoid-PointWithUncertaintyCircle", "LCS-EPS-Client-Name AVP", "AVP code 2501") are also matched literally against the clauses that define them. Those definitions come first and carry `definition`.

**Exact values:** numbers, constants, table numbers and symbol names in the query (e.g. "32400", "44.1 dB", "Table 5.2-1", "D_RX_OTA_MARGIN") are also matched literally against clause text, including numbers inside formulas. For a query that is mostly such terms, or when no meaning-based match contains them, clauses holding every term come first. Results that contain query terms carry `matched_terms`.

**Results:** Each result includes a matched text chunk (`content`) and optionally the full parent section (`section_text`). The `relevance_score` (0–1) from the reranker is the best quality signal. Always cite results as "TS 38.331 Section 5.3.5 (Rel-19)".

**Dates for prior art:** each result's `provenance` says when that version was uploaded to the 3GPP archive (UTC, from the 3GPP FTP listing) and the TSG plenary it was approved at, with source links; quote `provenance.statement` as written. Set `available_before` (e.g. a priority date) to search only versions uploaded before it. These are archive upload and approval dates, not publication dates, and they apply to the whole version, not to one clause.

## Request body

- TextSearchRequest: Request body for text search.
  - `query` string, required: Natural language search query. Be specific — e.g. 'RRC connection reconfiguration procedure' rather than just 'RRC'.
  - `match_count` integer: Candidate matches to retrieve before reranking. Higher = slower but more thorough. Default 30 balances speed and quality.
  - `match_threshold` number: Minimum similarity score. Leave at 0 (default) and rely on reranking for quality filtering.
  - `rerank` boolean: Rerank results for higher precision. Always leave true (default) — the reranker dramatically improves result quality.
  - `rerank_top_k` integer: Number of final results after reranking. Use 3–5 for focused lookups, 10–20 for broad research.
  - `include_section_text` boolean: Include the full parent section text alongside each chunk. Provides richer context but increases response size.
  - `deduplicate` boolean: Collapse near-duplicate results from different releases/versions (same doc_number + section_number), so rerank_top_k counts distinct sections. Keeps the highest-scored result (the newest release when scores tie, as identical text across releases does) and annotates it with an 'also_in' list showing each collapsed match's release, version, and scores. Ignored when filter_release is set.
  - `filter_release` string, nullable: Restrict to a specific 3GPP release. Examples: 'Rel-15', 'Rel-17', 'Rel-20'. Omit for all indexed releases (Rel-15 through Rel-20).
  - `filter_doc_type` string, nullable: Restrict by document type: 'TS' (Technical Specification) or 'TR' (Technical Report). Omit for both.
  - `filter_doc_number` string, nullable: Restrict to a specific document, e.g. '38.331' (NR RRC), '23.501' (system architecture), '38.300' (NR overview). Use the numeric format without the 'TS'/'TR' prefix.
  - `filter_series` string, nullable: Restrict by 3GPP series number: '38' = NR/5G radio, '23' = system architecture, '24' = signalling, '36' = LTE, '33' = security, '29' = core network.
  - `filter_section_number` string, nullable: Restrict to a specific section, e.g. '5.3.5'. Only useful when combined with filter_doc_number.
  - `prefer_latest` boolean: Add latest_version and latest_release (the newest indexed version of the document) to each result, and when deduplicating keep the newest matched version of each section instead of the highest-scored one.
  - `available_before` string, date, nullable: 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.
  - `include_children` boolean: Add each result's sub-clauses (number, title, token count; all of them up to 12, else the direct ones) and descendant_count, so you can pick the clause to read without a table-of-contents call.

## Response `200`

Successful Response

- TextSearchResponse: Response from text search.
  - `query` string, required
  - `results` TextResult[], required
    - `id` integer, required
    - `doc_number` string, required
    - `doc_type` string, required
    - `version` string, required
    - `release` string, required
    - `section_number` string, nullable
    - `section_title` string, nullable
    - `content` string, required
    - `content_type` string, nullable
    - `similarity` number, nullable: Vector similarity; null for a chunk found only by exact identifier or exact term match.
    - `definition` MatchedDefinition: The exact identifier from the query that this chunk defines.
      - `name` string, required: The identifier as the spec writes it, e.g. 'Ellipsoid-PointWithUncertaintyCircle'.
      - `kind` string, required: 'asn1' (Name ::= ...), 'avp', 'command' (Diameter), 'ie' (IE heading), 'heading', or 'avp_table'.
      - `code` integer, nullable: AVP or Diameter command code, when known.
      - `match` string, required: 'exact' (ignoring case), 'loose' (ignoring case, hyphens and underscores), or 'code'.
    - `matched_terms` string[], nullable: Exact numbers, constants or identifiers from the query that this chunk contains, lowercase (e.g. ['32400'], ['44.1'], ['d_rx_ota_margin']). Numbers inside formulas count.
    - `relevance_score` number, nullable
    - `section_text` string, nullable
    - `section_token_count` integer, nullable
    - `also_in` AlsoIn[], nullable
      - `release` string, required
      - `version` string, required
      - `relevance_score` number, nullable
      - `similarity` number, nullable
      - `archive_uploaded_at` string, nullable: When this version was uploaded to the 3GPP archive (ISO 8601, UTC); null when unknown.
    - `latest_version` string, nullable
    - `latest_release` string, nullable
    - `provenance` SpecProvenance: 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.
      - `statement` string, nullable: 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` string, nullable: 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` string, nullable: The zip on the 3GPP FTP server whose folder listing gives archive_uploaded_at; open its folder to verify the time.
      - `archive_date_source` string, nullable: '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` string, nullable: YYYY-MM of the plenary round whose batch of specifications includes this version (3GPP's dated folders, /ftp/Specs/YYYY-MM/).
      - `plenary_batch_source` string, nullable: '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` string, nullable: 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` string, nullable: The meeting as 3GPP names it, e.g. 'TSG SA #113'.
      - `tsg_meeting_relation` string, nullable: '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` string, date, nullable: First day of the plenary meeting.
      - `tsg_meeting_end` string, date, nullable: Last day of the plenary meeting.
      - `tsg_meeting_source` string, nullable: '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` string, nullable: The 3GPP file that names the meeting.
      - `unknown_reasons` object, nullable: 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` string, nullable: Anything a reviewer should know, e.g. the file was re-uploaded or two sources name different meetings.
    - `children` SectionChild[], nullable: With include_children: the section's sub-clauses, without text.
      - `section_number` string, required
      - `section_title` string, nullable
      - `token_count` integer, nullable
    - `descendant_count` integer, nullable: With include_children: sub-clauses at any depth.
  - `total` integer, required
  - `reranked` boolean, required
  - `elapsed_ms` number, 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)