REST APIv1 · tRPC over HTTP

REST API Reference

Tapas exposes a tRPC-over-HTTP API. Every endpoint accepts JSON and returns JSON. No SDK required — a single POST with a JSON body is all you need. The base URL is https://tapas.one.

Endpoint Overview

All endpoints — base URL: https://tapas.one

POST

/api/trpc/query.ask

Submit a query — returns cached or AI-generated answer with energy metrics

None

GET

/api/trpc/categories.list

List all knowledge categories with domain counts

None

GET

/api/trpc/energy.summary

Platform-wide energy savings summary and cache hit rate

None

GET

/api/trpc/energy.trend

30-day daily energy savings trend data

None

POST

/api/trpc/submissions.create

Submit a community Q&A contribution for admin review

User

GET

/api/trpc/cache.list

List all cached responses (admin only)

Admin

DELETE

/api/trpc/cache.delete

Delete a cached response by ID (admin only)

Admin

POST

/api/trpc/cache.warm

Trigger cache warming job — pre-populate up to 20 queries (admin only)

Admin

tRPC envelope format: All requests wrap the payload in ajson key: { "json": { ...your payload } }. All responses wrap the result in { "result": { "data": { ...response } } }.

POST/api/trpc/query.askNo auth required

The primary endpoint. Submit any natural-language question and receive a cached or AI-generated answer with full energy metrics. Enable lemMode for bullet-point cache responses at 0.001 Wh; disable for full prose inference at ~3.0 Wh.

Request body

querystringrequiredThe user's natural-language question

lemModebooleanoptionalEnable Low Energy Mode — returns bullets from cache (default: false)

domainstring?optionalOptional domain hint slug (e.g. 'science_technology') to bias routing

cURL example

POST /api/trpc/query.ask

bash

curl -X POST https://tapas.one/api/trpc/query.ask \
  -H 'Content-Type: application/json' \
  -d '{
    "json": {
      "query": "How does quantum computing work?",
      "lemMode": true
    }
  }'

Response schema

200 OK — cache hit example

json

{
  "result": {
    "data": {
      "mode":             "cache",
      "lemMode":          true,
      "answer":           "",
      "bullets": [
        "Quantum computers use qubits instead of classical bits",
        "Qubits exploit superposition to represent 0 and 1 simultaneously",
        "Entanglement links qubits so operations on one affect others instantly",
        "Quantum interference amplifies correct answers and cancels wrong ones",
        "Current hardware (NISQ era) is noisy — error correction is an active research area"
      ],
      "category":         "Quantum Computing",
      "domain":           "science_technology",
      "confidence":       0.94,
      "routingMethod":    "cosine",
      "energyWhUsed":     0.001,
      "energyWhSaved":    2.999,
      "responseTimeMs":   42,
      "cachedResponseId": "clx9f2k0000abc"
    }
  }
}

Response field reference

mode"cache" | "llm"How the answer was served

lemModebooleanWhether Low Energy Mode was active

answerstringFull prose answer — populated in LLM mode, empty string in cache mode

bulletsstring[] | nullBullet points — populated in cache/LEM mode

categorystringMatched knowledge category name

domainstringTop-level domain slug

confidencenumber (0–1)Cosine similarity score of cache match

routingMethodstring"cosine" | "smart-router" | "hybrid"

energyWhUsednumberWatt-hours consumed by this query

energyWhSavednumberWatt-hours saved vs. full GPU inference baseline

responseTimeMsnumberEnd-to-end server latency in milliseconds

cachedResponseIdstring | nullCache entry ID — null when served by LLM

GET/api/trpc/categories.listNo auth required

Returns all 160+ active knowledge categories grouped by domain, along with per-domain counts. Use this to build category pickers, domain filters, or to validate domain hint slugs.

GET /api/trpc/categories.list

bash

curl 'https://tapas.one/api/trpc/categories.list' \
  -H 'Content-Type: application/json'

200 OK — truncated response

json

{
  "result": {
    "data": {
      "categories": [
        {
          "id":          "clx9f2k0000001",
          "name":        "Quantum Computing",
          "domain":      "science_technology",
          "description": "Quantum mechanics applied to computation — qubits, superposition, entanglement",
          "isActive":    true
        }
        // ... 159 more categories
      ],
      "domainCounts": {
        "science_technology": 30,
        "health_medicine":    25,
        "finance_economics":  20,
        "history_culture":    20,
        "programming_cs":     25,
        "environment_energy": 20,
        "general_knowledge":  20
      }
    }
  }
}

