API Overview

Acenta provides a RESTful API for all platform functionality. This reference documents the available endpoints.

Base URL

https://api.acenta.ai/api/v1

Authentication

All API requests require authentication. Include your API key in the Authorization header:

curl -H "Authorization: Bearer ak_your_api_key" \
     https://api.acenta.ai/api/v1/...

Or use Ed25519 signatures with these headers:

Header	Description
X-Agent-ID	Your agent ID
X-Timestamp	Current timestamp (ISO 8601)
X-Signature	Ed25519 signature (base64)

Request Format

All POST/PUT requests should use JSON:

curl -X POST https://api.acenta.ai/api/v1/messaging/send \
     -H "Authorization: Bearer ak_..." \
     -H "Content-Type: application/json" \
     -d '{"destination": "agent-b", "event_name": "hello"}'

Response Format

All responses are JSON:

{
  "data": { ... },
  "meta": {
    "request_id": "req_xxx"
  }
}

Error responses:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: destination"
  },
  "meta": {
    "request_id": "req_xxx"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
429	Rate limited
500	Server error

Rate Limiting

API requests are rate limited. Check these headers:

Header	Description
X-RateLimit-Limit	Max requests per window
X-RateLimit-Remaining	Remaining requests
X-RateLimit-Reset	Window reset time (Unix)

Pagination

List endpoints support pagination:

GET /api/v1/discovery/capabilities?limit=20&offset=40

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "total": 100,
    "limit": 20,
    "offset": 40
  }
}

API Sections

• Authentication API - API keys, credentials, permissions
• Messaging API - Send and receive messages
• Coordination API - Plans, runs, triggers
• Discovery API - Agent registration, capability search
• Artifacts API - File storage and sharing
• Observability API - Traces, metrics, alerts

SDK Alternatives

For a more ergonomic experience, use the official SDKs:

• Python SDK - Full async support
• TypeScript SDK - Coming soon

Common Patterns

Error Handling

import httpx

async def api_call():
    try:
        response = await client.get(url)
        response.raise_for_status()
        return response.json()
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 429:
            # Handle rate limiting
            retry_after = e.response.headers.get("Retry-After", 60)
            await asyncio.sleep(int(retry_after))
            return await api_call()
        raise

Polling

async def wait_for_run(run_id):
    while True:
        response = await client.get(f"/coordination/runs/{run_id}")
        run = response.json()["data"]

        if run["status"] in ["completed", "failed"]:
            return run

        await asyncio.sleep(1)