API Overview

The Alactic AGI API provides programmatic access to all document processing capabilities. Build custom integrations, automate workflows, and embed document intelligence into your applications with a simple RESTful API.

API Philosophy

Design Principles:

• RESTful: Standard HTTP methods (GET, POST, DELETE)
• JSON: All requests and responses use JSON
• Authentication: Deployment key-based authentication
• Idempotent: Safe to retry requests
• Versioned: API version in URL path
• Documented: Complete OpenAPI specification available

Base URL

https://your-vm-ip/api/v1

Or with custom domain (Pro+ Plan):

https://docs.yourcompany.com/api/v1

API Version:

• Current version: v1
• Version included in URL path for stability
• Breaking changes will result in new version (v2, v3, etc.)

Authentication

Deployment Key

All API requests require authentication using your deployment key.

Finding Your Deployment Key:

1. Login to dashboard
2. Navigate to Settings → API Access
3. Copy deployment key (format: ak-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)

Never share or commit your deployment key to version control.

Authentication Methods

Method 1: HTTP Header (Recommended)

curl -H "X-Deployment-Key: ak-your-key-here" \
     https://your-vm-ip/api/v1/health

Method 2: Query Parameter

curl "https://your-vm-ip/api/v1/health?key=ak-your-key-here"

Recommendation: Use HTTP header for better security (not logged in access logs).

Authentication Errors

Invalid Key:

{
  "error": "Invalid deployment key",
  "status": 401,
  "message": "The provided deployment key is not valid"
}

Missing Key:

{
  "error": "Authentication required",
  "status": 401,
  "message": "No deployment key provided"
}

Expired Key:

{
  "error": "Deployment key expired",
  "status": 401,
  "message": "This deployment has been deactivated"
}

Rate Limits

Rate limits vary by plan:

Plan	Requests/Second	Requests/Hour	Requests/Month
Free	10	1,000	50,000
Pro	20	5,000	150,000
Pro+	50	15,000	500,000
Enterprise	Custom	Custom	Unlimited

Rate Limit Headers:

Every response includes rate limit information:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset: 1614556800

Exceeding Rate Limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": "Rate limit exceeded",
  "status": 429,
  "message": "Too many requests. Retry after 30 seconds.",
  "retry_after": 30
}

Best Practice: Implement exponential backoff when receiving 429 responses.

API Endpoints

Health Check

GET /api/v1/health

Check API availability and service status.

Request:

curl https://your-vm-ip/api/v1/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-03-20T14:35:22Z",
  "services": {
    "api": "running",
    "worker": "running",
    "database": "connected",
    "azure_openai": "connected"
  }
}

No authentication required for health check.

Document Processing

POST /api/v1/process

Process a PDF document or URL.

Request (PDF):

curl -X POST https://your-vm-ip/api/v1/process \
  -H "X-Deployment-Key: ak-your-key" \
  -F "file=@document.pdf" \
  -F "model=gpt-4o-mini" \
  -F "analysis_depth=standard"

Request (URL):

curl -X POST https://your-vm-ip/api/v1/process \
  -H "X-Deployment-Key: ak-your-key" \
  -F "url=https://example.com/article" \
  -F "model=gpt-4o-mini" \
  -F "analysis_depth=standard"

Parameters:

Parameter	Type	Required	Description
file	File	Conditional	PDF file (required if not using url)
url	String	Conditional	URL to scrape (required if not using file)
model	String	Optional	gpt-4o-mini (default) or gpt-4o
analysis_depth	String	Optional	quick, standard (default), or deep
enable_vectors	Boolean	Optional	Enable vector storage (default: true)
webhook_url	String	Optional	Webhook for completion notification

Response:

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "estimated_time": 18,
  "message": "Document processing started"
}

Async Processing: API returns immediately. Poll for results or use webhook.

Get Job Status

GET /api/v1/jobs/{job_id}

Check processing status of a job.

Request:

curl -H "X-Deployment-Key: ak-your-key" \
     https://your-vm-ip/api/v1/jobs/job_abc123xyz

Response (Processing):

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "progress": 45,
  "created_at": "2024-03-20T14:35:22Z",
  "estimated_completion": "2024-03-20T14:35:40Z"
}

