TARXDocs
⌘Ktarx.com →

Search Docs

Skip to Content
Developers

API Reference

One familiar request shape across local, hosted, and enterprise execution.

Start local first

TARX is designed to start locally.

That means:

  • no hosted Supercomputer key is required for first-party local TARX use
  • external integrations may use developer identity keys for account identity, project attribution, local runtime identity, and rate limits when that pilot surface is enabled
  • your existing OpenAI SDK can point at the local TARX runtime
  • you can add hosted Supercomputer access later without rewriting the app

Local runtime

Launch-safe local request:

curl http://127.0.0.1:11440/health
export TARX_API_KEY="your_developer_key"
 
curl http://127.0.0.1:11440/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TARX_API_KEY" \
  -d '{
    "model": "tarx-local",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Python example:

import os
from openai import OpenAI
 
client = OpenAI(
    base_url="http://127.0.0.1:11440/v1",
    api_key=os.environ["TARX_API_KEY"]
)
 
response = client.chat.completions.create(
    model="tarx-local",
    messages=[{"role": "user", "content": "Hello"}]
)
 
print(response.choices[0].message.content)

Hosted Supercomputer

When you need hosted execution, use the same request shape with a TARX API key:

curl https://tarx.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TARX_API_KEY" \
  -H "x-tarx-execution-policy: supercomputer-fast" \
  -H "x-tarx-privacy-tier: mesh_safe" \
  -d '{
    "model": "gemma",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

When key access is enabled for an account, keys are managed from /settings/api-keys. The developer funnel should keep this simple:

  1. Create a free developer identity key for external integrations.
  2. Start locally; current local runtime builds may still accept unauthenticated calls during the coordinated enforcement migration.
  3. Create a hosted Supercomputer key when you want permissioned power beyond the Computer.
  4. Keep the same app request shape.

Current lifecycle truth:

  • POST /api/keys issues a TARX key with scope: "developer_runtime" or scope: "supercomputer"
  • scope: "developer_runtime" is a free identity key, not a hosted compute entitlement
  • scope: "supercomputer" requires a paid Supercomputer entitlement and otherwise returns 402 hosted_entitlement_required
  • GET /api/keys lists issued key metadata for the signed-in account without returning secret values
  • DELETE /api/keys revokes a listed key
  • self-serve rotation is not live yet

Hosted Supercomputer usage is packaged as optional power. Technical account and developer views may expose Joules as TARX’s native energy unit for hosted compute, alongside familiar workload indicators for forecasting. Do not assume or publish a fixed conversion unless TARX has explicitly published one.

Execution planes

The TARX runtime is being shaped around these execution planes:

  • local
  • Supercomputer
  • enterprise runtime
  • enterprise BYO agreements

The important promise is not just routing. It is portability:

Start local. Scale to hosted TARX compute. Land on customer-scoped infrastructure or enterprise-approved provider agreements. Keep the app shape familiar.

Stable surfaces

Today, the launch-safe public developer surface should be treated as:

  • GET /v1/health
  • GET /v1/models
  • GET /v1/routes
  • GET /v1/evidence
  • GET /v1/capacity
  • GET /v1/rag/status
  • GET /v1/usage
  • POST /v1/chat/completions

For release and updater truth, TARX also exposes:

  • GET /api/version

The current truth boundary matters:

  • GET /v1/usage requires a TARX API key and currently reports Bridge aggregate beta accounting
  • POST /v1/chat/completions on the hosted API now requires a TARX API key and returns a structured TARX error envelope on auth, quota, rate-limit, or upstream failures
  • GET /v1/usage currently exposes Bridge aggregate beta accounting plus API-key route/project attribution when hosted requests are recorded; project attribution comes from x-tarx-project-id and is not Stripe-reconciled billing truth
  • GET /v1/models and GET /v1/routes describe the TARX contract and route families, not every underlying weight file
  • GET /v1/evidence exposes the route-evidence schema and request-header contract TARX uses for hosted execution
  • GET /v1/capacity exposes the launch-safe queue and backpressure contract; it does not claim live queue depth or reserved capacity
  • GET /v1/rag/status exposes the local/account/private-boundary retrieval truth contract; it does not claim shared/global private RAG, hybrid retrieval, reranking, graph RAG, visual RAG, or proven cross-device RAG sync
  • GET /v1/health reports hosted TARX reachability; it does not prove a developer’s local Bridge runtime is healthy
  • GET /api/version is the release-truth surface for web deployment metadata plus the current TARX Desktop / Electron release manifest

