3GPT API

Semantic search over 3GPP technical specifications — 3,200+ documents across multiple releases, with full text and image search powered by state-of-the-art embeddings and reranking.

The 3GPT API lets you search across the full text of 3GPP specifications using natural language. Your query is semantically matched against indexed content, reranked for precision, and returned with the matching text along with full section context.

All endpoints are read-only and require an API key for access.

Base URL

https://api.3gppscout.com

All endpoints are relative to this base URL. The API is served over HTTPS only.

Quick Start

Search for anything in the 3GPP spec corpus with a single request:

curl -X POST https://api.3gppscout.com/search/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does RRC connection setup work in NR?",
    "rerank_top_k": 5
  }'

{
  "query": "How does RRC connection setup work in NR?",
  "results": [
    {
      "id": 42,
      "doc_number": "38.331",
      "doc_type": "TS",
      "version": "19.1.0",
      "release": "Rel-19",
      "section_number": "5.3.3",
      "section_title": "RRC connection establishment",
      "content": "The purpose of this procedure is to establish an RRC connection...",
      "similarity": 0.8234,
      "relevance_score": 0.9512,
      "section_text": "...full section text..."
    }
  ],
  "total": 5,
  "reranked": true,
  "elapsed_ms": 420.3
}

That's it. The API handles search, content retrieval, and reranking in a single call.

Authentication

All API requests require a valid API key passed as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Getting an API Key

Sign in to the 3GPP Scout Dashboard and navigate to API Keys to create and manage your keys.

Error Responses

The /health, /docs, and /images endpoints do not require authentication.

Text Search

curl -X POST https://api.3gppscout.com/search/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "HARQ process for downlink in NR",
    "filter_series": "38",
    "rerank_top_k": 5
  }'

Image Search

curl -X POST https://api.3gppscout.com/search/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "random access procedure diagram",
    "match_count": 5
  }'

Combined Search

curl -X POST https://api.3gppscout.com/search/combined \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "beam management procedure in NR",
    "filter_doc_number": "38.214",
    "rerank_top_k": 5,
    "image_match_count": 3
  }'

Filtering

All search endpoints support metadata filters that narrow results before similarity matching. Filters are applied server-side for efficient pre-filtering.

Filters can be combined. For example, filter_series: "38" + filter_release: "Rel-19" searches only the latest 5G NR specs.

Reranking

Text search results are reranked by default using a cross-encoder reranking model. The flow is:

1. Embed query → retrieve match_count nearest matches (default 50)
2. Fetch the text content for each match
3. Pass query + all candidate texts to the reranker
4. Return the top rerank_top_k results sorted by relevance score

Reranked results include both similarity (semantic similarity, 0–1) and relevance_score (reranker output, 0–1). The relevance score is generally a better signal for result quality.

Set "rerank": false to skip reranking and return results sorted by similarity only.

List Documents

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.3gppscout.com/documents?doc_number=38.811"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.3gppscout.com/documents?doc_type=TR&release=Rel-19"

[
  {
    "id": 1,
    "doc_number": "38.811",
    "doc_type": "TR",
    "version": "15.4.0",
    "release": "Rel-15",
    "series": "38",
    "title": null,
    "filename": "38811-f40.zip",
    "total_text_chunks": 812,
    "total_image_chunks": 45,
    "status": "complete"
  }
]

Get Document

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.3gppscout.com/documents/42

Get Sections

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.3gppscout.com/sections?section_number=5.3.3&doc_number=38.331&release=Rel-19"

Table of Contents

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.3gppscout.com/sections/toc?doc_number=38.321"

Get Image

# 1. Search for images
curl -X POST https://api.3gppscout.com/search/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "user plane protocol stack", "filter_doc_number": "38.300"}'

# Response includes: "image_path": "/images/38.300/19.1.0/8"

# 2. Fetch the image (no auth needed)
curl https://api.3gppscout.com/images/38.300/19.1.0/8 --output figure.png

<img src="https://api.3gppscout.com/images/38.300/19.1.0/8"
     alt="User Plane Protocol Stack (TS 38.300)" />

MCP Server

The 3GPP Scout API includes an MCP (Model Context Protocol) server, allowing AI agents in Cursor, Claude Desktop, VS Code, and other MCP clients to use the API as a tool directly.

