API Reference

REST API endpoints for developers who want programmatic access to Autonomis.

Most users do not need the API. Everything listed here is available through the Dashboard with a friendly interface. The API is for developers who want to automate workflows or build custom integrations.

Base URL

https://api.autonomis.nexaminds.ai/api/v1

Authentication

All API requests require an API key sent in the X-API-Key header:

Example request header

X-API-Key: your-api-key-here

You can find your API key in the dashboard. Keep it secret — anyone with your key can manage your agents.

Error Responses

When something goes wrong, the API returns a JSON object with an error field describing the problem:

Error response

{
  "error": "agent not found"
}

For security reasons, server errors (5xx) always return a generic "internal server error" message without revealing internal details.

User Management

Create and manage user accounts and change plans.

Method	Path	Description
POST	/api/v1/users	Create a new user account
GET	/api/v1/users	List all users
GET	/api/v1/users/{user}	Get user details and agents
DELETE	/api/v1/users/{user}	Delete user and all their data
PUT	/api/v1/users/{user}/tier	Change the user's plan

Agent Management

Create, list, and delete agents. Check agent health and rotate API keys.

Method	Path	Description
POST	/api/v1/users/{user}/agents	Create one or more agents
GET	/api/v1/users/{user}/agents	List all agents for a user
GET	/api/v1/users/{user}/agents/{agent}	Get agent details
DELETE	/api/v1/users/{user}/agents/{agent}	Delete an agent
POST	/api/v1/users/{user}/agents/{agent}/rotate-key	Generate a new API key for the agent
GET	/api/v1/users/{user}/agents/{agent}/ping	Check if the agent is online
GET	/api/v1/users/{user}/agents/{agent}/connect	Get gateway connection details
GET	/api/v1/users/{user}/deploy/status	Check deployment progress

Chat

Send messages to your agents and receive responses. The streaming endpoint uses Server-Sent Events (SSE) for real-time output.

Method	Path	Description
POST	/api/v1/users/{user}/agents/{agent}/chat	Send a message and get a response
POST	/api/v1/users/{user}/agents/{agent}/chat/stream	Send a message with streaming response (SSE)

Example: Send a message

POST /api/v1/users/{user}/agents/{agent}/chat

{
  "messages": [
    { "role": "user", "content": "Hello, what can you help me with?" }
  ]
}

Response:
{
  "message": "I can help you with research, writing, and analysis...",
  "agent": "manager"
}

Templates

Customize agent behavior with template files (SOUL.md, USER.md, TOOLS.md, HEARTBEAT.md). Set defaults for all agents, or override per agent.

Method	Path	Description
GET	/api/v1/users/{user}/agent-templates	Get user-level default templates
PUT	/api/v1/users/{user}/agent-templates	Update user-level default templates
GET	/api/v1/users/{user}/agents/{agent}/templates	Get per-agent template overrides
PUT	/api/v1/users/{user}/agents/{agent}/templates	Update per-agent template overrides

Secrets

Store encrypted environment variables (API keys, tokens, passwords) that your agents can use at runtime.

Method	Path	Description
PUT	/api/v1/users/{user}/secrets	Add or update secrets
GET	/api/v1/users/{user}/secrets	List secret keys (values are masked)
DELETE	/api/v1/users/{user}/secrets/{key}	Delete a secret

Agent Files

Read, write, and delete files in an agent's workspace.

Method	Path	Description
GET	/api/v1/users/{user}/agents/{agent}/files/*	Read a file from the agent's workspace
PUT	/api/v1/users/{user}/agents/{agent}/files/*	Write a file to the agent's workspace
DELETE	/api/v1/users/{user}/agents/{agent}/files/*	Delete a file from the workspace

Skills

Upload custom skills or install pre-built ones from the ClawHub marketplace.

Method	Path	Description
PUT	/api/v1/users/{user}/skills/{id}/file	Upload a custom skill
DELETE	/api/v1/users/{user}/skills/{id}/file	Delete a skill
POST	/api/v1/users/{user}/skills/{slug}/registry-install	Install a skill from ClawHub

Usage & Monitoring

Track token usage, view container logs, and update agent tool settings.

Method	Path	Description
GET	/api/v1/users/{user}/usage	Get token usage for the current month
GET	/api/v1/users/{user}/logs	Get container logs
PATCH	/api/v1/users/{user}/agents/{agent}/config	Update agent tool configuration

Health Check

GET /healthz

Response 200:
{
  "status": "ok"
}

Use this endpoint to verify the API is running. No authentication required.