Reference

API Reference

Complete specification for every AXIOM endpoint — request format, response shape, authentication, errors, and limits.

Base URL

https://api.axiom.dev

Authentication

Pass your API key via header or query parameter:

X-API-Key: your-api-key

# or query parameter
?api_key=your-api-key

Endpoints

POST	/v2/encode	Encode one text
POST	/v2/batch-encode	Encode many texts
POST	/v2/similarity	Compare two vectors
GET	/v2/health	Health check

Key Facts

Vector: 1,256 bytes (10,048 bits)
Deterministic: same input = same vector, always
Similarity range: 0.0 to 1.0 (baseline ~0.50)

Endpoints

POST/v2/encode

Encode a single text string into a 10,048-bit hypervector.

Request Body

text string required The text to encode. Lowercased and trimmed internally.

curl -X POST https://api.axiom.dev/v2/encode \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"text": "hello world"}'

Response

`text`	string	optional	The input text (echoed back).
`vector`	number[]	optional	Array of 1,256 unsigned bytes (u8). This is the hypervector.
`dimensions`	number	optional	Always 10048.

{
  "text": "hello world",
  "vector": [147, 68, 33, 211, ...],  // 1,256 bytes
  "dimensions": 10048
}

POST/v2/batch-encode

Encode multiple texts in a single request. Counts as one API call against your rate limit.

Request Body

texts string[] required Array of text strings to encode.

curl -X POST https://api.axiom.dev/v2/batch-encode \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"texts": ["hello world", "hello worl", "dog"]}'

Response

`vectors`	object[]	optional	Array of {text, vector} objects, one per input text. Same order as input.
`vectors[].text`	string	optional	The input text (echoed).
`vectors[].vector`	number[]	optional	1,256-byte hypervector.
`count`	number	optional	Number of vectors returned.

{
  "vectors": [
    { "text": "hello world", "vector": [147, 68, 33, ...] },
    { "text": "hello worl",  "vector": [151, 68, 33, ...] },
    { "text": "dog",         "vector": [203, 14, 88, ...] }
  ],
  "count": 3
}

POST/v2/similarity

Compute the similarity between two previously encoded vectors. Returns a score from 0.0 to 1.0.

Request Body

`vector_a`	number[]	required	First vector (1,256 bytes from /v2/encode).
`vector_b`	number[]	required	Second vector (1,256 bytes from /v2/encode).

curl -X POST https://api.axiom.dev/v2/similarity \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "vector_a": [147, 68, 33, ...],
    "vector_b": [151, 68, 33, ...]
  }'

Response

`similarity`	number	optional	Normalized Hamming similarity. 1.0 = identical, ~0.50 = unrelated (random baseline), 0.0 = maximally different.
`vector_a_dimensions`	number	optional	Dimensions of vector A (always 10048).
`vector_b_dimensions`	number	optional	Dimensions of vector B (always 10048).

{
  "similarity": 0.8649,
  "vector_a_dimensions": 10048,
  "vector_b_dimensions": 10048
}

Similarity Score Guide

Score	Meaning	Example
1.00	Identical	"hello world" vs "hello world"
0.85+	Near-duplicate (typo, one word changed)	"hello world" vs "hello worl" (0.8649)
0.70 - 0.85	Structurally similar (shared substrings)	"rust programming" vs "python programming" (0.7481)
0.55 - 0.70	Some overlap (shared prefix or fragments)	"apple" vs "application" (0.6391)
~0.50	Unrelated (random baseline)	"dog" vs "quantum physics" (~0.50)
< 0.45	Extremely rare — vectors are anti-correlated	Almost never happens with natural text

GET/v2/healthNo auth required

Check if the API is up. No authentication required. Not rate-limited.

curl https://api.axiom.dev/v2/health

Response

{ "status": "ok" }

Authentication

All endpoints except /v2/health require an API key. Pass it in one of two ways:

# Option 1: Header (recommended)
curl -H "X-API-Key: YOUR_API_KEY" ...

# Option 2: Query parameter
curl "https://api.axiom.dev/v2/encode?api_key=YOUR_API_KEY" ...

Frontend Proxy Pattern

Never expose your API key in client-side code. Use a server-side proxy (Next.js API routes, Express, etc.) that adds the key on the backend.

// Next.js: app/api/encode/route.ts
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  const body = await request.json();
  const res = await fetch(
    `${process.env.AXIOM_API_URL}/v2/encode`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.AXIOM_API_KEY!,
      },
      body: JSON.stringify(body),
    }
  );
  return NextResponse.json(await res.json());
}

// Client-side code calls /api/encode (your proxy), not the AXIOM API directly.

Rate Limits & Errors

Rate Limits

Free tier: 100 requests per day per API key
Batch calls: A single /v2/batch-encode counts as 1 request regardless of how many texts
Health check: Not rate-limited, no key needed
Reset: Daily at midnight UTC

HTTP Status Codes

200	Success
400	Bad request (missing/invalid fields)
401	Missing or invalid API key
429	Rate limit exceeded
500	Server error

Error Response Format

// 401 — Missing or invalid API key
{ "error": "Unauthorized" }

// 429 — Rate limit exceeded
{ "error": "Rate limit exceeded. Try again tomorrow." }

// 400 — Bad request
{ "error": "Field 'text' is required" }

Best Practices

Use batch-encode

A single /v2/batch-encode counts as 1 API call. Encode 50 texts in one request instead of 50 separate calls.

Cache vectors

Encoding is deterministic — same input always produces the same vector. Store vectors and skip re-encoding.

Interpret scores correctly

~0.50 = unrelated (random baseline). Above 0.60 = some structural overlap. Above 0.85 = near-duplicate.

Normalize input

AXIOM lowercases and trims input. But cleaning punctuation or extra whitespace yourself improves consistency.

Proxy your API key

Never put your API key in client-side JavaScript. Use a server-side route that adds the key.

Know the limits

AXIOM detects character-level similarity, not semantic meaning. 'car' vs 'automobile' will score ~0.50.

Examples · Why AXIOM · Playground