API Overview

The DocSnap API provides programmatic access to document upload, OCR processing, search, and management. Use it to build integrations, automate workflows, or connect DocSnap with your existing systems.

Base URL

https://api.openesl.com

For local development:

http://localhost:5001

Authentication

All API endpoints (except registration and login) require a Bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Tokens are obtained through the authentication endpoints. Access tokens expire after 1 hour; use the refresh endpoint to obtain new ones without re-authenticating.

Request Format

• Content-Type: application/json for most endpoints
• Multipart: multipart/form-data for file uploads
• JSON keys: All request and response keys use snake_case

Response Format

All successful responses return JSON. Dates use ISO 8601 format with timezone:

{
  "received_at": "2026-02-21T15:30:16.258193+00:00"
}

UUIDs are lowercase hyphenated strings:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Pagination

List endpoints support pagination with limit and offset query parameters:

GET /v1/documents?limit=20&offset=40

Paginated responses include a paging object:

{
  "items": [...],
  "paging": {
    "limit": 20,
    "offset": 40,
    "total": 156
  }
}

Parameter	Default	Maximum	Description
limit	50	200	Number of items to return
offset	0	--	Number of items to skip

Rate Limiting

Certain endpoints are rate-limited to prevent abuse:

Endpoint	Limit
Registration	5 per hour per IP
Login	3 free attempts, then exponential backoff (15s to 5min)
Resend verification	1 per minute, 5 per hour
Forgot password	1 per minute, 5 per hour

When rate-limited, the API returns status 429 with a Retry-After header indicating when you can retry.

Error Handling

All errors follow a consistent format. See the Error Codes reference for a complete list.

{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "Document not found."
  }
}

SDKs and Libraries

Currently, the API is accessed directly via HTTP requests. The DocSnap iOS app serves as a reference implementation for API integration.

Quick Test

# Login and get a token
TOKEN=$(curl -s -X POST https://api.openesl.com/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"yourpassword"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# List your documents
curl -s https://api.openesl.com/v1/documents \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool