3GPP Scout

Semantic search over the full 3GPP TS/TR corpus (Rel-15 through Rel-20, 8,700+ document versions). The hosted index stays current as 3GPP publishes new and revised specs. Search text, diagrams, and figures across 2.6M+ text vectors. Hosted MCP at https://api.3gppscout.com/mcp/.

3GPP Scout API — Agent Skill Guide

You have access to the 3GPP Scout API, a semantic search engine over 3GPP technical specifications. Use it to find specific information in 3GPP standards documents (TS and TR series).

Provider & Pricing

Provider: Carrot Labs Homepage: 3gppscout.com Dashboard: dashboard.3gppscout.com API Docs: api.3gppscout.com/docs Terms of Service: 3gppscout.com/terms Privacy Policy: 3gppscout.com/privacy

Direct REST, MCP, and BYOK hosted-chat retrieval share a monthly request allowance. The Explorer plan includes 150 requests per UTC calendar month. Founding Engineer includes 1,000 requests per calendar month for $8/month. Enterprise limits follow the active agreement. View usage or upgrade at dashboard.3gppscout.com/dashboard/billing.

Base URL

text

https://api.3gppscout.com

Authentication

All search and document endpoints require a Bearer token (API key).

How to get an API key:

1. Sign up or log in at dashboard.3gppscout.com
2. Go to the API Keys page
3. Create a new key — it will start with sk-

Set your API key via environment variable:

text

export SCOUT_API_KEY="sk-your-key-here"

Or set skills."3gpp-scout".apiKey / skills."3gpp-scout".env.SCOUT_API_KEY in ~/.openclaw/openclaw.json.

The key is included in every request as a Bearer token:

text

Authorization: Bearer $SCOUT_API_KEY

MCP Agent Setup

For Cursor, Claude, Codex, or another MCP client, fetch and follow:

text

https://api.3gppscout.com/agent-setup/prompt.md

The hosted Streamable HTTP MCP URL is:

text

https://api.3gppscout.com/mcp/

MCP uses OAuth 2.1, so no Scout API key belongs in the MCP configuration. The first connection or tool call opens a browser for sign-in. After authorization, verify the connection by calling list_documents with doc_number="38.331" and release="Rel-19"; keep both filters so verification returns a small list.

Monthly Quota Exhaustion

REST API keys, OAuth-authenticated MCP tools, and BYOK hosted-chat retrieval share the same request allowance. Regular Scout-funded hosted chat uses prepaid credits instead. If a tool or endpoint returns HTTP 402, inspect the error's detail object. The stable machine-readable code is api_quota_exhausted, and the response includes:

• current_plan
• used, limit, and remaining
• reset_at as a UTC timestamp
• upgrade.plan (Founding Engineer)
• upgrade.price (8 USD per month)
• upgrade.requests_per_month (1000)
• upgrade.url (https://dashboard.3gppscout.com/dashboard/billing)

Do not retry repeatedly while remaining is zero. Wait until reset_at or present the absolute upgrade.url to the user. FastMCP-generated tools expose the same FastAPI error payload.

Available Endpoints

POST /search/text

Semantic search over specification text. This is your primary tool.

Request body (JSON):

Parameter	Type	Default	Description
query	string	—	Required. Natural language search query
match_count	int	30	Candidate matches before reranking (1–200)
match_threshold	float	0.0	Minimum similarity score (0–1)
rerank	bool	true	Rerank results for higher precision
rerank_top_k	int	10	Results to keep after reranking (1–50)
include_section_text	bool	true	Include the full parent section text
deduplicate	bool	true	Collapse duplicates across releases/versions; see also_in
filter_release	string	null	e.g. "Rel-19", "Rel-15"
filter_doc_type	string	null	"TS" or "TR"
filter_doc_number	string	null	e.g. "38.331", "23.501"
filter_series	string	null	e.g. "38" (NR/5G), "23" (system architecture)
filter_section_number	string	null	e.g. "5.3.3"

Response fields:

Field	Type	Description
query	string	Echo of the search query
results	TextResult[]	Matching text chunks
total	int	Number of results returned
reranked	bool	Whether reranking was applied
elapsed_ms	float	Server processing time in ms

Each TextResult contains:

• doc_number, doc_type, version, release — document metadata
• section_number, section_title — which section the chunk is from
• content — the matched text chunk
• similarity — semantic similarity score (0–1)
• relevance_score — reranker score (0–1), present when reranked
• section_text — full parent section text (when include_section_text=true)
• section_token_count — token count of the parent section
• also_in — when deduplicate is true, other releases/versions that matched the same section (each entry has release, version, and scores)

POST /search/images

Semantic search over figures, diagrams, and tables in specifications.

Request body (JSON):

Parameter	Type	Default	Description
query	string	—	Required. Natural language query
match_count	int	10	Number of results (1–50)
match_threshold	float	0.3	Minimum similarity (0–1)
deduplicate	bool	true	Collapse duplicates across releases/versions; see also_in
filter_release	string	null	e.g. "Rel-19"
filter_doc_number	string	null	e.g. "38.300"
filter_series	string	null	e.g. "38"

Each ImageResult contains:

• doc_number, doc_type, version, release — document metadata
• section_number — which section the image is in
• caption — figure/table caption
• context_before, context_after — surrounding text
• image_path — path to the image file
• similarity — semantic similarity score
• also_in — when deduplicate is true, other releases/versions for the same figure (each entry has release, version, and similarity)

POST /search/combined

Text + image search in a single request. Useful for broad questions where both text passages and diagrams are relevant.

Request body (JSON):

Parameter	Type	Default	Description
query	string	—	Required. Natural language query
text_match_count	int	30	Text candidates before reranking (1–200)
text_match_threshold	float	0.0	Text similarity threshold (0–1)
rerank	bool	true	Rerank text results
rerank_top_k	int	10	Text results after reranking (1–50)
include_section_text	bool	true	Include full parent section text
image_match_count	int	5	Image results to return (1–50)
image_match_threshold	float	0.0	Image similarity threshold (0–1)
filter_release	string	null	Filter both searches by release
filter_doc_type	string	null	Filter text search by doc type
filter_doc_number	string	null	Filter both searches by document
filter_series	string	null	Filter both searches by series
filter_section_number	string	null	Filter text search by section

Response has text_results (TextResult[]) and image_results (ImageResult[]).

GET /documents

List available 3GPP documents with metadata. Use filters to check if a specific document or release is indexed — this is fast (1-2 lookups). Without filters returns all ~3,200 documents which is slower.

Query parameters:

Parameter	Type	Default	Description
doc_number	string	null	Filter by document number, e.g. "38.811". Recommended.
release	string	null	Filter by release, e.g. "Rel-19"
series	string	null	Filter by series, e.g. "38"
doc_type	string	null	Filter by type: "TS" or "TR"

Example: Check if TR 38.811 has a Rel-19 version:

text

GET /documents?doc_number=38.811&release=Rel-19

GET /documents/{document_id}

Get a single document by its numeric ID.

GET /sections

Fetch full section text by section number.

Query parameters:

Parameter	Type	Default	Description
section_number	string	—	Required. Numeric (5.3.3), trailing-letter (5.3.1a), or annex (A.1, B.2.3)
doc_number	string	—	Required. e.g. 38.331, 23.501
version	string	null	e.g. 19.1.0
release	string	null	e.g. Rel-19
prefix	bool	false	Match sub-sections too — works for numeric (5.4 → 5.4.1) and annex (A → A.1)

Behavior on no match: Returns HTTP 200 with an empty list []. If you get an empty list, call GET /sections/toc?doc_number=… to see the document's actual section IDs — your section number may use a different form (e.g. annex letter case, or the doc isn't indexed yet).