Add to Cursor (one click)

Add to Cursor

Clicking the button opens Cursor and installs the 3GPP Scout MCP server automatically.

Manual Configuration

For Cursor, add to .cursor/mcp.json in your workspace or user settings:

{
  "mcpServers": {
    "3gpp-scout": {
      "url": "https://api.3gppscout.com/mcp/",
      "transport": "streamable-http"
    }
  }
}

For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "3gpp-scout": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.3gppscout.com/mcp/"
      ]
    }
  }
}

Authentication

The MCP server uses OAuth 2.1 — no API key is needed in the config. On first use, your browser will open for you to sign in with your 3GPP Scout account. After approving access, the MCP client handles tokens automatically.

Available Tools

Once connected, your agent has access to all API endpoints as MCP tools:

• search_text — semantic search over specification text
• search_images — search diagrams, figures, and tables
• search_combined — text + image search in one call
• list_documents / get_document — browse available documents
• get_sections / list_sections — fetch section text and table of contents
• get_image — fetch extracted figures as PNG images

MCP Resource

The MCP server also provides a scout://skill-guide resource — a comprehensive guide your agent can read to understand the API, recommended workflows, and best practices.

Skill File

For agents that don't support MCP, we provide a Skill File — a standalone markdown document containing everything an LLM agent needs to use the API effectively: endpoints, parameters, workflows, and tips.

Download

https://api.3gppscout.com/skill.md

How to Use

1. Download or copy the file from the link above
2. Save it as SKILL.md in your project (e.g. .cursor/skills/3gpp-scout/SKILL.md)
3. Your agent will read it automatically and know how to call the API

The skill file covers the same information as the MCP resource (scout://skill-guide) but works with any agent framework — just include it in the agent's context.

OpenClaw

The 3GPP Scout skill is published on ClawHub, the skill registry for OpenClaw. If you use an OpenClaw-compatible agent, you can install the skill directly from the registry.

Install

https://clawhub.ai/chriscarrotlabs/3gpp-scout

Configure your API key

Once installed, set your API key as the SCOUT_API_KEY environment variable:

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

Or add it to ~/.openclaw/openclaw.json under skills."3gpp-scout".env.SCOUT_API_KEY.

The ClawHub listing has passed OpenClaw's security scan (benign, high confidence) and is updated whenever the skill file here changes.

Models & Embeddings

The API uses three Voyage AI models:

Text chunks are contextualized embeddings — each chunk is embedded along with metadata about the document and section it belongs to, improving retrieval quality for domain-specific queries.

Architecture

The API is a stateless server backed by cloud infrastructure:

  Client Request
       │
       ▼
  ┌──────────────────────┐
  │      3GPT API        │  api.3gppscout.com
  └──────────┬───────────┘
             │
   ┌─────────┼──────────┬──────────┐
   ▼         ▼          ▼          ▼
Embedding   Vector     Content    Image
 Model      Search     Store      Store
                     (text/JSON)  (PNGs)

Request flow for text search:

1. Embed the query string using the text embedding model
2. Run vector similarity search with optional metadata filters
3. Resolve matches to their source document and chunk
4. Fetch chunk text and section context
5. Optionally rerank candidates for higher precision
6. Return the final results

Request flow for image serving:

1. Image search returns results with image_path (e.g. /images/38.300/19.1.0/8)
2. Client fetches the image URL directly
3. API proxies the PNG from Google Cloud Storage

Corpus Coverage

The current index covers two complete 3GPP releases:

Additional releases (Rel-16 through Rel-18, Rel-20) are being processed and will be added incrementally.

Processing Pipeline

Each document goes through a multi-stage pipeline: parsing, semantic chunking, embedding, section extraction, and image extraction. The chunking stage produces optimized chunks of 400–800 tokens for high-quality retrieval. Images are extracted as individual PNGs and served via the /images endpoint.

Health Check

curl https://api.3gppscout.com/health

{
  "status": "ok",
  "version": "0.2.0",
  "models": {
    "text_embedding": "voyage-context-3",
    "image_embedding": "voyage-multimodal-3",
    "reranker": "rerank-2"
  }
}

OpenAPI / Swagger

The auto-generated interactive API docs are available at /swagger (Swagger UI) and /redoc (ReDoc). The raw OpenAPI schema is at /openapi.json.