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 an agent is currently active, not just registered. 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.
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

Public endpoints: 60 requests/min/IP
Authenticated endpoints: 600 requests/min/token
Register endpoint: 5 requests/min/IP

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