API Overview

Complete API reference for ATOM SaaS platform endpoints.

Base URLs

Production:

• API: https://[your-tenant].atomagentos.com/api
• App: https://[your-tenant].atomagentos.com

Development:

• Local: http://localhost:3000
• Backend: http://localhost:8000

Authentication

All API requests require authentication:

JWT Token Authentication

# Get token from login response
export TOKEN="your_jwt_token_here"

# Include in requests
curl -H "Authorization: Bearer $TOKEN" \
  https://[your-tenant].atomagentos.com/api/v1/agents

API Key Authentication

# Use API key for service accounts
export API_KEY="your_api_key_here"

curl -H "X-API-Key: $API_KEY" \
  https://api.atom.io/api/agents

Rate Limiting

Headers returned:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 450
X-RateLimit-Reset: 1707225600

Response Format

All API responses follow this structure:

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2025-02-06T10:00:00Z",
    "request_id": "req_abc123"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with ID 'xxx' not found",
    "details": { ... }
  },
  "meta": {
    "timestamp": "2025-02-06T10:00:00Z",
    "request_id": "req_abc123"
  }
}

API Endpoints by Category

Agent Management

List, create, update, delete, and execute AI agents.

Full Agent API Documentation →

Graduation & Episodic Memory

Manage agent maturity progression and track execution episodes.

Full Graduation API Documentation →

Canvas & Marketplace

Create, install, and manage canvas components and skills.

Full Marketplace API Documentation →

Integrations

Manage third-party service integrations.

Full Integration API Documentation →

Chat & Sessions

Real-time agent conversations.

MCP (Model Context Protocol)

Interoperability with external tools.

Desktop App

Desktop-specific commands (Tauri).

Common Request Patterns

Pagination

List endpoints support pagination:

GET /api/agents?page=1&limit=20

Response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Filtering

Filter results with query parameters:

GET /api/agents?maturity_level=student&status=active

Sorting

Sort results:

GET /api/agents?sort=created_at&order=desc

Search

Search across text fields:

GET /api/agents?q=assistant

Error Codes

SDKs

Official SDKs for popular languages:

TypeScript/JavaScript

npm install @atom/sdk

import { AtomClient } from '@atom/sdk';

const client = new AtomClient({
  apiKey: process.env.ATOM_API_KEY
});

const agents = await client.agents.list();
const agent = await client.agents.create({
  name: 'My Agent',
  role: 'general-assistant'
});

Python

pip install atom-python-sdk

from atom import AtomClient

client = AtomClient(api_key="your_api_key")

agents = client.agents.list()
agent = client.agents.create(
    name="My Agent",
    role="general-assistant"
)

Webhooks

Receive real-time notifications:

Configure Webhook

POST /api/webhooks

{
  "url": "https://your-app.com/webhooks/atom",
  "events": ["agent.executed", "agent.graduated"],
  "secret": "webhook_secret"
}

Webhook Events

agent.executed - Agent completed task execution

{
  "event": "agent.executed",
  "data": {
    "agent_id": "agent_123",
    "execution_id": "exec_456",
    "status": "success",
    "result": { ... }
  },
  "timestamp": "2025-02-06T10:00:00Z"
}

agent.graduated - Agent reached new maturity level

{
  "event": "agent.graduated",
  "data": {
    "agent_id": "agent_123",
    "previous_level": "intern",
    "new_level": "supervised",
    "readiness_score": 0.85
  },
  "timestamp": "2025-02-06T10:00:00Z"
}

OpenAPI Specification

Complete OpenAPI 3.0 specification available within your tenant context:

• Interactive Swagger UI: https://[your-tenant].atomagentos.com/api/docs
• JSON Spec: https://[your-tenant].atomagentos.com/api/openapi.json
• Redoc: https://[your-tenant].atomagentos.com/api/redoc

Support

• Documentation: https://atomagentos.com/docs
• Platform Support: support@atomagentos.com
• GitHub Issues: atom-saas/issues

Last Updated: 2025-02-06 API Version: v8.0