Response (Completed):

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "progress": 100,
  "created_at": "2024-03-20T14:35:22Z",
  "completed_at": "2024-03-20T14:35:38Z",
  "processing_time": 16.2,
  "result_url": "/api/v1/results/job_abc123xyz"
}

Response (Failed):

{
  "job_id": "job_abc123xyz",
  "status": "failed",
  "error": "PDF parsing failed",
  "message": "Unable to extract text from PDF",
  "created_at": "2024-03-20T14:35:22Z",
  "failed_at": "2024-03-20T14:35:30Z"
}

Status Values:

• queued: Waiting in queue
• processing: Currently being processed
• completed: Successfully finished
• failed: Processing failed

Get Results

GET /api/v1/results/{job_id}

Retrieve processing results.

Request:

curl -H "X-Deployment-Key: ak-your-key" \
     https://your-vm-ip/api/v1/results/job_abc123xyz

Response:

{
  "job_id": "job_abc123xyz",
  "document_id": "doc_xyz789",
  "status": "completed",
  "processing_time": 16.2,
  "model": "gpt-4o-mini",
  "content": {
    "text": "Full extracted text content...",
    "summary": "Document summary generated by AI...",
    "key_points": [
      "First key point extracted",
      "Second key point extracted",
      "Third key point extracted"
    ],
    "metadata": {
      "pages": 12,
      "words": 3450,
      "language": "en"
    }
  },
  "analysis": {
    "entities": [
      {
        "type": "person",
        "value": "John Smith",
        "confidence": 0.95
      },
      {
        "type": "company",
        "value": "Acme Corporation",
        "confidence": 0.88
      }
    ],
    "sentiment": {
      "overall": "positive",
      "score": 0.72
    }
  },
  "tokens": {
    "input": 8500,
    "output": 420,
    "total": 8920
  },
  "cost": {
    "amount": 0.0015,
    "currency": "USD"
  }
}

Batch Processing

POST /api/v1/batch

Process multiple documents in one request.

Request:

curl -X POST https://your-vm-ip/api/v1/batch \
  -H "X-Deployment-Key: ak-your-key" \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.pdf" \
  -F "files[]=@doc3.pdf" \
  -F "model=gpt-4o-mini"

Response:

{
  "batch_id": "batch_def456",
  "jobs": [
    {
      "job_id": "job_abc123",
      "filename": "doc1.pdf",
      "status": "queued"
    },
    {
      "job_id": "job_abc124",
      "filename": "doc2.pdf",
      "status": "queued"
    },
    {
      "job_id": "job_abc125",
      "filename": "doc3.pdf",
      "status": "queued"
    }
  ],
  "total_documents": 3,
  "estimated_time": 54
}

Batch Limits:

Plan	Max Files per Batch	Max Batch Size
Free	10 PDFs or 25 URLs	100 MB total
Pro	25 PDFs or 50 URLs	500 MB total
Pro+	50 PDFs or 100 URLs	2 GB total
Enterprise	500 PDFs or 1000 URLs	50 GB total

Get Batch Status

GET /api/v1/batches/{batch_id}

Check status of batch processing.

Request:

curl -H "X-Deployment-Key: ak-your-key" \
     https://your-vm-ip/api/v1/batches/batch_def456

Response:

{
  "batch_id": "batch_def456",
  "status": "processing",
  "total_documents": 3,
  "completed": 1,
  "processing": 1,
  "queued": 1,
  "failed": 0,
  "progress": 33,
  "jobs": [
    {
      "job_id": "job_abc123",
      "status": "completed",
      "result_url": "/api/v1/results/job_abc123"
    },
    {
      "job_id": "job_abc124",
      "status": "processing"
    },
    {
      "job_id": "job_abc125",
      "status": "queued"
    }
  ]
}

Delete Document

DELETE /api/v1/documents/{document_id}

Delete a processed document and its results.

Request:

curl -X DELETE \
  -H "X-Deployment-Key: ak-your-key" \
  https://your-vm-ip/api/v1/documents/doc_xyz789

Response:

{
  "status": "deleted",
  "document_id": "doc_xyz789",
  "message": "Document and all associated data deleted successfully"
}

List Documents

GET /api/v1/documents

List all processed documents.

Request:

