Search API

The Search API provides hybrid vector + lexical retrieval across all indexed wiki content, with optional cross-encoder reranking and per-chunk paid access. Content is automatically chunked, embedded, and indexed when articles are published.

Base URL

https://search.zing.services/

Authentication

The Search API has two access modes:

Free Access (Internal App)

Our web app uses these endpoints via backend proxy:

Header	Value
`X-App-Key`	Your `APP_API_KEY`

Paid Access (Public API)

External developers pay per request via USDC on Sui:

Sign an ApiAccessMessage with your Sui wallet
Send USDC to the platform address
Include signature, bytes, and transaction_digest in the request

How Search Works

Content is indexed through a multi-stage RAG pipeline:

Query
  │
  ├──► Vector Search (pgvector HNSW, 256-dim)
  │    - Embedding via potion-multilingual-128M
  │    - Cosine similarity, top candidates
  │
  ├──► Lexical Search (pg_bigm + ts_rank_cd)
  │    - Bigram ILIKE + PostgreSQL full-text
  │
  └──► RRF Merge (k=60) → Cross-encoder Rerank
       - bge-reranker-v2-m3 (ONNX quantized)
       - Content-type-aware blending (prose/code/table)
       - Score threshold filter (min 0.15)

Chunking Strategy

Articles are split into chunks using markdown-aware chunking:

Property	Description
Target	~200 tokens per chunk, ~25 token overlap
Types	`prose`, `code`, `table`
Atomic	Code blocks and tables are never split
Excerpts	Prose: 280 chars, Code: 400 chars, Table: header + 3 rows

Each chunk stores full chunk_text and a truncated excerpt. Use the expand endpoint to retrieve full untruncated text.

GET/search

Global Search (Free)

Search across all indexed wikis. Returns top results sorted by relevance score.

Query parameters

Name
q
Type
string
Description
Search query.
Name
limit
Type
integer
Description
Max results (default: 20).

Results are filtered server-side — chunks with relevance_score < 0.15 are excluded.

Request

GET

/search

curl "https://search.zing.services/search?q=what+is+DeFi&limit=5" \
  -H "X-App-Key: $APP_API_KEY"

GET/query

Wiki Search (Free)

Search within a specific wiki's content. Returns results with results, total, and wiki_tags.

Query parameters

Name
wiki
Type
string
Description
Owner address (e.g., 0x123...).
Name
q
Type
string
Description
Search query.
Name
mode
Type
string
Description
Search mode: vector, lexical, or hybrid (default).
Name
limit
Type
integer
Description
Max results (default: 20).
Name
rerank
Type
string
Description
Reranker: cross-encoder-onnx (default), embedding, heuristic.

Request

GET

/query

curl "https://search.zing.services/query?wiki=0x32c21ad0de99fd2150a231fab36f4c0b2e55a95d6c3e367621870fb33bdb2389&q=Web3" \
  -H "X-App-Key: $APP_API_KEY"

POST/search

Paid Global Search

Search across all indexed wikis with per-result pricing. Requires a signed ApiAccessMessage and an on-chain USDC payment.

Cost structure

Flat search fee: $0.0005 (for limit ≤ 20, scales linearly for larger limits)
Per-result fee: based on token count × base rate ($0.0004 per 1K tokens) + creator content fees
Results returned greedily within budget (highest relevance first)

Request body

Name
q
Type
string
Description
Search query.
Name
wiki
Type
string
Description
global or owner address.
Name
limit
Type
integer
Description
Max results (capped at 50).
Name
transaction_digest
Type
string
Description
Sui transaction digest.
Name
signature
Type
string
Description
Base64-encoded signature.
Name
bytes
Type
string
Description
Base64-encoded BCS ApiAccessMessage.

Request

POST

/search

curl -X POST https://search.zing.services/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "what is DeFi?",
    "wiki": "global",
    "limit": 20,
    "transaction_digest": "8xK2...",
    "signature": "base64_sig...",
    "bytes": "base64_bcs..."
  }'

POST/chunks

Paid Chunk Retrieval

Retrieve semantic chunks with per-chunk pricing. Returns chunks greedily accumulated within budget (highest relevance first).

Cost structure

Flat infrastructure fee: $0.0005 (limit ≤ 20)
Per-chunk base fee: chunk_tokens / 1000 × $0.0004
Per-chunk content fee: chunk_tokens / 1000 × creator_rate (0 if subscribed)

Request body

Name
q
Type
string
Description
Search query.
Name
wiki
Type
string
Description
global or owner address.
Name
limit
Type
integer
Description
Max results (capped at 50).
Name
expand
Type
boolean
Description
When true, returns full chunk_text instead of excerpt (no additional charge).
Name
article_ids
Type
array
Description
Optional filter to specific article IDs.
Name
transaction_digest
Type
string
Description
Sui transaction digest.
Name
signature
Type
string
Description
Base64-encoded signature.
Name
bytes
Type
string
Description
Base64-encoded BCS ApiAccessMessage.

Request

POST

/chunks