Release truth

GET /api/version is the canonical TARX release-truth endpoint.

Compatibility fields remain at the top level for existing updater and desktop consumers:

  • version
  • build
  • commit
  • deployment
  • download_url
  • updater_manifest_url
  • notes

New consumers should prefer the structured release fields:

  • release.tarx
  • release.web
  • release.electron
  • web.version
  • electron.version
  • electron.released_at

This endpoint is intentionally no-store and should be treated as operational truth, not as a cached docs surface.

Additional modalities and primitives should follow the same runtime model as they harden:

  • POST /v1/embeddings
  • POST /v1/jobs
  • GET /v1/jobs/{id}
  • image workflows
  • voice
  • vision
  • long-running media jobs
  • sessions, files, memory, tools, and route evidence

Route evidence

Hosted TARX should be explainable, not just billable.

Use GET /v1/evidence to inspect the current request-header contract and the machine-readable tarx_route response shape used for hosted execution evidence.

The important ideas are:

  • request policy is explicit
  • privacy boundary is explicit
  • fallback is explicit
  • Joules accounting is explicit
  • evidence IDs are explicit

Examples of route-control headers:

x-tarx-execution-policy: supercomputer-fast
x-tarx-privacy-tier: mesh_safe
x-tarx-project-id: demo-project
x-tarx-max-joules: 50000
x-tarx-max-latency-ms: 1500

Browser clients that call https://tarx.com/api/v1/* cross-origin must send only the documented TARX route headers above. Those headers are now included in the API CORS allow-list.

Capacity and Backpressure

Use GET /v1/capacity to inspect the launch queue/backpressure contract.

Today it can expose:

  • interactive queue class for supercomputer-fast
  • deep queue class for supercomputer-deep
  • enterprise queue class for enterprise-private and enterprise-BYO policy
  • Retry-After, x-tarx-queue-class, and x-tarx-backpressure-state headers on rate limits or upstream unavailability

Today it does not claim:

  • live queue depth
  • async hosted job queueing
  • reserved public capacity
  • million-user scale readiness

RAG Status

Use GET /v1/rag/status to inspect the launch-safe local/account/private-boundary retrieval contract. Supercomputer may sync encrypted account-scoped RAG state across a user’s devices or shard RAG inside a private network, but TARX Global/shared pools must not index or retrieve private memory outside that boundary.

curl https://tarx.com/api/v1/rag/status
 
curl https://tarx.com/api/v1/rag/jobs

Today it can expose:

  • Bridge health reachability
  • Bridge memory-search reachability
  • Bridge unified-search reachability
  • which retrieval modes are launch-default, available-when-configured, or planned
  • the Gemma-family candidate strategy for local embeddings, multimodal work, code, safety, and sector-specific pilots
  • the planned account/private-boundary RAG job evidence contract for account sync, private Supercomputer, and public/mesh-safe global jobs

Today it does not claim:

  • full hybrid dense+sparse retrieval
  • reranking
  • graph/community-summary RAG
  • visual-document RAG
  • cross-device RAG sync
  • shared/global private-memory RAG

The first local embedding candidate is google/embeddinggemma-300m, but TARX will not swap retrieval models without eval proof on precision, latency, stale-memory rejection, and answer support. Account sync and private/org sharded RAG may use paid Supercomputer compute only inside the user account or customer-approved boundary.

If a chat turn attempts Computer retrieval but Bridge/search is unavailable, TARX telemetry should report retrieval_unavailable rather than treating the turn as a clean zero-hit memory lookup. That failure class belongs to RAG/infrastructure triage unless the evidence was correct and the model ignored it.