curl -H "X-Deployment-Key: ak-your-key" \
     "https://your-vm-ip/api/v1/documents?limit=10&offset=0"

Parameters:

Parameter	Type	Default	Description
limit	Integer	50	Number of results (1-100)
offset	Integer	0	Pagination offset
status	String	all	Filter by status: all, completed, failed
model	String	all	Filter by model
from_date	String	-	Filter from date (ISO 8601)
to_date	String	-	Filter to date (ISO 8601)

Response:

{
  "total": 245,
  "limit": 10,
  "offset": 0,
  "documents": [
    {
      "document_id": "doc_xyz789",
      "filename": "contract.pdf",
      "status": "completed",
      "model": "gpt-4o-mini",
      "created_at": "2024-03-20T14:35:22Z",
      "processing_time": 16.2
    },
    {
      "document_id": "doc_xyz788",
      "filename": "invoice.pdf",
      "status": "completed",
      "model": "gpt-4o-mini",
      "created_at": "2024-03-20T12:22:10Z",
      "processing_time": 12.8
    }
  ]
}

Usage Statistics

GET /api/v1/usage

Get current usage statistics.

Request:

curl -H "X-Deployment-Key: ak-your-key" \
     https://your-vm-ip/api/v1/usage

Response:

{
  "current_month": {
    "pdfs_processed": 45,
    "urls_scraped": 132,
    "total_documents": 177,
    "quota": {
      "pdfs": 100,
      "urls": 200
    },
    "remaining": {
      "pdfs": 55,
      "urls": 68
    },
    "percentage_used": {
      "pdfs": 45,
      "urls": 66
    }
  },
  "storage": {
    "used_gb": 3.2,
    "total_gb": 5.0,
    "percentage": 64
  },
  "tokens": {
    "input": 2450000,
    "output": 385000,
    "cost": 0.87
  },
  "model_distribution": {
    "gpt-4o-mini": {
      "documents": 140,
      "cost": 0.21
    },
    "gpt-4o": {
      "documents": 37,
      "cost": 0.93
    }
  }
}

Webhooks

Configuring Webhooks

Receive notifications when processing completes.

Set webhook in processing request:

curl -X POST https://your-vm-ip/api/v1/process \
  -H "X-Deployment-Key: ak-your-key" \
  -F "file=@document.pdf" \
  -F "webhook_url=https://your-app.com/webhook"

Or configure default webhook:

Dashboard → Settings → API → Webhook URL

Webhook Payload

Success:

{
  "event": "job.completed",
  "job_id": "job_abc123",
  "document_id": "doc_xyz789",
  "status": "completed",
  "timestamp": "2024-03-20T14:35:38Z",
  "result_url": "/api/v1/results/job_abc123"
}

Failure:

{
  "event": "job.failed",
  "job_id": "job_abc123",
  "status": "failed",
  "error": "PDF parsing failed",
  "timestamp": "2024-03-20T14:35:30Z"
}

Webhook Requirements:

• Must return 2xx status code within 10 seconds
• HTTPS recommended (HTTP allowed)
• Retried up to 3 times on failure (exponential backoff)

Webhook Security

Verify webhook signature:

Each webhook includes signature header:

X-Alactic-Signature: sha256=abc123def456...

Verify in your application:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Webhook secret: Found in Settings → API → Webhook Secret

Error Handling

Error Response Format

{
  "error": "Error type",
  "status": 400,
  "message": "Human-readable error message",
  "details": {
    "field": "Additional error details"
  },
  "request_id": "req_abc123"
}

Common HTTP Status Codes

Code	Meaning	Action
200	Success	Continue
201	Created	Resource created successfully
400	Bad Request	Fix request parameters
401	Unauthorized	Check authentication
403	Forbidden	Check permissions or IP whitelist
404	Not Found	Resource doesn't exist
429	Too Many Requests	Implement rate limiting backoff
500	Internal Server Error	Retry or contact support
503	Service Unavailable	Temporary issue, retry later

Error Examples

Invalid File Type:

{
  "error": "Invalid file type",
  "status": 400,
  "message": "Only PDF files are supported for document processing",
  "details": {
    "file_type": "image/jpeg",
    "supported_types": ["application/pdf"]
  }
}

File Too Large:

