API Reference

Rocktalk Labs provides the Rocktalk Lens API — a 22-dimensional semantic coordinate system, free for all researchers. All endpoints live at https://api.rocktalk.ai.

Authentication

All requests require a Authorization header with your API key as a Bearer token.

Authorization header

Authorization: Bearer sk_rt_YOUR_KEY_HERE

API keys are prefixed sk_rt_. Get a key by signing up — your key arrives by email. Keep it secret; it carries your quota.

Key security: Do not expose your API key in client-side code or public repositories. Use environment variables or a secrets manager.

Base URL

All API endpoints are under:

base url

https://api.rocktalk.ai

Lens endpoints are at /v1/lens/*. Every request requires authentication.

Error Responses

All errors return JSON with an error field and a standard HTTP status code.

error response format

{
  "error": "Description of what went wrong"
}

Status	When it occurs
401	Missing or invalid API key
422	Invalid input — empty text, text too long, malformed JSON
429	Rate limit exceeded (60 req/min or 1000 req/hr)
503	Model loading failed or service temporarily unavailable

Rate Limits

Limits apply per API key regardless of plan tier.

Window	Limit	Notes
Per minute	60 requests	Rolling 60-second window
Per hour	1,000 requests	Rolling 60-minute window

When rate limited you receive a 429 response. The Retry-After header indicates seconds to wait. For higher limits, contact api@rocktalk.ai.

Rocktalk Lens

Rocktalk Lens maps text into a 22-dimensional semantic coordinate space. Each dimension captures a distinct primitive category of meaning. Coordinates are deterministic — the same input always produces the same output. Lens is always free; cite as Rocktalk Labs Lens in publications.

Encode Text

POST /v1/lens/encode

Encode one or more texts into 22-dimensional semantic coordinates. Accepts a single string or an array of strings.

Field	Type	Description
text required	string \| string[]	Text to encode. Single string or array of strings. Max 4096 characters per item. Max 64 items per batch.

python — single text

import requests

res = requests.post(
    "https://api.rocktalk.ai/v1/lens/encode",
    headers={"Authorization": "Bearer sk_rt_YOUR_KEY"},
    json={"text": "love is patient"}
)
data = res.json()
result = data["results"][0]

print(result["coordinates"])     # [0.82, 0.34, ..., 0.91] — 22 floats
print(result["top_dimensions"])  # top activated dimensions

python — batch encode

res = requests.post(
    "https://api.rocktalk.ai/v1/lens/encode",
    headers={"Authorization": "Bearer sk_rt_YOUR_KEY"},
    json={"text": [
        "the speed of light",
        "maximum constraint on information transfer",
        "photon velocity in vacuum"
    ]}
)

for r in res.json()["results"]:
    print(r["text"], r["coordinates"][:4], "...")

curl

curl https://api.rocktalk.ai/v1/lens/encode \
  -H "Authorization: Bearer sk_rt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "love is patient"}'

Response Format

json response

{
  "results": [
    {
      "text": "love is patient",
      "coordinates": [
        0.8234, 0.7102, 0.3045, 0.5567,
        0.6891, 0.7234, 0.2109, 0.8012,
        0.9101, 0.4523, 0.6677, 0.3345,
        0.2234, 0.7890, 0.5012, 0.4101,
        0.3567, 0.8234, 0.2678, 0.1234,
        0.4512, 0.9023
      ],
      "top_dimensions": [
        {"index": 8,  "meaning": "surrounding/goodness", "value": 0.9101},
        {"index": 21, "meaning": "covenant/completion",  "value": 0.9023},
        {"index": 0,  "meaning": "strength/primacy",     "value": 0.8234}
      ]
    }
  ],
  "model": "rocktalk-lens-v1",
  "dimensions": 22
}

Compare Two Texts

POST /v1/lens/compare

Compute the semantic distance between two texts in the 22D coordinate space.

Field	Type	Description
text_a required	string	First text. Max 4096 characters.
text_b required	string	Second text. Max 4096 characters.

python

res = requests.post(
    "https://api.rocktalk.ai/v1/lens/compare",
    headers={"Authorization": "Bearer sk_rt_YOUR_KEY"},
    json={
        "text_a": "the speed of light",
        "text_b": "maximum constraint on information transfer"
    }
)
data = res.json()
print(data["cosine_similarity"])  # 0.94 — very similar
print(data["l2_distance"])        # Euclidean distance in 22D space

curl

curl https://api.rocktalk.ai/v1/lens/compare \
  -H "Authorization: Bearer sk_rt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text_a": "democracy",
    "text_b": "shared decision structure"
  }'

Response Format

json response

{
  "cosine_similarity": 0.9412,
  "l2_distance": 0.2341,
  "coordinates_a": [0.82, 0.71, /* ...22 floats */],
  "coordinates_b": [0.79, 0.68, /* ...22 floats */]
}

Cosine similarity is 0–1, where 1 is identical direction. L2 distance is Euclidean distance in 22D space — smaller means more similar.

Get Dimension Definitions

GET /v1/lens/dimensions

Returns the definitions for all 22 semantic dimensions. No request body needed.

curl

curl https://api.rocktalk.ai/v1/lens/dimensions \
  -H "Authorization: Bearer sk_rt_YOUR_KEY"

json response

{
  "dimensions": [
    {"index": 0,  "meaning": "strength/primacy"},
    {"index": 1,  "meaning": "house/dwelling/family"},
    /* ... */
    {"index": 21, "meaning": "covenant/completion"}
  ],
  "count": 22,
  "model": "rocktalk-lens-v1"
}

Free Tier Limits

All accounts start on the free tier. No credit card required.

Resource	Free Tier	Notes
Lens calls	10,000 / month	Always free — no charge on any plan

Monthly quotas reset on the 1st of each calendar month UTC. Need higher throughput? Contact api@rocktalk.ai.

Lens is always free. There is no charge for Lens calls. If you need higher throughput for a research project, just ask.

22 Dimensions Reference

The full table of dimension indices and their semantic meanings as returned by GET /v1/lens/dimensions.

Index	Meaning
d0	strength / primacy
d1	house / dwelling / family
d2	movement / lifting
d3	pathway / entry / decision
d4	revelation / breath
d5	connection / securing
d6	cutting / nourishment
d7	enclosure / protection
d8	surrounding / goodness
d9	work / deed / making
d10	covering / blessing
d11	teaching / authority
d12	flow / chaos / massive
d13	seed / continuity
d14	support / cycle
d15	seeing / knowing
d16	speech / expression
d17	desire / righteousness
d18	time / condensing
d19	head / beginning
d20	fire / transformation
d21	covenant / completion

Research citation: When using Rocktalk Lens output in publications, cite as: Rocktalk Labs Lens (rocktalk.ai). Include the API version from the model field in the response.