API Quickstart

5 minutes

Integrate AIM directly using REST API calls. Perfect for custom integrations, microservices, or non-Python environments.

Prerequisites

• AIM running at http://localhost:8080
• An API key (get it from Settings → API Keys in the dashboard)
• curl or any HTTP client

Get Your API Key

1. Login to AIM at http://localhost:3000
2. Go to Settings → API Keys
3. Click Generate New Key
4. Copy your API key (starts with aim_)

bash

# Set your API key as an environment variable
export AIM_API_KEY="aim_your_api_key_here"
export AIM_URL="http://localhost:8080"

Register an Agent

bash

curl -X POST "$AIM_URL/api/v1/agents" \
  -H "Authorization: Bearer $AIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-api-agent",
    "display_name": "My API Agent",
    "description": "Agent created via REST API",
    "capabilities": ["read_data", "send_notifications"]
  }'

Response:

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-api-agent",
  "display_name": "My API Agent",
  "status": "pending",
  "trust_score": 50.0,
  "public_key": "base64-encoded-public-key...",
  "private_key": "base64-encoded-private-key...",
  "created_at": "2025-01-15T10:30:00Z"
}

⚠️ Save the private_key! It's only returned once during registration. Store it securely.

Log Agent Actions

Track what your agent does for audit and monitoring:

bash

# Replace AGENT_ID with the id from step 2
AGENT_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X POST "$AIM_URL/api/v1/agents/$AGENT_ID/actions" \
  -H "Authorization: Bearer $AIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "db:read",
    "resource": "users_table",
    "riskLevel": "low",
    "metadata": {
      "query": "SELECT * FROM users WHERE active = true",
      "rows_returned": 42
    }
  }'

Check Trust Score

Get the current trust score and breakdown:

bash

curl -X GET "$AIM_URL/api/v1/agents/$AGENT_ID/trust-score" \
  -H "Authorization: Bearer $AIM_API_KEY"

Response:

json

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "trust_score": 72.5,
  "factors": {
    "verification_status": 20.0,
    "age_factor": 8.5,
    "activity_factor": 15.0,
    "violation_factor": 20.0,
    "mcp_attestation": 0.0,
    "certificate_validity": 9.0,
    "alert_factor": 0.0,
    "capability_compliance": 0.0
  },
  "calculated_at": "2025-01-15T10:35:00Z"
}

Register an MCP Server

bash

curl -X POST "$AIM_URL/api/v1/mcp-servers" \
  -H "Authorization: Bearer $AIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem-server",
    "display_name": "Filesystem MCP Server",
    "server_url": "stdio://filesystem-server",
    "capabilities": ["read_file", "write_file", "list_directory"],
    "description": "Local filesystem access"
  }'

Link Agent to MCP Server

Connect your agent to registered MCP servers:

bash

MCP_SERVER_ID="mcp-server-uuid-here"

curl -X POST "$AIM_URL/api/v1/agents/$AGENT_ID/mcp-servers/$MCP_SERVER_ID" \
  -H "Authorization: Bearer $AIM_API_KEY"

Common API Endpoints

Operation	Method	Endpoint
List agents	GET	/api/v1/agents
Create agent	POST	/api/v1/agents
Get agent	GET	/api/v1/agents/:id
Update agent	PATCH	/api/v1/agents/:id
Delete agent	DELETE	/api/v1/agents/:id
Get trust score	GET	/api/v1/agents/:id/trust-score
Log action	POST	/api/v1/agents/:id/actions
List MCP servers	GET	/api/v1/mcp-servers
Register MCP server	POST	/api/v1/mcp-servers
Bulk acknowledge alerts	POST	/api/v1/admin/alerts/bulk-acknowledge

See the full API reference for all 160+ endpoints.

What's Next?

Full API Reference

Explore all 160+ endpoints

Authentication

OAuth, JWT, and API key options

MCP Attestation

Cryptographically verify MCP servers

Security Model

Understand AIM's security architecture