epsimo-agent 0.1.0 → 0.2.0

package/references/api_reference.md

@@ -1,34 +1,802 @@
-# Reference Documentation for Epsimo Agent
-
-This is a placeholder for detailed reference documentation.
-Replace with actual reference content or delete if not needed.
-
-Example real reference docs from other skills:
-- product-management/references/communication.md - Comprehensive guide for status updates
-- product-management/references/context_building.md - Deep-dive on gathering context
-- bigquery/references/ - API references and query examples
-
-## When Reference Docs Are Useful
-
-Reference docs are ideal for:
-- Comprehensive API documentation
-- Detailed workflow guides
-- Complex multi-step processes
-- Information too lengthy for main SKILL.md
-- Content that's only needed for specific use cases
-
-## Structure Suggestions
-
-### API Reference Example
-- Overview
-- Authentication
-- Endpoints with examples
-- Error codes
-- Rate limits
-
-### Workflow Guide Example
-- Prerequisites
-- Step-by-step instructions
-- Common patterns
-- Troubleshooting
-- Best practices
+# Epsimo API Reference
+
+Complete reference for the Epsimo Agent Platform API v1.0
+
+**Base URL:** `https://api.epsimoagents.com`
+
+---
+
+## Table of Contents
+
+1. [Authentication](#authentication)
+2. [HTTP Status Codes](#http-status-codes)
+3. [Error Handling](#error-handling)
+4. [Rate Limits](#rate-limits)
+5. [Projects](#projects)
+6. [Assistants](#assistants)
+7. [Threads](#threads)
+8. [Messages](#messages)
+9. [Files](#files)
+10. [Credits & Billing](#credits--billing)
+11. [Virtual Database](#virtual-database)
+
+---
+
+## Authentication
+
+All API requests require authentication using JWT tokens.
+
+### POST /auth/signup
+
+Register a new user account.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "secure-password"
+}
+```
+
+**Response (200):**
+```json
+{
+  "access_token": "eyJhbG...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "user": {
+    "email": "user@example.com",
+    "user_id": "usr_..."
+  }
+}
+```
+
+### POST /auth/login
+
+Authenticate and receive access token.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "secure-password"
+}
+```
+
+**Response (200):**
+```json
+{
+  "access_token": "eyJhbG...",
+  "token": "eyJhbG...",
+  "jwt_token": "eyJhbG...",
+  "expires_in": 3600
+}
+```
+
+**Error Response (401):**
+```json
+{
+  "error": "Invalid credentials",
+  "detail": "Email or password is incorrect"
+}
+```
+
+### GET /auth/thread-info
+
+Get current user information and thread usage.
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Response (200):**
+```json
+{
+  "email": "user@example.com",
+  "user_id": "usr_123",
+  "thread_counter": 45,
+  "thread_max": 100,
+  "subscription_tier": "standard"
+}
+```
+
+### Token Refresh
+
+Tokens expire after 1 hour. To refresh:
+
+```python
+# Python example
+import requests
+
+def refresh_token(expired_token):
+    # Re-authenticate with stored credentials
+    response = requests.post(
+        "https://api.epsimoagents.com/auth/login",
+        json={"email": stored_email, "password": stored_password}
+    )
+    return response.json()["access_token"]
+```
+
+---
+
+## HTTP Status Codes
+
+| Code | Meaning | Common Causes | Recommended Action |
+|------|---------|---------------|-------------------|
+| 200 | Success | Request completed successfully | Continue processing |
+| 201 | Created | Resource created successfully | Capture returned ID |
+| 204 | No Content | Deletion succeeded | Confirm success |
+| 400 | Bad Request | Invalid payload, missing fields | Validate request schema |
+| 401 | Unauthorized | Invalid/expired token | Refresh or re-authenticate |
+| 403 | Forbidden | Insufficient permissions | Check user/project access |
+| 404 | Not Found | Resource doesn't exist | Verify ID is correct |
+| 409 | Conflict | Duplicate resource | Check for existing records |
+| 422 | Validation Error | Schema validation failed | Review error details |
+| 429 | Too Many Requests | Rate limit exceeded | Implement exponential backoff |
+| 500 | Server Error | Backend issue | Retry with exponential backoff |
+| 503 | Service Unavailable | Temporary downtime | Wait and retry |
+
+---
+
+## Error Handling
+
+### Standard Error Response Format
+
+```json
+{
+  "error": "Error type",
+  "detail": "Detailed error message",
+  "field": "problematic_field_name",
+  "code": "ERROR_CODE"
+}
+```
+
+### Example Error Responses
+
+**Validation Error (422):**
+```json
+{
+  "error": "Validation Error",
+  "detail": "Field 'name' is required",
+  "field": "name"
+}
+```
+
+**Authentication Error (401):**
+```json
+{
+  "error": "Unauthorized",
+  "detail": "Token has expired or is invalid",
+  "code": "TOKEN_EXPIRED"
+}
+```
+
+### Retry Logic with Exponential Backoff
+
+```python
+import time
+import requests
+from requests.exceptions import HTTPError
+
+def make_request_with_retry(url, headers, method="GET", json_data=None, max_retries=5):
+    """Make API request with automatic retry on rate limits and server errors."""
+    for attempt in range(max_retries):
+        try:
+            response = requests.request(method, url, headers=headers, json=json_data)
+            response.raise_for_status()
+            return response.json() if response.content else None
+
+        except HTTPError as e:
+            if e.response.status_code == 429:
+                # Rate limited - exponential backoff
+                wait_time = min(60 * (2 ** attempt), 300)  # Max 5 minutes
+                print(f"Rate limited. Waiting {wait_time}s...")
+                time.sleep(wait_time)
+            elif e.response.status_code >= 500:
+                # Server error - retry with backoff
+                wait_time = min(10 * (2 ** attempt), 60)  # Max 1 minute
+                print(f"Server error. Waiting {wait_time}s...")
+                time.sleep(wait_time)
+            elif e.response.status_code == 401:
+                # Token expired - try to refresh
+                print("Token expired. Attempting refresh...")
+                raise
+            else:
+                # Other errors - don't retry
+                raise
+
+    raise Exception(f"Max retries ({max_retries}) exceeded")
+```
+
+---
+
+## Rate Limits
+
+| Tier | Limit |
+|------|-------|
+| Free | 60 requests/minute |
+| Standard | 300 requests/minute |
+| Premium | 1,000 requests/minute |
+
+**Rate Limit Headers:**
+```
+X-RateLimit-Limit: 300
+X-RateLimit-Remaining: 245
+X-RateLimit-Reset: 1672531200
+```
+
+When rate limited (429), wait and retry with exponential backoff (see [Error Handling](#error-handling)).
+
+---
+
+## Projects
+
+Projects are top-level containers for assistants, threads, and files.
+
+### GET /projects/
+
+List all projects for the authenticated user.
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Response (200):**
+```json
+[
+  {
+    "project_id": "proj_abc123",
+    "name": "My AI Project",
+    "description": "Customer support automation",
+    "created_at": "2024-01-15T10:30:00Z",
+    "access_token": "proj_token_..."
+  }
+]
+```
+
+### POST /projects/
+
+Create a new project.
+
+**Request:**
+```json
+{
+  "name": "My New Project",
+  "description": "Optional description",
+  "metadata": {
+    "custom_field": "value"
+  }
+}
+```
+
+**Response (201):**
+```json
+{
+  "project_id": "proj_xyz789",
+  "name": "My New Project",
+  "description": "Optional description",
+  "access_token": "proj_token_...",
+  "created_at": "2024-01-15T11:00:00Z"
+}
+```
+
+### GET /projects/{project_id}
+
+Get project details including project-specific access token.
+
+**Response (200):**
+```json
+{
+  "project_id": "proj_abc123",
+  "name": "My AI Project",
+  "description": "Customer support automation",
+  "access_token": "proj_token_...",
+  "token": "proj_token_...",
+  "jwt_token": "proj_token_...",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+**Note:** Use the `access_token` from this response for project-scoped operations (assistants, threads, files).
+
+### DELETE /projects/{project_id}?confirm=true
+
+Delete a project and all associated resources.
+
+**Query Parameters:**
+- `confirm=true` (required) - Confirmation flag
+
+**Response (204):**
+No content (successful deletion)
+
+---
+
+## Assistants
+
+Assistants are AI agents with specific instructions and capabilities.
+
+### GET /assistants/
+
+List all assistants in a project.
+
+**Headers:**
+```
+Authorization: Bearer <project_access_token>
+```
+
+**Response (200):**
+```json
+[
+  {
+    "assistant_id": "asst_abc123",
+    "name": "Support Agent",
+    "config": {
+      "instructions": "You are a helpful support agent",
+      "model": "gpt-4o",
+      "configurable": {
+        "type": "agent",
+        "agent_type": "agent"
+      }
+    },
+    "public": false,
+    "created_at": "2024-01-15T10:45:00Z"
+  }
+]
+```
+
+### POST /assistants/
+
+Create a new assistant.
+
+**Request:**
+```json
+{
+  "name": "Research Assistant",
+  "config": {
+    "instructions": "You help with research tasks",
+    "model": "gpt-4o",
+    "configurable": {
+      "type": "agent",
+      "agent_type": "agent"
+    },
+    "tools": [
+      {
+        "type": "search_tavily",
+        "max_results": 5
+      },
+      {
+        "type": "function",
+        "name": "update_database",
+        "description": "Save structured data",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "key": {"type": "string"},
+            "value": {"type": "object"}
+          },
+          "required": ["key", "value"]
+        }
+      }
+    ]
+  },
+  "public": false
+}
+```
+
+**Response (201):**
+```json
+{
+  "assistant_id": "asst_xyz789",
+  "name": "Research Assistant",
+  "config": { ... },
+  "public": false,
+  "created_at": "2024-01-15T11:15:00Z"
+}
+```
+
+### GET /assistants/{assistant_id}
+
+Get assistant details.
+
+**Response (200):**
+```json
+{
+  "assistant_id": "asst_abc123",
+  "name": "Support Agent",
+  "config": { ... },
+  "public": false,
+  "created_at": "2024-01-15T10:45:00Z"
+}
+```
+
+### DELETE /assistants/{assistant_id}
+
+Delete an assistant.
+
+**Response (204):**
+No content (successful deletion)
+
+---
+
+## Threads
+
+Threads represent persistent conversation contexts with Virtual Database state.
+
+### GET /threads/
+
+List all threads in a project.
+
+**Headers:**
+```
+Authorization: Bearer <project_access_token>
+```
+
+**Response (200):**
+```json
+[
+  {
+    "thread_id": "thread_abc123",
+    "name": "Customer #1234",
+    "assistant_id": "asst_xyz789",
+    "metadata": {
+      "configurable": {},
+      "type": "thread"
+    },
+    "created_at": "2024-01-15T12:00:00Z"
+  }
+]
+```
+
+### POST /threads/
+
+Create a new thread.
+
+**Request:**
+```json
+{
+  "name": "Customer Support Session",
+  "assistant_id": "asst_xyz789",
+  "metadata": {
+    "configurable": {},
+    "type": "thread"
+  },
+  "configurable": {
+    "type": "agent"
+  }
+}
+```
+
+**Response (201):**
+```json
+{
+  "thread_id": "thread_new123",
+  "name": "Customer Support Session",
+  "assistant_id": "asst_xyz789",
+  "created_at": "2024-01-15T12:30:00Z"
+}
+```
+
+### GET /threads/{thread_id}
+
+Get thread details and messages.
+
+**Response (200):**
+```json
+{
+  "thread_id": "thread_abc123",
+  "name": "Customer #1234",
+  "assistant_id": "asst_xyz789",
+  "messages": [
+    {
+      "role": "user",
+      "content": "Hello!",
+      "timestamp": "2024-01-15T12:01:00Z"
+    },
+    {
+      "role": "assistant",
+      "content": "How can I help you?",
+      "timestamp": "2024-01-15T12:01:05Z"
+    }
+  ]
+}
+```
+
+### POST /threads/{thread_id}/run
+
+Send a message and stream the assistant's response.
+
+**Request:**
+```json
+{
+  "message": "What's the status of my order?",
+  "stream": true
+}
+```
+
+**Response (Streaming):**
+```
+data: {"type": "start", "run_id": "run_123"}
+
+data: {"type": "content", "delta": "Your"}
+
+data: {"type": "content", "delta": " order"}
+
+data: {"type": "tool_call", "name": "database_query", "args": {...}}
+
+data: {"type": "done"}
+```
+
+### DELETE /threads/{thread_id}
+
+Delete a thread.
+
+**Response (204):**
+No content (successful deletion)
+
+---
+
+## Messages
+
+### GET /threads/{thread_id}/messages
+
+Get all messages in a thread.
+
+**Query Parameters:**
+- `limit` (optional): Max messages to return (default: 50)
+- `before` (optional): Cursor for pagination
+
+**Response (200):**
+```json
+{
+  "messages": [
+    {
+      "message_id": "msg_123",
+      "role": "user",
+      "content": "Hello",
+      "timestamp": "2024-01-15T12:00:00Z"
+    }
+  ],
+  "has_more": false
+}
+```
+
+### POST /threads/{thread_id}/messages
+
+Add a message to a thread (without triggering assistant).
+
+**Request:**
+```json
+{
+  "role": "user",
+  "content": "This is a manual message"
+}
+```
+
+**Response (201):**
+```json
+{
+  "message_id": "msg_new456",
+  "role": "user",
+  "content": "This is a manual message",
+  "timestamp": "2024-01-15T12:45:00Z"
+}
+```
+
+---
+
+## Files
+
+### GET /files/
+
+List all files in a project.
+
+**Headers:**
+```
+Authorization: Bearer <project_access_token>
+```
+
+**Response (200):**
+```json
+[
+  {
+    "file_id": "file_abc123",
+    "filename": "document.pdf",
+    "size": 1024567,
+    "mime_type": "application/pdf",
+    "uploaded_at": "2024-01-15T13:00:00Z"
+  }
+]
+```
+
+### POST /files/
+
+Upload a file.
+
+**Request (multipart/form-data):**
+```
+file: <binary file data>
+purpose: "assistants" | "retrieval"
+```
+
+**Response (201):**
+```json
+{
+  "file_id": "file_new789",
+  "filename": "document.pdf",
+  "size": 1024567,
+  "purpose": "retrieval",
+  "uploaded_at": "2024-01-15T13:15:00Z"
+}
+```
+
+### DELETE /files/{file_id}
+
+Delete a file.
+
+**Response (204):**
+No content (successful deletion)
+
+---
+
+## Credits & Billing
+
+### GET /credits/balance
+
+Get current thread usage and limits.
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Response (200):**
+```json
+{
+  "thread_counter": 45,
+  "thread_max": 100,
+  "threads_remaining": 55,
+  "subscription_tier": "standard"
+}
+```
+
+### POST /credits/checkout
+
+Create a Stripe checkout session for purchasing threads.
+
+**Request:**
+```json
+{
+  "quantity": 1000,
+  "amount": 80.00
+}
+```
+
+**Response (200):**
+```json
+{
+  "url": "https://checkout.stripe.com/session_...",
+  "session_id": "cs_..."
+}
+```
+
+**Pricing:**
+- < 500 threads: €0.10/thread
+- 500-999 threads: €0.09/thread
+- 1000+ threads: €0.08/thread
+
+---
+
+## Virtual Database
+
+Threads can serve as structured, persistent storage.
+
+### GET /db/{project_id}/{thread_id}
+
+Get all structured data from a thread.
+
+**Headers:**
+```
+Authorization: Bearer <project_access_token>
+```
+
+**Response (200):**
+```json
+{
+  "user_preferences": {
+    "theme": "dark",
+    "language": "en"
+  },
+  "status": "active",
+  "last_action": "checkout"
+}
+```
+
+### GET /db/{project_id}/{thread_id}/{key}
+
+Get specific key from thread state.
+
+**Response (200):**
+```json
+{
+  "theme": "dark",
+  "language": "en"
+}
+```
+
+### PUT /db/{project_id}/{thread_id}/{key}
+
+Set a key-value pair in thread state.
+
+**Request:**
+```json
+{
+  "value": {
+    "theme": "light",
+    "language": "es"
+  }
+}
+```
+
+**Response (200):**
+```json
+{
+  "success": true,
+  "key": "user_preferences",
+  "value": {
+    "theme": "light",
+    "language": "es"
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Token Management
+- Cache tokens and refresh on 401 errors
+- Store tokens securely (never in version control)
+- Use project-specific tokens for multi-tenant apps
+
+### 2. Error Handling
+- Always implement retry logic for 429 and 500+ errors
+- Use exponential backoff with jitter
+- Log errors for debugging
+
+### 3. Rate Limiting
+- Implement client-side throttling
+- Respect `X-RateLimit-*` headers
+- Consider upgrading tier for higher limits
+
+### 4. Security
+- Use HTTPS for all requests
+- Validate SSL certificates in production
+- Never expose API keys in frontend code
+- Use environment variables for credentials
+
+### 5. Performance
+- Use streaming for long-running conversations
+- Implement pagination for large result sets
+- Cache frequently accessed data
+- Batch operations when possible
+
+---
+
+## Code Examples
+
+See [README.md](../README.md) for comprehensive Python SDK examples.
+
+---
+
+## Support
+
+- **GitHub Issues:** https://github.com/thierryteisseire/epsimo-agent/issues
+- **Documentation:** [SKILL.md](../SKILL.md)
+- **Virtual DB Guide:** [docs/virtual_db_guide.md](../docs/virtual_db_guide.md)
+
+---
+
+**API Version:** 1.0  
+**Last Updated:** 2024-02-11