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 is only returned once during registration. Store it securely.

Check trust score

Get the current trust score and breakdown:

bash

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

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

Register the MCP servers your agent talks to. The request lists each server in mcp_servers; this one lists the server from step 4:

bash

curl -X PUT "$AIM_URL/api/v1/agents/$AGENT_ID/mcp-servers" \
  -H "Authorization: Bearer $AIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_servers": [
      {
        "name": "filesystem-server",
        "url": "stdio://filesystem-server",
        "capabilities": ["read_file", "write_file", "list_directory"]
      }
    ]
  }'

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	PUT	/api/v1/agents/:id
Delete agent	DELETE	/api/v1/agents/:id
Get trust score	GET	/api/v1/agents/:id/trust-score
List MCP servers	GET	/api/v1/mcp-servers
Register MCP server	POST	/api/v1/mcp-servers
List an agent's MCP servers	GET	/api/v1/agents/:id/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 the AIM security architecture