AimableDocs
DocsAPI Reference

Ingestion

Ingestion

The Ingestion domain of the Aimable Platform API (v0.1.0) enables you to upload, manage, and retrieve documents programmatically. This functionality is essential for building document-aware applications such as search systems, AI-powered chatbots, or compliance tools. By ingesting files into the platform, you make their content available for search, preview, and analysis — including PII (Personally Identifiable Information) and OII (Other Identifiable Information) detection.

Key Concepts

  • File: A document uploaded to the platform. Each file is assigned a unique source_id upon ingestion.
  • source_id: A string identifier representing a specific file in the document store. Used to reference files in subsequent operations.
  • PII/OII Detection: Optional processing that identifies sensitive data in document content during search or preview.
  • Document Store: Central repository where ingested files are stored and indexed for retrieval.

How to Use the Ingestion Endpoints

1. Ingest Files

Upload one or more files to the document store.

Endpoint: POST /api-proxy/v1/files/

curl -X POST "https://api.aimable.com/api-proxy/v1/files/" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: multipart/form-data" \
  -F "files=@/path/to/document.pdf" \
  -F "files=@/path/to/spreadsheet.xlsx"

Note: The API accepts files in these formats: CSV, DOCX, HTML, JSON, MD, PPTX, PDF, TXT, XLSX.

Success Response (200):

{
  "source_ids": [
    "src_abc123",
    "src_def456"
  ]
}

2. Search Documents

Search across ingested documents with optional PII detection.

Endpoint: POST /api-proxy/v1/files/search?search_query=confidential

curl -X POST "https://api.aimable.com/api-proxy/v1/files/search?search_query=confidential" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_ids": ["src_abc123", "src_def456"],
    "include_pii": true,
    "include_oii": false
  }'

Success Response (200):

{
  "results": [
    {
      "source_id": "src_abc123",
      "content": "This file contains confidential information...",
      "piis": [
        {
          "type": "EMAIL",
          "value": "john.doe@example.com"
        }
      ]
    }
  ]
}

3. Preview a File

Retrieve a processed preview of a document, optionally including PII/OII.

Endpoint: POST /api-proxy/v1/files/preview

curl -X POST "https://api.aimable.com/api-proxy/v1/files/preview" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "include_pii": true
  }'

Success Response (200):

{
  "source_id": "src_abc123",
  "content": "Document text with redacted or highlighted PII...",
  "piis": [
    {
      "type": "PHONE",
      "value": "+1-555-123-4567"
    }
  ]
}

4. Get Raw File Content

Retrieve the raw text content of a file.

Endpoint: GET /api-proxy/v1/files/src_abc123/content

curl -X GET "https://api.aimable.com/api-proxy/v1/files/src_abc123/content" \
  -H "Authorization: Bearer <your-access-token>"

Success Response (200):

This is the full extracted text from the PDF...
No formatting, just plain content.

5. Delete Files

Remove one or more files from the document store.

Endpoint: DELETE /api-proxy/v1/files/

curl -X DELETE "https://api.aimable.com/api-proxy/v1/files/" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_ids": ["src_abc123", "src_def456"]
  }'

Success Response (200):

{
  "deleted_count": 2
}

Common Workflows

Ingest → Search → Preview

  1. Ingest your documents:

    POST /api-proxy/v1/files/ (with file attachments)
→ Get source_ids

  2. Search for relevant content:

    POST /api-proxy/v1/files/search?search_query=contract
→ Retrieve chunks with PII flagged

  3. Preview a specific file:

    POST /api-proxy/v1/files/preview
→ Inspect content and detected entities

Cleanup: Delete Unused Files

After processing or when files are obsolete:

DELETE /api-proxy/v1/files/
→ Remove by source_id

Authentication & Error Handling

All endpoints require authentication via the Authorization: Bearer <token> header. The X-API-Key header is optional but may be used for legacy compatibility.

Common Errors

  • 401 Unauthorized: Missing or invalid access token.
  • 403 Forbidden: Insufficient permissions for the requested action.
  • 422 Unprocessable Entity: Invalid input (e.g., missing source_id, malformed JSON).

Example 422 Response:

{
  "detail": [
    {
      "loc": ["body", "source_ids"],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}

Ensure proper error handling in your client to provide feedback during file processing.

Related Endpoints