GET/api/trpc/energy.summaryNo auth required

Platform-wide aggregate energy metrics — total queries, cache hit rate, total Wh saved, CO₂ grams saved, and a cars-off-road equivalent. Useful for embedding live savings stats in your own dashboards.

GET /api/trpc/energy.summary

bash

curl 'https://tapas.one/api/trpc/energy.summary' \
  -H 'Content-Type: application/json'

200 OK

json

{
  "result": {
    "data": {
      "totalQueries":    12847,
      "cacheHits":       10920,
      "hitRate":         0.85,
      "totalWhSaved":    32760.0,
      "totalWhUsed":     1924.5,
      "co2GramsSaved":   15724.8,
      "carsEquivalent":  0.07
    }
  }
}

GET/api/trpc/energy.trendNo auth required

Returns 30 daily data points for energy savings trend charts. Each entry contains date, query count, cache hits, Wh saved, and CO₂ grams saved. Ideal for time-series visualisations.

GET /api/trpc/energy.trend

bash

curl 'https://tapas.one/api/trpc/energy.trend' \
  -H 'Content-Type: application/json'

200 OK — truncated to 1 entry

json

{
  "result": {
    "data": [
      {
        "date":          "2026-03-19",
        "totalQueries":  1284,
        "cacheHits":     1091,
        "whSaved":       3273.0,
        "co2GramsSaved": 1571.0
      }
      // ... 29 more daily entries
    ]
  }
}

POST/api/trpc/submissions.createUser auth required

Submit a community Q&A contribution for admin review. Requires a valid session cookie (obtained via Manus OAuth). Approved submissions are added to the knowledge cache.

POST /api/trpc/submissions.create

bash

curl -X POST https://tapas.one/api/trpc/submissions.create \
  -H 'Content-Type: application/json' \
  -H 'Cookie: session=<your-session-cookie>' \
  -d '{
    "json": {
      "question":    "How does mRNA vaccine technology work?",
      "answer":      "mRNA vaccines deliver genetic instructions...",
      "domain":      "health_medicine",
      "categoryId":  "clx9f2k0000042"
    }
  }'

Error Codes

All errors follow the tRPC error envelope format. The data.code field contains a machine-readable error code; data.httpStatus mirrors the HTTP status.

Error response examples

json

// HTTP 400 — Bad Request (missing required field)
{
  "error": {
    "json": {
      "message": "query is required",
      "code":    -32600,
      "data": {
        "code":       "BAD_REQUEST",
        "httpStatus": 400,
        "path":       "query.ask"
      }
    }
  }
}

// HTTP 401 — Unauthorized (protected procedure, no session)
{
  "error": {
    "json": {
      "message": "UNAUTHORIZED",
      "code":    -32001,
      "data": {
        "code":       "UNAUTHORIZED",
        "httpStatus": 401
      }
    }
  }
}

// HTTP 429 — Rate Limited
{
  "error": {
    "json": {
      "message": "Too many requests. Retry after 60 seconds.",
      "code":    -32000,
      "data": {
        "code":       "TOO_MANY_REQUESTS",
        "httpStatus": 429,
        "retryAfter": 60
      }
    }
  }
}

HTTP status code reference

200OKRequest succeeded — response in result.data

400BAD_REQUESTMissing or invalid request field (e.g. query is empty)

401UNAUTHORIZEDProtected endpoint requires a valid session cookie

403FORBIDDENAuthenticated but insufficient role (admin required)

404NOT_FOUNDResource not found (e.g. category ID does not exist)

429TOO_MANY_REQUESTSRate limit exceeded — see Retry-After header

500INTERNAL_SERVER_ERRORUnexpected server error — retry with exponential backoff

Rate Limits

Rate limits are applied per IP address. Authenticated users (with a valid session) receive higher limits. When a limit is exceeded, the API returns HTTP 429 with a Retry-After header.

Rate limit tiers

Anonymous60 req / min10 req / secPer IP

Authenticated user300 req / min30 req / secPer user

AdminUnlimitedUnlimitedPer user

Cache hits do not count against rate limits. Only queries that require full LLM inference (cache misses) consume rate limit tokens. This means a well-warmed cache can effectively serve unlimited traffic from a single IP.

Try it live

Use the interactive chat to test queries, or explore the full SDK docs for typed client libraries.