API Overview - Naive API v2

Base URL

https://api.usenaive.ai

For local development, the API runs at http://localhost:3101 and the container sidecar at http://localhost:3100.

Authentication

All endpoints (except /skill.md, /register.md, /health, and /v1/auth/register) require:

Authorization: Bearer nv_sk_live_...

Response Format

All responses are JSON. Successful responses return the data directly. Errors follow:

{
  "error": {
    "code": "error_code",
    "message": "Human readable description",
    "hint": "Actionable next step for the agent",
    "reason": "OPTIONAL_GRANULAR_REASON"
  }
}

code is the canonical kind (rate_limited, forbidden, invalid_input, etc.) and maps 1:1 to the HTTP status. Some endpoints also return a more granular reason field (e.g. RATE_LIMITED, PROTECTED_RECORD, UNOWNED_RECORD_REQUIRES_ACK) plus extra context fields. Rate-limit responses include a standard Retry-After header.

Conventions

All timestamps are ISO 8601 with timezone (UTC)
UUIDs are used for all entity IDs
Pagination uses limit and offset query parameters
Mutation endpoints support Idempotency-Key header

Live event stream

Subscribe to a company-scoped Server-Sent Events stream:

GET /v1/events
Authorization: Bearer nv_sk_live_...
Accept: text/event-stream

Frames look like:

event: domain.updated
id: 42
data: {"id":42,"companyId":"...","type":"domain.updated","createdAt":"2026-05-08T...","payload":{"action":"dns_record_set","domainId":"..."}}

Currently emitted event types:

Type	Payload	Emitted when
`domain.updated`	`{ action: "dns_record_set" \| "dns_record_deleted" \| "agent_managed", domainId }`	An agent successfully writes/deletes a DNS record, or apex A/AAAA flips to agent_managed
`activity.logged`	`{ actorType, actorId, action, entityType, entityId, agentId, runId, details }`	Any audit-logged event (every DNS edit, including rejections)

The stream emits a : heartbeat <ts> comment every ~25s so intermediate proxies don’t idle the connection out.

Audit log

DNS edit endpoints (and any future writes that opt in) append rows to the shared activity_log table with these actions:

Action	Triggered by
`dns.record.set`	Successful POST to `/v1/domains/:id/zone-records`
`dns.record.delete`	Successful DELETE to `/v1/domains/:id/zone-records/:recordId`
`dns.record.rejected`	Any guard-rail rejection (rate limit, protected record, unowned ack required, etc.)

Each row carries entity_type = "domain", entity_id = <domainId>, the calling agent_id when known, and a details JSONB blob with the granular reason plus operation-specific context.

Core Endpoints