{
  "error": "File too large",
  "status": 400,
  "message": "File size exceeds maximum allowed",
  "details": {
    "file_size_mb": 120,
    "max_size_mb": 100
  }
}

Quota Exceeded:

{
  "error": "Quota exceeded",
  "status": 429,
  "message": "Monthly PDF processing quota exceeded",
  "details": {
    "quota": 100,
    "used": 100,
    "resets_at": "2024-04-01T00:00:00Z"
  }
}

Best Practices

1. Authentication

• Store deployment key securely (environment variables, secret manager)
• Never commit keys to version control
• Rotate keys if compromised (contact support)
• Use HTTPS header authentication (not query parameters)

2. Error Handling

Implement retry logic with exponential backoff:

import time

def api_call_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, ...)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                # Rate limit - wait and retry
                retry_after = int(e.response.headers.get('Retry-After', 30))
                time.sleep(retry_after)
            elif e.response.status_code >= 500:
                # Server error - exponential backoff
                wait_time = 2 ** attempt
                time.sleep(wait_time)
            else:
                # Client error - don't retry
                raise
    raise Exception("Max retries exceeded")

3. Async Processing

Poll for results instead of waiting synchronously:

def process_document(file_path):
    # Submit job
    response = requests.post(
        f"{BASE_URL}/api/v1/process",
        headers={"X-Deployment-Key": DEPLOYMENT_KEY},
        files={"file": open(file_path, "rb")}
    )
    job_id = response.json()["job_id"]
    
    # Poll for completion
    while True:
        status = requests.get(
            f"{BASE_URL}/api/v1/jobs/{job_id}",
            headers={"X-Deployment-Key": DEPLOYMENT_KEY}
        ).json()
        
        if status["status"] == "completed":
            # Get results
            results = requests.get(
                f"{BASE_URL}/api/v1/results/{job_id}",
                headers={"X-Deployment-Key": DEPLOYMENT_KEY}
            ).json()
            return results
        elif status["status"] == "failed":
            raise Exception(status["error"])
        
        # Wait before next poll
        time.sleep(5)

Better: Use webhooks to avoid polling.

4. Batch Processing

Process multiple documents in batches for efficiency:

def process_batch(file_paths):
    files = [("files[]", open(f, "rb")) for f in file_paths]
    
    response = requests.post(
        f"{BASE_URL}/api/v1/batch",
        headers={"X-Deployment-Key": DEPLOYMENT_KEY},
        files=files
    )
    
    return response.json()["batch_id"]

5. Resource Cleanup

Delete documents when no longer needed:

def cleanup_old_documents(days=90):
    # Get documents older than 90 days
    from_date = (datetime.now() - timedelta(days=days)).isoformat()
    
    response = requests.get(
        f"{BASE_URL}/api/v1/documents",
        headers={"X-Deployment-Key": DEPLOYMENT_KEY},
        params={"to_date": from_date}
    )
    
    for doc in response.json()["documents"]:
        # Delete document
        requests.delete(
            f"{BASE_URL}/api/v1/documents/{doc['document_id']}",
            headers={"X-Deployment-Key": DEPLOYMENT_KEY}
        )

SDK Libraries

Official SDKs

Python SDK (Recommended):

pip install alactic-agi

Node.js SDK:

npm install alactic-agi

Documentation:

• Python SDK Guide
• Node.js SDK Guide
• REST API Reference

Community SDKs

• Ruby SDK (community-maintained)
• PHP SDK (community-maintained)
• Java SDK (community-maintained)

Check GitHub for latest community SDKs.

OpenAPI Specification

Download OpenAPI spec:

curl https://your-vm-ip/api/v1/openapi.json > alactic-api-spec.json

Use with tools:

• Import into Postman
• Generate client libraries with OpenAPI Generator
• Validate requests with OpenAPI validators

API Changelog

Version 1.0 (Current)

• Initial API release
• Document processing endpoints
• Batch processing support
• Webhook notifications
• Usage statistics API

Upcoming Features

• Streaming API for real-time results
• Advanced search endpoints
• Custom prompt templates
• Fine-tuning API (Enterprise)

Related Documentation

• API Authentication
• Processing Documents
• Batch Operations
• Python SDK
• Node.js SDK
• Webhooks Guide
• Error Reference