TARS
TARS · API Reference

API reference.

All TARS data is public and machine-readable. Query status, trust scores, and endpoint metadata over REST, MCP, or A2A. Register new endpoints via the REST API or web form.

GET /statusPOST /registerPOST /ingestMCP /mcpA2A /a2a
BASE URL
tars.dev
AUTH
None — public
FORMAT
JSON
SCHEMA-VERSION
1.0
V
OK
REST·GET/api/v1/status

All endpoint status

Returns the current status, uptime, and response time for every active endpoint. Public, no authentication required. Updated every 60 seconds.

Parameters
Response header1.0
Cache-Controls-maxage=60, stale-while-revalidate=30
Response fields
schema_version"1.0"
generated_atTimestamp of this response
overall_statusall_operational · degraded_performance · partial_outage · no_data
endpoint_countTotal monitored endpoints
endpoints[]One object per endpoint (see below)
↳ slugURL-safe identifier
↳ nameDisplay name
↳ urlEndpoint URL
↳ protocolMCP · A2A · REST
↳ current_statusup · degraded · down · null
↳ last_checked_atLast probe time
↳ response_time_ms.lastMost recent probe latency
↳ response_time_ms.avg_24h24h average latency
↳ uptime_percent.last_24h0–100
↳ uptime_percent.last_7d0–100
↳ uptime_percent.last_30d0–100
Request
curl https://tars.dev/api/v1/status
Response (200)
{
  "schema_version": "1.0",
  "overall_status": "all_operational",
  "endpoint_count": 12,
  "endpoints": [{
    "slug": "mcp-registry",
    "protocol": "MCP",
    "current_status": "up",
    "uptime_percent": {"last_30d": 99.8}
  }]
}
REST·POST/api/v1/register

Register an endpoint

Submit an endpoint for monitoring. Idempotent — safe to call on every app startup. Endpoints that pass an initial health check begin probing within minutes. Others are queued for manual review.

Request body (JSON)
urlFull URL of your endpoint
protocolMCP · A2A · REST
nameDisplay name (defaults to hostname)
descriptionWhat this endpoint provides to agents
hosting_regionRegion key for carbon band (e.g. aws-eu-west-1)
green_hostingOperator-declared renewable energy commitment
Responses
201 / status: monitoringAccepted immediately — health check passed
202 / status: pendingQueued for manual review
409 / status: already_monitoredURL already registered — idempotent
slugAssigned URL-safe identifier
monitoring_urlPublic monitor page for this endpoint
Request
curl -X POST \
  https://tars.dev/api/v1/register \
  -H "Content-Type: application/json" \
  -d '
  {
    "url": "https://api.example.com/mcp",
    "protocol": "MCP",
    "name": "My MCP Server",
    "hosting_region": "aws-eu-west-1"
  }'
Response (201)
{
  "status": "monitoring",
  "slug": "api-example-com",
  "monitoring_url": "https://tars.dev/monitor/api-example-com"
}
SDK·POST/api/v1/ingest

Submit telemetry

Called automatically by the @tars/sdk — not intended for direct use. Submits a windowed batch of anonymous call statistics from an SDK reporter instance. Used to compute Class B ratings (community adoption signal).

Request body (JSON)
reporterEd25519 public key — "ed25519:<hex>"
window_startStart of the observation window
window_endEnd of the observation window
reports[]One entry per endpoint in this window
↳ endpointFull endpoint URL
↳ callsTotal calls in window
↳ successSuccessful call count
↳ errorsError count
↳ p50_msMedian latency (optional)
↳ p95_ms95th percentile latency (optional)
SDK usage (recommended)
// Handled automatically — no direct calls needed
import { TarsReporter } from '@tars/sdk'

const reporter = new TarsReporter()
// Flushes to /api/v1/ingest every 5 minutes
Response (202)
{
  "accepted": 3,
  "skipped": 0,
  "auto_listed": 1
}
MCP·POST/mcp

MCP endpoint

Exposes TARS data as a Model Context Protocol server. Agents and MCP clients can connect to this endpoint to query live status and trust data programmatically. Streamable HTTP transport, JSON-RPC 2.0.

Tools
list_endpoints

List all monitored endpoints with current status, uptime, and response times.

protocolFilter: MCP · A2A · REST (optional)
statusFilter: up · degraded · down (optional)
get_endpoint_status

Detailed reliability metrics for one endpoint — status, latency, uptime over 24h/7d/30d.

slugEndpoint slug (from list_endpoints)
urlFull endpoint URL (alternative to slug)
get_trust_summary

Concise trust summary for any URL — status, uptime, and conformance. Hostname-level matching.

url *The URL to check trust data for
Connect with MCP SDK
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from
  '@modelcontextprotocol/sdk/client/streamableHttp.js'

const client = new Client({ name: 'my-agent', version: '1.0' })
await client.connect(
  new StreamableHTTPClientTransport(
    new URL('https://tars.dev/mcp')
  )
)

const result = await client.callTool({
  name: 'get_trust_summary',
  arguments: { url: 'https://mcp.example.com' }
})
A2A·POST/a2a

A2A task endpoint

Google Agent-to-Agent protocol v0.2. Accepts tasks/send with either a structured data part (direct skill dispatch) or a text part (keyword routing). All tasks are synchronous — no stored state.

Agent card
Agent card URL/.well-known/agent.json
Skillslist_endpoints · get_endpoint_status · get_trust_summary
Input modestext · data
Output modestext
tasks/send — data part
curl -X POST https://tars.dev/a2a \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0", "id": 1,
  "method": "tasks/send",
  "params": {
    "id": "task-1",
    "message": { "role": "user", "parts": [{
      "type": "data",
      "data": {
        "skill": "get_trust_summary",
        "arguments": {"url": "https://mcp.example.com"}
      }
    }]}
  }
}&apos;
Monitor →SDK →Live JSON →Register endpoint →