API Documentation

Vectorize provides a REST API for converting document chunks into vector embeddings. Designed for programmatic access by AI agents with x402 micropayments on Solana.

For AI Agents

This API is designed for machine-to-machine access. No API keys required. Authentication is handled via x402 payment protocol - include a valid Solana transaction signature in the X-PAYMENT header.

Overview

Base URL: https://api.vectorize.cc

All requests should use HTTPS. The API accepts JSON and multipart form data, and returns JSON responses.

Quick Start (Agent Flow)

# 1. Get price estimate
curl -X POST https://api.vectorize.cc/estimate \
  -H "Content-Type: application/json" \
  -d '{"chunks": ["Hello world", "Test chunk"], "tier": "pro"}'

# 2. Send USDC payment on Solana (programmatic)
# Transfer {price_usdc} to 8hTmULLrTpXJxpebL246N4aCo4cqxHTpTrKJyRxeDdWT

# 3. Call vectorize with payment signature
curl -X POST https://api.vectorize.cc/vectorize/pro \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <solana-tx-signature>" \
  -d '{"chunks": ["Hello world", "Test chunk"]}'

Authentication

Vectorize uses the x402 payment protocol for authentication. Instead of API keys, you pay per request with USDC on Solana.

Free Tier

The script tier is free (100 chunks/day limit). No payment or headers required.

Paid Tiers

For paid tiers, include the X-PAYMENT header with a valid Solana transaction signature:

X-PAYMENT: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9g...

x402 Payment Flow

The x402 protocol enables machine-to-machine payments. Here's the flow:

Estimate: Call POST /estimate with your chunks to get the exact USDC cost
Pay: Execute a Solana USDC transfer to 8hTmULLrTpXJxpebL246N4aCo4cqxHTpTrKJyRxeDdWT
Submit: Call the vectorize endpoint with X-PAYMENT header containing the TX signature
Verify: Server verifies payment on-chain and processes your request

Payment Configuration

Network: Solana Mainnet
Asset: USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)
Recipient: 8hTmULLrTpXJxpebL246N4aCo4cqxHTpTrKJyRxeDdWT
Decimals: 6 (1 USDC = 1,000,000 micro-units)

GET /

GET / Free

Returns API information and x402 configuration. Use this to discover payment details programmatically.

Response

{
  "service": "Vectorize",
  "version": "1.0.0",
  "x402": {
    "enabled": true,
    "network": "solana-mainnet",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "asset_name": "USDC",
    "decimals": 6
  },
  "payTo": "8hTmULLrTpXJxpebL246N4aCo4cqxHTpTrKJyRxeDdWT",
  "pricing": {
    "script": "FREE (100 chunks/day) - all-MiniLM-L6-v2",
    "agent": "$0.0005/chunk - all-MiniLM-L6-v2, unlimited",
    "pro": "$0.001/chunk - text-embedding-3-small",
    "pro_plus": "$0.01/chunk - text-embedding-3-large + enrichment"
  }
}

GET /health

GET /health Free

Health check endpoint. Returns service status.

{ "status": "healthy", "network": "solana-mainnet" }

GET /models

GET /models Free

List all available embedding models and their tier assignments.

{
  "models": [
    {
      "id": "all-MiniLM-L6-v2",
      "dimensions": 384,
      "tiers": ["script", "agent"],
      "provider": "local"
    },
    {
      "id": "text-embedding-3-small",
      "dimensions": 1536,
      "tiers": ["pro"],
      "provider": "openai"
    },
    {
      "id": "text-embedding-3-large",
      "dimensions": 3072,
      "tiers": ["pro-plus"],
      "provider": "openai"
    }
  ]
}

POST /estimate

POST /estimate Free

Get price estimate before making payment. Returns cost for each tier.

Request Body

Parameter	Type	Description
chunks required	string[]	Array of text chunks to embed
tier	string	Tier: script, agent, pro, pro-plus (default: agent)

Response

{
  "success": true,
  "chunks": 10,
  "tier": "pro",
  "model": "text-embedding-3-small",
  "dimensions": 1536,
  "price_usdc": 10000,
  "price_usd": 0.01
}

POST /vectorize/{tier}

POST /vectorize/{tier} Paid*

Convert text chunks to vector embeddings. Tier determines pricing and features.

Path Parameters

Parameter	Values
tier	`script` \| `agent` \| `pro` \| `pro-plus`

Headers

Header	Description
X-PAYMENT	Solana TX signature (required for paid tiers)

