Simple API v1 Documentation

Unified, easy-to-use API for document processing. Just 3 endpoints for complete workflow.

open_in_new Full Swagger Docs

Quick Start

Base URL: http://www.structora.eu/api/v1

Authentication: Authorization: Bearer YOUR_API_KEY

Content-Type: multipart/form-data for file uploads

Workflow: 1) Create template → 2) Process documents → 3) Get results

Complete Workflow Example

1a Suggest Schema: Upload sample document to get AI-suggested extraction fields
1b Create Template: Submit schema (suggested or custom) to create extraction template
2 Process Documents: Use template to extract data from 1 or many documents
3 Get Results: Poll job status and retrieve extracted data

📝 Step 1: Template Management

POST /api/v1/templates/suggest

Upload a sample document to get AI-suggested extraction schema

Example Request
curl -X POST "http://www.structora.eu/api/v1/templates/suggest" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "sample_file=@sample-invoice.pdf"
Example Response
{
  "success": true,
  "message": "Analyzed document and suggested 8 fields",
  "suggested_schema": {
    "fields": [
      {
        "field_name": "invoice_number",
        "data_type": "String",
        "description": "Invoice number"
      },
      {
        "field_name": "total_amount",
        "data_type": "Number", 
        "description": "Total invoice amount"
      }
    ]
  },
  "sample_filename": "sample-invoice.pdf",
  "fields_count": 8
}
POST /api/v1/templates

Create template with explicit schema (use suggested schema or create your own)

Example Request
curl -X POST "http://www.structora.eu/api/v1/templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Template",
    "description": "Extract invoice data",
    "category": "Financial",
    "schema": {
      "fields": [
        {
          "field_name": "invoice_number",
          "data_type": "String",
          "description": "Invoice number"
        },
        {
          "field_name": "total_amount",
          "data_type": "Number",
          "description": "Total invoice amount"
        },
        {
          "field_name": "due_date", 
          "data_type": "Date",
          "description": "Payment due date"
        }
      ]
    }
  }'
Schema Validation Rules

Required fields: name, schema

Valid categories: Financial, Manufacturing, Legal, Medical, Custom, Other

Valid data_types: String, Number, Date, Array, Boolean

Field names: Alphanumeric + underscores only (no spaces)

Required per field: field_name, data_type, description

Example Response
{
  "success": true,
  "template_id": "template-uuid-123",
  "name": "Invoice Template",
  "fields": 3,
  "message": "Template 'Invoice Template' created with 3 fields"
}
GET /api/v1/templates

List all available templates (custom + library)

Example Request
curl -X GET "http://www.structora.eu/api/v1/templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

🚀 Step 2: Process Documents

POST /api/v1/process

Upload and process documents (single or batch) with your template

Single Document Example
curl -X POST "http://www.structora.eu/api/v1/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "template_id=template-uuid-123" \
  -F "files=@invoice.pdf"

Note: Use multipart/form-data for file uploads. Files must be PDF format.

Batch Processing Example
curl -X POST "http://www.structora.eu/api/v1/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "template_id=template-uuid-123" \
  -F "files=@invoice1.pdf" \
  -F "files=@invoice2.pdf" \
  -F "files=@invoice3.pdf"
Example Response
{
  "success": true,
  "job_id": "job-uuid-456",
  "status": "processing",
  "message": "Processing 3 document(s)",
  "check_status_url": "/api/v1/jobs/job-uuid-456"
}

📊 Step 3: Get Results

GET /api/v1/jobs

List all your processing jobs with status and basic info

Example Request
curl -X GET "http://www.structora.eu/api/v1/jobs?status=completed&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
Query Parameters

status (optional): Filter by status - pending, running, completed, failed, cancelled

limit (optional): Max jobs to return (default: 50, max: 100)

Example Response
{
  "success": true,
  "jobs": [
    {
      "job_id": "job-uuid-456",
      "name": "API Processing - 3 document(s)",
      "status": "completed",
      "template_id": "template-uuid-123",
      "total_documents": 3,
      "completed_documents": 3,
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:32:15Z"
    },
    {
      "job_id": "job-uuid-789", 
      "name": "API Processing - 1 document(s)",
      "status": "processing",
      "template_id": "template-uuid-123",
      "total_documents": 1,
      "completed_documents": 0,
      "created_at": "2024-01-15T11:00:00Z",
      "completed_at": null
    }
  ],
  "count": 2,
  "message": "Found 2 jobs"
}
GET /api/v1/jobs/{job_id}

Get detailed job status and extracted data. Poll this endpoint until status is "completed"

Example Request
curl -X GET "http://www.structora.eu/api/v1/jobs/job-uuid-456" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response (Completed)
{
  "success": true,
  "job_id": "job-uuid-456",
  "status": "completed",
  "progress": "3/3",
  "results": [
    {
      "filename": "invoice1.pdf",
      "status": "completed",
      "data": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1250.00,
        "vendor": "ACME Corp",
        "due_date": "2024-02-15"
      }
    },
    {
      "filename": "invoice2.pdf",
      "status": "completed",
      "data": {
        "invoice_number": "INV-2024-002",
        "total_amount": 750.50,
        "vendor": "XYZ Ltd",
        "due_date": "2024-02-20"
      }
    }
  ]
}

🚨 Error Handling

Common Error Responses

401 Unauthorized
{
  "success": false,
  "message": "API key required. Include 'Authorization: Bearer YOUR_API_KEY' header."
}
429 Quota Exceeded
{
  "success": false,
  "message": "API quota exceeded. You have used 100 of 100 credits this month."
}
400 Bad Request - Invalid File
{
  "success": false,
  "message": "Only PDF files are supported. Invalid file: document.docx"
}
400 Bad Request - Invalid Category
{
  "success": false,
  "message": "Failed to create template: violates check constraint \"document_templates_category_check\""
}

Use valid categories: Financial, Manufacturing, Legal, Medical, Custom, Other

HTTP Status Codes

200 Success
400 Bad Request (invalid parameters)
401 Unauthorized (invalid API key)
429 Too Many Requests (quota exceeded)
500 Internal Server Error

Interactive API Explorer

Try out the API endpoints with full Swagger UI documentation