Developers | CARNETIA

Quick Start

The CARNETIA API is REST/JSON, public for verification, key-authenticated for management.

Base URL: https://carnetia.ai/api/v2

Format: JSON · Auth: Bearer token (Sanctum)

curl https://carnetia.ai/api/v2/health

Authentication

Public endpoints require no authentication. Authenticated endpoints use a Bearer token obtained via login:

curl -X POST https://carnetia.ai/api/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"...","device":"my-app"}'

Returns {"ok":true,"token":"1|xxx..."}

Use the token in subsequent requests:

curl https://carnetia.ai/api/v2/auth/me \
  -H "Authorization: Bearer 1|xxx..."

Endpoints

Public

GET /api/v2/health — service status + global stats
GET /api/v2/verify/{carnetia_id} — full agent details (canonical)
GET /api/v2/agent/{carnetia_id} — alias of /verify (legacy compat)
GET /api/v2/founders — list of all founders (paginated)
GET /api/v2/founders/stats — counts vs cap
POST /api/v2/subscribe — coming soon list
POST /api/v2/register — register operator + first agent

Live Challenge (anti-impersonation)

The TOTP-based live challenge proves that whoever answers holds the agent's secret right now, not just that the agent is registered. It does not prove who operates the agent or how well it works. Codes rotate every 30 seconds (RFC 6238 with HMAC-SHA1).

GET /api/v2/challenge/{carnetia_id} — public challenge state. Returns seconds_remaining, window_start, tolerance_seconds. Code itself is hidden in production (only exposed for demo agents). Rate limit: 60/min/IP.
Response note: aliveness_score is null when the agent has no activity in the last 7 days; activity_status is one of active_now, recent, dormant or no_activity.
POST /api/v2/verify-totp — verify a code submitted by a verifier. Body: { "carnetia_id": "...", "code": "123456" }. On valid: returns agent name and bumps aliveness_score. Rate limit: 10/min/IP.
GET /api/v2/agents/{carnetia_id}/code — operator-only. Returns the current TOTP code so the agent can share it with a verifier. Requires Authorization: Bearer ck_live_xxx API key. Rate limit: 60/min/key.
POST /api/v2/agents/{carnetia_id}/heartbeat — agent self-reports as alive (passive aliveness). Requires API key. Body optional: { "context": "login|action|response" }.

Authenticated

POST /api/v2/auth/token — login, get Bearer token
GET /api/v2/auth/me — current user + operators
POST /api/v2/auth/logout — revoke current token
GET /api/v2/my-agents — list agents you own

How the Live Challenge works (3-step flow)

Verifier wants to confirm the agent is real and alive. They open https://carnetia.ai/verify/{ID} or call GET /api/v2/challenge/{ID} to see if challenge is active.
Verifier asks the agent over their existing channel (chat/voice/email): "What's your CARNETIA code right now?"
Agent fetches their current code via GET /api/v2/agents/{ID}/code (using their API key) and replies. Verifier submits to POST /api/v2/verify-totp. Valid = proven aliveness.

Why it works: An impostor who doesn't have the agent's API key can't fetch the code. Codes expire in 30s, so replay attacks fail.

Code Examples

JavaScript

// Verify an agent
const res = await fetch(
  'https://carnetia.ai/api/v2/verify/CAR-2026-MX-1042-GP6X'
);
const { ok, agent } = await res.json();
if (ok && agent.status === 'active') {
  console.log('Verified:', agent.name);
}

Python

import requests

r = requests.get(
  'https://carnetia.ai/api/v2/verify/CAR-2026-MX-1042-GP6X'
)
data = r.json()
if data['ok'] and data['agent']['status'] == 'active':
    print(f"Verified: {data['agent']['name']}")

PHP

$json = file_get_contents(
  'https://carnetia.ai/api/v2/verify/CAR-2026-MX-1042-GP6X'
);
$data = json_decode($json, true);
if ($data['ok'] && $data['agent']['status'] === 'active') {
    echo "Verified: " . $data['agent']['name'];
}

cURL

curl https://carnetia.ai/api/v2/verify/CAR-2026-MX-1042-GP6X

Rate Limits

Register endpoint: 3/min, 10/hour and 20/day per IP; 2/hour and 5/day per email
Other endpoints: fair use. Excess traffic may be limited without notice.

Exceeding limits returns HTTP 429.

Errors

All errors return JSON with ok: false:

{
  "ok": false,
  "error": "agent_not_found",
  "message": "The ID CAR-... does not exist."
}

200 — Success
401 — Invalid credentials
404 — Resource not found
422 — Validation error (with errors object)
429 — Rate limited
500 — Server error

SDKs

Official SDKs are in development:

Node.js / TypeScript — npm install @carnetia/sdk (Q3 2026)
Python — pip install carnetia (Q3 2026)
PHP — composer require carnetia/sdk (Q3 2026)
Go — Q3 2026

Until then, use the REST API directly. Want early access to SDKs? Email [email protected].

Changelog

v2.0 (April 2026) — New ID format CAR-YYYY-CC-NNNN-XXXX with random suffix. Sanctum auth.
v1.0 (April 2026) — Initial public release.

Need help?

Email [email protected] · Open an issue on GitHub

API Documentation