Account/private-boundary RAG job classes such as account_or_private_rerank, account_or_private_graph_summary, and account_or_private_visual_rag are planned contracts, not live public capacity guarantees. Each job must emit data_boundary as one of computer, account_supercomputer_sync, private_supercomputer, or global_public_only. Joules and route evidence prove paid compute use only; they do not prove TARX Global owns or indexes a private corpus.

GET /v1/rag/jobs exposes the planned runner contract. POST /v1/rag/jobs validates the boundary rules but returns rag_job_runner_not_live until account/private-boundary execution, queueing, route evidence, and Joules ledgers are proven.

curl https://tarx.com/api/v1/rag/jobs \
  -H "Authorization: Bearer $TARX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_class": "account_or_private_rerank",
    "data_boundary": "account_supercomputer_sync",
    "privacy_tier": "personal",
    "account_id": "acct_example"
  }'

Do not submit private account or customer sources with data_boundary: "global_public_only". That boundary is only for public or explicitly mesh-safe retrieval context.

Examples of response evidence fields:

  • execution_plane
  • policy
  • privacy_tier
  • model
  • provider
  • latency_ms
  • raw_joules
  • estimated_joules
  • billable_joules
  • fallback
  • fallback_reason
  • evidence_id

Usage truth

GET /v1/usage is intentionally honest about what it can and cannot attribute today.

Today it can expose:

  • aggregate Joules used this month
  • aggregate Joules remaining for the current plan
  • daily aggregate Joules timeline
  • whether accounting came from Bridge KV or Bridge was unavailable
  • the current attribution scope and ledger keys through source_descriptor
  • beta per-key hosted request counts for the API key used on the request
  • beta per-project hosted request counts when clients send x-tarx-project-id
  • route evidence IDs and Joules in the key ledger when the upstream hosted response includes tarx_route
  • project-level route evidence and Joules when both x-tarx-project-id and route evidence are present

Today it does not claim to expose:

  • per-space attribution
  • billing-grade per-key Joules attribution when upstream route evidence is absent
  • billing-grade per-project Joules attribution when upstream route evidence is absent
  • billing-grade per-route Joules attribution across every hosted response
  • route-evidence-linked billing events
  • Stripe reconciliation

That distinction matters. Usage is live; key and project request counting are beta; route-evidence Joules are captured only when emitted by the hosted route; full hosted billing attribution is still maturing.

Errors

Hosted TARX errors use a stable envelope:

{
  "error": {
    "message": "Authentication required",
    "type": "authentication_error",
    "code": "tarx_api_key_required",
    "docs_url": "/docs/api-reference#errors"
  }
}

Current launch-safe error types:

  • authentication_error for missing or invalid hosted TARX keys
  • authentication_error with tarx_api_key_revoked when a listed key was revoked
  • insufficient_quota when the key does not carry active Supercomputer entitlement
  • rate_limit_error with retry_after_seconds when the hosted API backstop limiter trips
  • server_error when the upstream Supercomputer route is unavailable

MCP server

Connect from any MCP client:

{
  "mcpServers": {
    "tarx": {
      "url": "https://mcp.tarx.com/mcp"
    }
  }
}

For local-private usage in Claude Desktop or Claude Code, use the TARX stdio bridge. This keeps memory, files, Vault, and device context on the user’s Computer:

{
  "mcpServers": {
    "tarx-local": {
      "command": "node",
      "args": ["/Users/YOU/Desktop/tarx-mcp/scripts/tarx-local-memory-mcp.mjs"],
      "env": {
        "TARX_BRIDGE_URL": "http://127.0.0.1:11440"
      }
    }
  }
}

OpenAI function calling

Export the launch-safe TARX local context tools in OpenAI function calling format:

curl https://mcp.tarx.com/openai-tools

Pass the response tools array to your agent and implement handlers that execute locally against http://127.0.0.1:11440. Do not send Vault, files, credentials, or local device context to remote models.

Important truth boundary

Public developer docs should not depend on internal TARX topology names or old internal ports.

What developers should care about:

  • the local and hosted request shape
  • how to start locally
  • how to add hosted execution
  • how to keep the same app shape in enterprise