API

The API documentation provides you with all necessary information for programmatically integrating EASE-AI into your applications. Here you'll find detailed endpoint descriptions, authentication methods, and code examples. Use this section when you want to integrate Ease into your existing systems or create automated workflows.

Authentication

Authentication is the first step for secure API access. Learn how to generate, manage, and securely use API tokens. Proper authentication is fundamental for all API operations.

API Token Authentication

API token authentication provides a secure method for programmatic access. Each token grants specific access rights and can be revoked if needed. Token-based authentication is the recommended method for API access.

API Endpoints

The API endpoints form the interface between your application and EASE-AI. Each endpoint provides specific functionalities for document management. The endpoints are RESTful and follow modern API design principles.

Upload Endpoint

The upload endpoint allows uploading new documents into the system. You can upload individual files in PDF, text, or image format and optionally enable OCR, categorization, and entity extraction. The response includes a document ID for further operations.

Request:

# Form data with:
- file: The file to upload (multipart/form-data)
- extraction_options: ["ocr", "category", "entities"]

Response:

{
    "message": "Document queued for processing successfully",
    "document_id": 123,
    "status": 200
}

Update Endpoint

The update endpoint allows modifying document metadata such as name, category, tags, and entities. You can update individual fields or multiple properties simultaneously. Changes take effect immediately in the system.

Request:

{
    "id": 123,
    "name": "new_name.pdf",
    "category": "invoices",
    "entities": "{\"entity1\": [\"value1\", \"value2\"], \"entity2\": [\"value1\"]}",
    "tag": "important"
}

Response:

{
    "message": "Document updated successfully",
    "document_id": 123,
    "status": 200
}

Get Endpoint

The get endpoint provides detailed information about a specific document. The response includes document content, metadata, categorization, and extracted entities. Ideal for displaying document details or integrating with other systems.

Response:

{
    "name": "example.pdf",
    "content": "document_text_content",
    "category": "invoices",
    "entities": {"entity1": ["value1", "value2"]},
    "document_id": 123,
    "tag": "important",
    "created_at": "2024-03-21T10:00:00Z",
    "status": 200
}

Delete Endpoint

The delete endpoint allows removing documents from the system. You can delete individual documents by their ID. The operation permanently removes both metadata and stored files.

Request:

{
    "document_id": 123
}

Response:

{
    "message": "Document deleted successfully",
    "document_id": 123,
    "status": 200
}

Search Endpoint

The search endpoint provides flexible search capabilities for your documents. You can search by name, category, tags, or entities and sort results by various criteria. The search supports pagination for large result sets.

Request:

# Query parameters:
- search: "search term"
- field: "name" (Options: name, category, entities, tag, created_at)
- sort_by: "created_at" (Options: category, created_at)
- sort_order: "desc" (Options: asc, desc)
- limit: 30 (Maximum: 100)

Response:

{
    "document_ids": [123, 124, 125],
    "status": 200
}

Code Examples

The code examples show practical implementations of the API endpoints in Python. They demonstrate proper authentication, error handling, and all available operations. The examples can serve as a foundation for your own integration.

Python Code Examples

import requests
import json
import os

BASE_URL = "https://ease-ai.de"
API_TOKEN = "your_api_token_here"

# Configure headers with API token
headers = {
    "X-API-Key": f"{API_TOKEN}"
}

# Upload a document
def add_document(file_path, extraction_options):
    with open(file_path, 'rb') as f:
        file = {'file': (os.path.basename(file_path), f, 'application/pdf')}
        response = requests.post(
            f"{BASE_URL}/api/v1/document",
            headers=headers,
            files=file,
            data={"extraction_options": extraction_options}
        )
    return response.json()

# Get document details
def get_document(document_id):
    response = requests.get(
        f"{BASE_URL}/api/v1/document",
        params={"document_id": document_id},
        headers=headers
    )
    return response.json()

# Update document
def update_document(document_id, update_data):
    response = requests.put(
        f"{BASE_URL}/api/v1/document",
        data=update_data,
        headers=headers
    )
    return response.json()

# Search documents
def search_documents(search, field, sort_by, sort_order, limit):
    response = requests.get(
        f"{BASE_URL}/api/v1/search_documents",
        data={
            "search": search,
            "field": field,
            "sort_by": sort_by,
            "sort_order": sort_order,
            "limit": limit
        },
        headers=headers
    )
    return response.json()

# Delete document
def delete_document(document_id):
    response = requests.delete(
        f"{BASE_URL}/api/v1/document",
        data={"document_id": document_id},
        headers=headers
    )
    return response.json()

# Example usage
add_response = add_document("example.pdf", ["ocr", "category", "entities"])
document_id = add_response.get("document_id")

get_response = get_document(document_id)

update_data = {
    "id": document_id,
    "name": "updated_name.pdf",
    "category": "invoices",
    "entities": json.dumps({"entity1": ["value1", "value2"]})
}
update_response = update_document(document_id, update_data)

search_response = search_documents(
    search="invoice",
    field="name",
    sort_by="created_at",
    sort_order="desc",
    limit=10
)

delete_response = delete_document(document_id)

Error Handling

Error handling describes possible error scenarios and their meaning. Each error includes a descriptive text and an HTTP status code. The documentation helps you identify and handle errors appropriately.

Error Status Codes

• 401 - Not authenticated or invalid API token
• 403 - Invalid or expired API token
• 404 - Document not found
• 500 - Internal server error

Error Format:

{
    "error": "Error message description",
    "status": status_code
}