GET /sections/toc

Table of contents for a document — section numbers and titles without full text.

Query parameters:

Parameter	Type	Default	Description
doc_number	string	—	Required. e.g. "38.321"
version	string	null	e.g. "19.1.0"

GET /images/{doc_number}/{version}/{image_index}

Fetch an extracted image (PNG) from a specification. No authentication required.

The image_path field in image search results (e.g. /images/38.300/19.1.0/5) maps directly to this endpoint. Construct the full URL as:

text

https://api.3gppscout.com/images/{doc_number}/{version}/{image_index}

Returns image/png on success, 404 if the image doesn't exist.

Corpus Coverage

The index covers the full published TS/TR corpus for Rel-15 through Rel-20 — not a Rel-15 + Rel-19 subset. Production currently serves 8,700+ document versions, 1.3M+ sections, 2.6M+ text vectors, and 225K+ image vectors.

The corpus is kept current with the 3GPP source: new and bumped specifications are discovered, processed, and merged into the live search index (incremental apply for spec updates; full Vertex rebuilds on a monthly cadence). Do not treat the index as frozen at an older release pair.

The /sections artifacts for the production corpus were refreshed after the annex-heading parser fix, so annex sections such as A.1 are available via GET /sections when the caller provides doc_number.

Series 38 = NR/5G, 23 = system architecture, 24 = signaling protocols, 36 = LTE, 33 = security, 29 = core network protocols.

Recommended Workflows

Finding specific technical details

1. Use POST /search/text with a focused query and rerank_top_k: 5
2. Read the content field for the matched chunk
3. Read section_text for the full section context
4. If you need the broader document structure, call GET /sections/toc with the doc_number from the result

Exploring a specific document

1. Get the table of contents: GET /sections/toc?doc_number=38.331
2. Fetch a specific section: GET /sections?section_number=5.3.3&doc_number=38.331
3. Annex sections work the same way: GET /sections?section_number=A.1&doc_number=38.874
4. Use prefix=true to get a section and all its sub-sections

Broad topic research

1. Use POST /search/combined to get both text and diagrams
2. Use filter_series to narrow to a domain (e.g. "38" for NR)
3. Increase rerank_top_k to 15–20 for more diverse results

Comparing across releases

1. Search with filter_release: "Rel-15" for an earlier release
2. Search again with filter_release: "Rel-20" (or another release) for a later version
3. Compare the section text to see what changed

Tips for Best Results

• Always use reranking (enabled by default). The relevance_score from the reranker is a much better quality signal than raw similarity.
• Use filters to narrow scope. If you know which spec you're looking for, filter_doc_number dramatically improves result quality.
• Use include_section_text: true (the default) to get the full parent section. The content field is a chunk (~400-800 tokens), while section_text gives the complete section for full context.
• Cite results precisely. When presenting results to users, always include the document number, section number, and release. For example: "According to TS 38.331 Section 5.3.3 (Rel-19)..."
• Use the TOC endpoint before diving deep into a document. It helps you understand the document structure and find the right section numbers.
• Prefer /search/text over /search/combined when you only need text. Combined search is slower because it queries both indexes.
• Don't set match_threshold too high. The default of 0.0 with reranking gives the best results. The reranker handles quality filtering.
• Render images from search results. Image search results include image_path (e.g. /images/38.300/19.1.0/5). Construct the full URL: https://api.3gppscout.com{image_path}. No authentication required.

Data & Privacy

Queries you send to this API are processed by the 3GPP Scout service to perform vector search. The API does not store your queries beyond transient usage logs for billing. The corpus consists entirely of publicly available 3GPP specifications — no proprietary or user-supplied data is stored in the search index. See 3gppscout.com/privacy for the full privacy policy.