API Reference

Agents API

Complete API reference for creating, managing, and interacting with AI agents.

List Agents

Retrieve all agents for the authenticated tenant.

GET /api/v1/agents

# Request
curl https://api.engrami.com/api/v1/agents?tenant_id=tenant_xyz \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "items": [
    {
      "id": "agent_abc123",
      "name": "Customer Support Agent",
      "description": "Handles customer inquiries",
      "model": "gpt-4",
      "status": "active",
      "memory_enabled": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Create Agent

Create a new AI agent with specified configuration.

POST /api/v1/agents

# Request
curl -X POST https://api.engrami.com/api/v1/agents?tenant_id=tenant_xyz \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "description": "AI agent for research tasks",
    "model": "gpt-4",
    "system_prompt": "You are a helpful research assistant...",
    "memory_config": {
      "semantic_enabled": true,
      "episodic_enabled": true,
      "procedural_enabled": false
    },
    "tools": ["web_search", "document_reader"],
    "temperature": 0.7,
    "max_tokens": 4096
  }'

# Response
{
  "id": "agent_def456",
  "name": "Research Assistant",
  "description": "AI agent for research tasks",
  "model": "gpt-4",
  "status": "active",
  "memory_config": {
    "semantic_enabled": true,
    "episodic_enabled": true,
    "procedural_enabled": false
  },
  "tools": ["web_search", "document_reader"],
  "created_at": "2024-01-15T10:30:00Z"
}

Get Agent

Retrieve a specific agent by ID.

GET /api/v1/agents/{agent_id}

# Request
curl https://api.engrami.com/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "id": "agent_abc123",
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "model": "gpt-4",
  "system_prompt": "You are a helpful customer support agent...",
  "status": "active",
  "memory_config": {
    "semantic_enabled": true,
    "episodic_enabled": true,
    "procedural_enabled": true
  },
  "tools": ["knowledge_base", "ticket_creation"],
  "statistics": {
    "total_conversations": 1523,
    "avg_response_time": "2.3s",
    "satisfaction_rate": 0.94
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T15:45:00Z"
}

Update Agent

Update an existing agent's configuration.

PUT /api/v1/agents/{agent_id}

# Request
curl -X PUT https://api.engrami.com/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enhanced Support Agent",
    "temperature": 0.5,
    "tools": ["knowledge_base", "ticket_creation", "escalation"]
  }'

# Response
{
  "id": "agent_abc123",
  "name": "Enhanced Support Agent",
  "status": "active",
  "updated_at": "2024-01-20T16:00:00Z"
}

Delete Agent

Delete an agent and optionally its associated memory.

DELETE /api/v1/agents/{agent_id}

# Request
curl -X DELETE https://api.engrami.com/api/v1/agents/agent_abc123?delete_memory=true \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "success": true,
  "message": "Agent and associated memory deleted successfully"
}

Chat with Agent

Send a message to an agent and receive a response.

POST /api/v1/agents/{agent_id}/chat

# Request
curl -X POST https://api.engrami.com/api/v1/agents/agent_abc123/chat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How do I reset my password?",
    "conversation_id": "conv_xyz789",
    "context": {
      "user_id": "user_123",
      "platform": "web"
    }
  }'

# Response
{
  "response": "To reset your password, please follow these steps:\n\n1. Click on 'Forgot Password' on the login page...",
  "conversation_id": "conv_xyz789",
  "message_id": "msg_abc123",
  "tokens_used": 245,
  "memory_accessed": ["kb_article_456", "kb_article_789"],
  "latency_ms": 1823
}

Stream Chat Response

Stream responses in real-time using Server-Sent Events.

POST /api/v1/agents/{agent_id}/chat/stream

# Request
curl -X POST https://api.engrami.com/api/v1/agents/agent_abc123/chat/stream \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Explain quantum computing"
  }'

# Response (SSE stream)
data: {"type": "start", "message_id": "msg_abc123"}
data: {"type": "token", "content": "Quantum"}
data: {"type": "token", "content": " computing"}
data: {"type": "token", "content": " is"}
...
data: {"type": "end", "tokens_used": 523}

Agent Memory Operations

Get Agent Memory

GET /api/v1/agents/{agent_id}/memory

# Request
curl https://api.engrami.com/api/v1/agents/agent_abc123/memory?type=semantic&limit=10 \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "items": [
    {
      "id": "mem_123",
      "type": "semantic",
      "content": "Company refund policy: 30 days...",
      "embedding_model": "text-embedding-ada-002",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 156
}

Clear Agent Memory

DELETE /api/v1/agents/{agent_id}/memory

# Request
curl -X DELETE https://api.engrami.com/api/v1/agents/agent_abc123/memory?type=episodic \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "success": true,
  "deleted_count": 234,
  "message": "Episodic memory cleared successfully"
}

Continue to Workflows API