API Reference

Smart Agents REST API documentation for programmatic access to agents, templates, credits, and more

The Smart Agents API provides programmatic access to agent management, chat, template administration, credit tracking, and webhook configuration.

API endpoint canonical hostname. The Smart Agents API is served from api.agent.net.ai. Two earlier hostnames are now superseded:

bc.agent.net.ai (used by the BC extension before SA-085) stays bound to the same backend as a backward-compatible alias until 2027-05-17. HTTP-aware clients receive Deprecation: true + Sunset: response headers when calling via the alias.
api.smart.agent.net.ai appeared in earlier versions of these docs as an example host. It was never a production endpoint; the canonical URL has always been the same backend now reachable at api.agent.net.ai. All examples on this page use the canonical host.

Base URL

All API requests are made to the following base URL:

https://api.agent.net.ai/v1

Authentication

All API requests require a valid Bearer token. See the Authentication page for details on obtaining and using tokens.

curl -H "Authorization: Bearer <your-token>" \
  https://api.agent.net.ai/v1/agents

Response Format

All responses are returned as JSON. Successful responses include a data field. Error responses include an error field with a code and message.

Successful response:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-12T10:30:00Z"
  }
}

Error response:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required.",
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Status Code	Description
200	Success
201	Resource created
204	Success with no response body
400	Bad request — check the error message for details
401	Unauthorized — invalid or missing token
403	Forbidden — insufficient permissions
404	Resource not found
409	Conflict — resource already exists
422	Validation error — request body failed validation
429	Rate limited — too many requests
500	Internal server error

Rate Limits

API requests are rate-limited per API key:

Standard plan: 60 requests per minute
Professional plan: 300 requests per minute
Enterprise plan: 1,000 requests per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1712345678

Pagination

Endpoints that return lists support cursor-based pagination:

curl -H "Authorization: Bearer <token>" \
  "https://api.agent.net.ai/v1/agents?limit=20&cursor=eyJpZCI6MTAwfQ"

Pagination parameters:

Parameter	Type	Default	Description
`limit`	integer	20	Number of items per page (max 100)
`cursor`	string	—	Cursor from the previous response's `meta.next_cursor`

API Sections

Authentication — Token management and API key usage
Agents — Agent CRUD and chat endpoints
Templates — Template management
Credits — Credit balance and usage tracking
Webhooks — Event notifications (coming soon)