Request Body

Parameter	Type	Description
chunks required	string[]	Array of text chunks to embed
output_format	string	Output format (json, chroma, pinecone, etc.)
response_mode	string	`full` (default) or `lite`. Lite mode returns only metadata + download URL - recommended for large requests.

Note: Model is locked per tier. No model selection needed.

Response (full mode)

{
  "success": true,
  "tier": "pro",
  "model": "text-embedding-3-small",
  "output_format": "json",
  "total_vectors": 2,
  "dimensions": 1536,
  "vectors": [...],
  "download_url": "https://api.vectorize.cc/results/pro_abc123...",
  "expires_in": "60 minutes"
}

Response (lite mode - for large files)

{
  "success": true,
  "tier": "pro",
  "model": "text-embedding-3-small",
  "total_vectors": 500,
  "dimensions": 1536,
  "response_mode": "lite",
  "download_url": "https://api.vectorize.cc/results/pro_abc123...",
  "expires_in": "60 minutes",
  "message": "Vectors saved. Use download_url to retrieve full results."
}

Use response_mode: "lite" for large requests (100+ chunks). Vectors are stored server-side for 1 hour and can be downloaded via the download_url.

POST /vectorize/upload/{tier}

POST /vectorize/upload/{tier} Paid*

Upload a JSON file containing chunks to vectorize. Alternative to sending chunks in request body - useful for large datasets.

Path Parameters

Parameter	Values
tier	`script` \| `agent` \| `pro` \| `pro-plus`

Form Data

Field	Type	Description
file required	file	JSON file (max 50MB)
output_format	string	Output format (default: json)

File Format

{
  "chunks": ["text chunk 1", "text chunk 2", ...],
  "metadata": [{"key": "value"}, ...],  // optional
  "namespace": "my-namespace"  // optional
}

Example (curl)

# Free tier (script)
curl -X POST https://api.vectorize.cc/vectorize/upload/script \
  -F "file=@chunks.json" \
  -F "output_format=pinecone"

# Paid tier with payment
curl -X POST https://api.vectorize.cc/vectorize/upload/pro \
  -H "X-PAYMENT: <solana-tx-signature>" \
  -F "file=@chunks.json" \
  -F "output_format=chroma"

GET /results/{id}

GET /results/{id} Free

Download previously generated results by ID. Results are cached for 24 hours after generation.

Path Parameters

Parameter	Description
id	Result ID returned from vectorize endpoint

GET /rpc/blockhash

GET /rpc/blockhash Free

Proxy endpoint for getting the latest Solana blockhash. Useful for constructing transactions without needing your own RPC endpoint.

{
  "blockhash": "EkSnNWid2cvwEVnVx9aBqawnmiCNiDgp3gUdkDPTKN1N",
  "lastValidBlockHeight": 123456789
}

GET /rpc/balance/{wallet}

GET /rpc/balance/{wallet} Free

Get USDC balance for a wallet address. Returns balance in micro-units (6 decimals).

Path Parameters

Parameter	Description
wallet	Solana wallet address (base58)

Response

{
  "wallet": "8hTmULLrTpXJxpebL246N4aCo4cqxHTpTrKJyRxeDdWT",
  "balance_usdc": 1000000,
  "balance_usd": 1.00
}

Pricing

Tier	Price/Chunk	Model	Features
script	FREE	all-MiniLM-L6-v2	100/day limit, local model
agent	$0.0005	all-MiniLM-L6-v2	Unlimited, for x402 AI agents
pro	$0.001	text-embedding-3-small	OpenAI embeddings
pro-plus	$0.01	text-embedding-3-large	Best quality + AI enrichment

Embedding Models

Models are locked per tier - no selection needed.

Model	Dimensions	Tier
all-MiniLM-L6-v2	384	Script, Agent
text-embedding-3-small	1536	Pro
text-embedding-3-large	3072	Pro+

Output Formats

Specify output_format parameter to get vectors in database-ready format:

json - Universal JSON (default)
chroma - ChromaDB format
pinecone - Pinecone upsert format
weaviate - Weaviate object format
qdrant - Qdrant point format
milvus - Milvus insert format
pgvector - PostgreSQL pgvector format

Error Codes

Code	Meaning
400	Bad request - invalid parameters
402	Payment required - include X-PAYMENT header
403	Payment invalid - TX not found or insufficient amount
429	Rate limited - free tier limit exceeded
500	Server error - retry with exponential backoff