Group	Key Endpoints
Auth	`POST /v1/auth/register`, `POST /v1/auth/login`, `POST /v1/auth/link`
Identity	`GET /v1/identity`, `GET /v1/identity/emails`, `GET /v1/identity/resources`
Domains	`GET /v1/domains`, `POST /v1/domains/connect`, `GET /v1/domains/:id/dns-records`, `POST /v1/domains/:id/verify`, `GET /v1/domains/search`, `POST /v1/domains/purchase`, `GET /v1/domains/:id/zone-records`, `POST /v1/domains/:id/zone-records`, `DELETE /v1/domains/:id/zone-records/:recordId`
Billing	`GET /v1/billing/plans`, `POST /v1/billing/subscribe`, `POST /v1/billing/upgrade`, `GET /v1/billing/subscription`, `POST /v1/billing/portal`, `GET /v1/billing/packs`, `POST /v1/billing/topup`
Email	`GET /v1/email/inboxes`, `POST /v1/email/inboxes`, `POST /v1/email/send`
Search	`POST /v1/search`, `POST /v1/search/url`, `POST /v1/search/research`
Images	`POST /v1/images/generate`, `GET /v1/images/models`, `GET /v1/images/pricing`
Video	`POST /v1/video/generate`, `GET /v1/video/models`, `GET /v1/video/pricing`
Social	`GET /v1/social/status`, `POST /v1/social/activate`, `POST /v1/social/connect`, `POST /v1/social/portal`, `GET /v1/social/accounts`, `POST /v1/social/posts`, `POST /v1/social/posts/:id/publish`
SEO	`POST /v1/seo/keywords/{engine}/{endpoint}`, `POST /v1/seo/backlinks/{endpoint}`, `POST /v1/seo/labs/{engine}/{endpoint}`
App Data	`POST /v1/app-data/{platform}/{endpoint}`, `GET /v1/app-data/{platform}/{endpoint}/tasks-ready`, `GET /v1/app-data/{platform}/{endpoint}/:task_id`
Business Data	`POST /v1/business/{platform}/{endpoint}`, `POST /v1/business/social/{platform}`
AEO	`POST /v1/aeo/llm-responses/{llm}`, `POST /v1/aeo/llm-scraper/{endpoint}`, `POST /v1/aeo/llm-mentions/{endpoint}`, `POST /v1/aeo/ai-keywords/search-volume`
E-commerce	`POST /v1/ecommerce/{platform}/{endpoint}/task`, `GET /v1/ecommerce/{platform}/{endpoint}/tasks-ready`, `GET /v1/ecommerce/{platform}/{endpoint}/task/:id`
Verification	`POST /v1/verification`, `GET /v1/verification`, `GET /v1/verification/:id`, `POST /v1/verification/members/:id/complete`, `POST /v1/verification/members/:id/resend`
Formation	`GET /v1/formation/naics-codes`, `POST /v1/formation` (creates $249 checkout), `POST /v1/formation/:id/retry-payment`, `POST /v1/formation/:id/submit` (after payment), `GET /v1/formation`, `GET /v1/formation/:id`, `GET /v1/formation/:id/documents`, `GET /v1/formation/:id/documents/:docId`
Jobs	`GET /v1/jobs`, `GET /v1/jobs/:id`, `DELETE /v1/jobs/:id`
Status	`GET /v1/status`, `GET /v1/usage`
Events	`GET /v1/events` (Server-Sent Events stream of company-scoped live events)

Discovery Endpoints

Method	Path	Auth	Description
GET	`/skill.md`	No	Full capability documentation (markdown)
GET	`/register.md`	No	Agent onboarding guide (markdown)
GET	`/health`	No	Health check

Container & Sidecar

Each company gets a container running the Hermes CEO gateway and sidecar. The API communicates with it via the company_containers table.

Sidecar Endpoints

All sidecar routes require Authorization: Bearer <container_auth_token> (resolved from the DB).

Route	Method	Description
`/health`	GET	Container + gateway health status
`/provision`	POST	Assign a warm-pool container to a company
`/control/:companyId/ceo/run`	POST	Start a CEO run with a prompt
`/control/:companyId/ceo/runs/:runId/stream`	GET	SSE stream of CEO run output
`/control/:companyId/ceo/runs/:runId`	GET	Get run status
`/control/:companyId/tasks`	GET/POST	List or create kanban tasks
`/control/:companyId/tasks/:id`	GET/PATCH	Get or update a task
`/control/:companyId/tasks/:id/complete`	POST	Mark task complete
`/control/:companyId/tasks/dispatch`	POST	Trigger task dispatch
`/control/:companyId/agents`	GET	List Hermes profiles
`/control/:companyId/agents/provision`	POST	Create a new employee profile
`/control/:companyId/cron`	GET/POST	List or create cron jobs
`/control/:companyId/memory`	GET	Read agent memory
`/control/:companyId/status`	GET	Detailed container status

Data Flow

The sidecar runs a mirror process that watches kanban.db and MEMORY.md files in the Hermes home directory and syncs changes to the datastore. This is how the Studio UI and API see task updates in real-time without polling the container directly.

MCP Server

Method	Path	Auth	Description
GET	`/mcp/sse`	Yes	Establish SSE connection
POST	`/mcp/messages`	Session	Send MCP messages

​Base URL

​Authentication

​Response Format

​Conventions

​Live event stream

​Audit log

​Core Endpoints

​Discovery Endpoints

​Container & Sidecar

​Sidecar Endpoints

​Data Flow

​MCP Server