Skip to main content

​
Overview

The AgenticPal API provides RESTful endpoints for programmatic access to the agent. It supports synchronous responses, streaming via Server-Sent Events (SSE), and conversation management. Base URL: http://localhost:8000 (development)

​
Authentication

All chat endpoints require authentication via session cookies. First, authenticate using the OAuth flow:
1

Start OAuth flow

curl http://localhost:8000/auth/login
This returns a Google OAuth URL.
2

Complete OAuth and get session

After OAuth callback, you’ll receive a session_id cookie that authenticates subsequent requests.

​
Synchronous Chat

Send a message and receive a complete response.

​
Endpoint

POST /chat

​
Request

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -b "session_id=your-session-id" \
  -d '{
    "user_message": "What meetings do I have today?",
    "thread_id": "main",
    "conversation_history": []
  }'

​
Response

{
  "response": "You have 2 meetings today: Team Standup at 9:00 AM and Client Call at 2:00 PM.",
  "thread_id": "main",
  "actions": [
    {
      "id": "action_1",
      "tool": "list_calendar_events",
      "success": true,
      "result": {
        "events": [
          {
            "summary": "Team Standup",
            "start": "2026-03-08T09:00:00Z"
          },
          {
            "summary": "Client Call",
            "start": "2026-03-08T14:00:00Z"
          }
        ]
      }
    }
  ],
  "requires_confirmation": false
}

​
Rate Limiting

The API implements rate limiting based on session ID or IP address:
  • Default limit: 60 requests per minute
  • Configure: Set RATE_LIMIT environment variable
export RATE_LIMIT="100/minute"
When rate limited, you’ll receive a 429 response: 
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again later."
}

​
CORS Configuration

By default, the API allows requests from:
  • http://localhost:3000 (dev server)
  • Your configured production frontend
Configure additional origins: 
export CORS_ORIGINS="http://localhost:3000,https://app.example.com,https://staging.example.com"

​
Health Check

Check API and Redis connectivity.

​
Endpoint

GET /health

​
Request

curl http://localhost:8000/health

​
Response

{
  "status": "healthy",
  "version": "0.1.0",
  "redis_connected": true,
  "timestamp": "2026-03-08T10:30:00Z"
}

​
Confirmation Flow

For destructive operations, the agent requests user confirmation.

​
Step 1: Send message that requires confirmation

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -b "session_id=your-session-id" \
  -d '{
    "user_message": "Delete all my draft emails"
  }'

​
Response

{
  "response": "I found 15 draft emails. Are you sure you want to delete all of them?",
  "thread_id": "thread_abc123",
  "requires_confirmation": true,
  "confirmation_message": "This will permanently delete 15 draft emails. Confirm?",
  "actions": [
    {
      "id": "action_1",
      "tool": "delete_emails",
      "success": false,
      "result": null
    }
  ]
}

​
Step 2: Confirm the action

curl -X POST http://localhost:8000/chat/confirm \
  -H "Content-Type: application/json" \
  -b "session_id=your-session-id" \
  -d '{
    "thread_id": "thread_abc123",
    "confirmation": "yes"
  }'

​
Response

{
  "thread_id": "thread_abc123",
  "status": "completed",
  "response": "I've successfully deleted 15 draft emails.",
  "results": {
    "action_1": {
      "tool": "delete_emails",
      "success": true,
      "result": {"deleted_count": 15}
    }
  }
}

​
Step 3: Cancel the action (alternative)

curl -X POST http://localhost:8000/chat/cancel \
  -H "Content-Type: application/json" \
  -b "session_id=your-session-id" \
  -d '{
    "thread_id": "thread_abc123"
  }'

​
Response

{
  "thread_id": "thread_abc123",
  "status": "cancelled",
  "response": "Action cancelled.",
  "cancelled": true
}

​
Error Handling

The API returns consistent error responses:

​
Authentication Error (401)

{
  "error": "not_authenticated",
  "message": "Authentication required. Please log in first."
}

​
Agent Error (500)

{
  "error": "agent_error",
  "message": "Agent error: Unable to connect to Google Calendar API"
}

​
Validation Error (422)

{
  "error": "validation_error",
  "message": "Invalid request format",
  "details": [
    {
      "loc": ["body", "user_message"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Thread Management

Conversations are organized by thread IDs for context management: 
import requests
import uuid

# Create a new thread
thread_id = str(uuid.uuid4())

# First message
response1 = requests.post(
    "http://localhost:8000/chat",
    cookies={"session_id": "your-session-id"},
    json={
        "user_message": "Schedule a meeting for tomorrow",
        "thread_id": thread_id
    }
)

# Follow-up message in same thread
response2 = requests.post(
    "http://localhost:8000/chat",
    cookies={"session_id": "your-session-id"},
    json={
        "user_message": "Make it at 2pm",
        "thread_id": thread_id  # Same thread for context
    }
)
If you don’t provide a thread_id, the API will generate one automatically. Include it in follow-up requests to maintain conversation context.

​
API Documentation

Interactive API documentation is available at:

Swagger UI

Interactive API explorer with request/response examples

ReDoc

Alternative API documentation interface

Build docs developers (and LLMs) love

Get started for freeTalk to us