curl -X POST https://search.zing.services/chunks \
  -H "Content-Type: application/json" \
  -d '{
    "q": "what is Web3?",
    "wiki": "global",
    "limit": 10,
    "expand": false,
    "article_ids": null,
    "transaction_digest": "0xabc...",
    "signature": "sig...",
    "bytes": "bcs..."
  }'

POST/chunk/expand

Expand Chunks (Paid)

Retrieve the full untruncated text for up to 20 chunks by their IDs. Requires a signed ExpandAccessMessage and an on-chain USDC payment.

Request body

Name
chunk_ids
Type
array
Description
Chunk IDs to expand (max 20).
Name
transaction_digest
Type
string
Description
Sui transaction digest.
Name
signature
Type
string
Description
Base64-encoded signature.
Name
bytes
Type
string
Description
Base64-encoded BCS ExpandAccessMessage.

Request

POST

/chunk/expand

curl -X POST https://search.zing.services/chunk/expand \
  -H "Content-Type: application/json" \
  -d '{
    "chunk_ids": [1603, 94, 1802],
    "transaction_digest": "5KzN...",
    "signature": "AM3x...",
    "bytes": "BQAAAGNo..."
  }'

GET/search/formula

Search Formula

Returns the exact scoring weights used in the search pipeline. No authentication required.

Scoring constants

Constant	Value	Description
`RRF_K`	60	RRF rank smoothing parameter
`RRF_RAW_WEIGHT`	0.5	Raw similarity weight in RRF
`CROSS_ENCODER_ORIGINAL`	0.2	RRF score weight in final
`CROSS_ENCODER_SCORE`	0.8	Cross-encoder score weight
`DEFAULT_MIN_SCORE`	0.15	Minimum relevance threshold
Prose: doc=0.6, passage=0.4
Code: doc=0.3, passage=0.7
Table: doc=0.3, passage=0.7

Request

GET

/search/formula

curl https://search.zing.services/search/formula

GET/chunk/config/:address

Creator Fee Configuration

Content fees are level-based. Each article has a subscription_level (0-2). Creators set different fees per level. Get the effective fee for each level.

Response fields

Name
fee_per_1k_tokens_usdc
Type
object
Description
Map of level → fee per 1K tokens (in micro-USDC). Uses creator's configured fee if set, otherwise platform default (800 = $0.0008).
Name
search_enabled
Type
boolean
Description
Whether the wiki is included in global search.

Use PUT /chunk/config to set fee levels and PUT /chunk/config/enabled to toggle search visibility. Both require a Sui wallet signature.

Request

GET

/chunk/config/0x1aa2...

curl https://search.zing.services/chunk/config/0x1aa2c40369fa0fffb12fe6e1415b8aba52d15cc3cf59e001adc5d2687920fbd6

GET/tags/*

Endpoint	Description
`GET /tags/:owner`	Get tags for a specific wiki
`POST /tags/batch`	Get tags for multiple wikis
`GET /tags/trending`	Global trending tags
`GET /tags/:tag/articles`	Articles matching a tag
`GET /creators/:tag`	Creators matching a tag

Indexing

Content is automatically indexed via a background batch scheduler. The following endpoints allow creators to manage their own indexed content.

Endpoints

Name
GET /index/:owner/status
Type
public
Description
Check indexing status: pending, indexing, ready, or error.
Name
POST /index/:owner/articles
Type
signature
Description
Index specific articles. Requires Sui wallet signature with on-chain ownership verification.
Name
DELETE /index/:owner/articles/:id
Type
signature
Description
Remove indexed content for an article destroyed on-chain. Requires Sui wallet signature.

Request

GET

/index/:owner/status

curl https://search.zing.services/index/0x32c21ad0de99fd2150a231fab36f4c0b2e55a95d6c3e367621870fb33bdb2389/status

Technical Details

Component	Technology
Web framework	Axum (Rust, tokio)
Database	PostgreSQL 16+
Vector search	pgvector (HNSW, cosine, 256-dim)
Lexical search	pg_bigm (bigram GIN index) + ts_rank_cd
Embedding model	minishlab/potion-multilingual-128M
Cross-encoder	onnx-community/bge-reranker-v2-m3-ONNX
Blockchain	Sui (RPC, BCS deserialization)
Blob storage	Walrus (content download)
Encryption	Seal (decryption via sui-sdk)

Chunking and Excerpt Types

Type	Excerpt Strategy	Max Chars
Prose	Strip markdown, truncate at sentence boundary	280
Code	Line-boundary truncation, preserve syntax	400
Table	Header + first 3 data rows + "(N more rows)"	3 rows

When a chunk's excerpt is truncated, the response includes a truncated field with metadata about what was shortened. Use POST /chunk/expand to retrieve full untruncated text.

Next Steps

Pay-Per-Query API - Learn how to pay for chunk access
CLI - CLI tool for paid search and chunk retrieval
MCP Server - AI agent MCP integration
Attribution Ledger - Track AI usage
Synthesis - Multi-source research engine

Search API

Free Access (Internal App)

Paid Access (Public API)

Query parameters

Request

Query parameters

Request

Cost structure

Request body

Request

Cost structure

Request body

Request

Request body

Request

Scoring constants

Request

Response fields

Request

Available endpoints

Request

Endpoints

Request