AIM REST API Reference

Complete API documentation for Agent Identity Management with interactive examples

Base URL

https://aim.example.com/api/v1

Authentication

Bearer Token / API Key

Response Format

application/json

🔐 Authentication Methods

JWT Bearer Token (Web UI & User Access)

Used for web interface and user-authenticated requests. Obtained via login endpoint.

curl -H "Authorization: Bearer {access_token}" https://aim.example.com/api/v1/agents

API Key (SDK & Programmatic Access)

Used for SDK and automated agent operations. SHA-256 hashed with rate limiting.

curl -H "X-API-Key: {api_key}" https://aim.example.com/api/v1/sdk-api/agents/my-agent

📦 SDK Download & Zero-Config Setup

AIM provides pre-configured SDKs with embedded credentials - no API keys or configuration needed!

Download SDK Endpoint

curl -X GET https://aim.example.com/api/v1/sdk/download \
  -H "Authorization: Bearer {access_token}" \
  -o aim-sdk.zip

Using the SDK (One Line!)

# Extract and use - no pip install needed!
from aim_sdk import secure

# Your agent is now secure with zero configuration
agent = secure("my-agent")

⚡ Rate Limiting

All API endpoints implement rate limiting for security and performance:

Authenticated requests: 1000 requests per minute
Public endpoints: 100 requests per minute
SDK API (with API key): 5000 requests per minute
Auth endpoints: 10 requests per minute (prevent brute force)

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

❌ Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  },
  "request_id": "req_123abc",
  "timestamp": "2024-01-01T12:00:00Z"
}

Common Error Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Rate Limited

500 Server Error