API Reference v1

AURA AI API Documentation

The AURA AI API exposes two computer vision processing endpoints accessible via simple multipart/form-data POST requests. Responses are structured JSON objects delivered in under 200ms on standard workloads. Authentication uses project-scoped Bearer tokens generated from your developer dashboard.

Base URLhttps://api.aura.ai
Versionv1
Content-Typemultipart/form-data

Authentication

All API requests must include an Authorization header carrying a project-scoped API key. Keys are generated per project from the Developer Projects section of your dashboard after creating an account.

API keys carry full project access. Never expose them in client-side JavaScript, public repositories, or browser network requests. Rotate compromised keys immediately from the dashboard.

Authorization Header Format

Authorization: Bearer aura_live_sk_YOUR_PROJECT_KEY

Key Prefix Reference

aura_live_sk_Production environment
aura_test_sk_Sandbox environment
POST/api/v1/execute/omr-scanner/

OMR Bubble Sheet Scanner

Accepts a JPEG or PNG image of an answer sheet and returns per-bubble grading results along with a perspective-rectified annotated output image URL. Applies homographic transformation to correct camera-angle distortion before coordinate grid mapping and bubble classification.

Request Parameters

ParameterTypeRequiredDescription
filefilerequiredJPEG or PNG image of the OMR answer sheet. Max 10 MB.
num_questionsintegeroptionalTotal number of questions on the sheet (1–200). Defaults to auto-detect.

Code Examples

curl -X POST https://api.aura.ai/v1/execute/omr-scanner/ \
  -H "Authorization: Bearer aura_live_sk_YOUR_PROJECT_KEY" \
  -F "file=@answer_sheet.jpg" \
  -F "num_questions=40"
import requests

url = "https://api.aura.ai/v1/execute/omr-scanner/"
headers = {"Authorization": "Bearer aura_live_sk_YOUR_PROJECT_KEY"}
files  = {"file": open("answer_sheet.jpg", "rb")}
data   = {"num_questions": 40}

response = requests.post(url, headers=headers, files=files, data=data)
result   = response.json()

print(result["status"])                   # "SUCCESS"
print(result["results"]["user_input"][0]) # {"question_no": 1, "ans_choice": 1, "remarks": None}
print(result["file_url"])                 # annotated marked-sheet S3 URL
import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const form = new FormData();
form.append("file", fs.createReadStream("answer_sheet.jpg"));
form.append("num_questions", "40");

const response = await fetch("https://api.aura.ai/v1/execute/omr-scanner/", {
  method: "POST",
  headers: {
    Authorization: "Bearer aura_live_sk_YOUR_PROJECT_KEY",
    ...form.getHeaders(),
  },
  body: form,
});

const result = await response.json();
console.log(result.results.user_input[0]);   // { question_no: 1, ans_choice: 1, remarks: null }
console.log(result.file_url);                // annotated sheet URL

Success Response 200 OK

{
  "status": "SUCCESS",
  "service_module": "omr-scanner",
  "execution_time_ms": 187,
  "file_url": "https://cdn.aura.ai/scans/3f9a1b2c_marked.jpg",
  "results": {
    "user_input": [
      { "question_no": 1, "ans_choice": 1, "remarks": null },
      { "question_no": 2, "ans_choice": 3, "remarks": null },
      { "question_no": 3, "ans_choice": null, "remarks": "Multiple bubbles selected" }
    ]
  }
}
POST/api/v1/execute/pdf-ocr/

PDF Text Extraction (OCR)

Accepts a PDF file and returns full structured text extracted from all pages. Handles multi-column layouts, scanned images, and mixed text/image PDFs. Supports documents up to 50 pages per request.

Request Parameters

ParameterTypeRequiredDescription
filefilerequiredPDF document for text extraction. Max 50 MB, up to 50 pages per call.

Code Example

curl -X POST https://api.aura.ai/v1/execute/pdf-ocr/ \
  -H "Authorization: Bearer aura_live_sk_YOUR_PROJECT_KEY" \
  -F "file=@document.pdf"

Success Response 200 OK

{
  "status": "SUCCESS",
  "service_module": "pdf-ocr",
  "execution_time_ms": 340,
  "file_url": null,
  "results": {
    "text": "Full extracted document text...",
    "pages": 3,
    "word_count": 812
  }
}

Error Codes

All errors return a JSON body with error and detail fields.

HTTP CodeError KeyCause & Resolution
401UnauthorizedMissing, invalid, or expired API key. Verify the Authorization header and regenerate the key if needed.
400Bad RequestThe file field is missing from the multipart body. Ensure the form-data key matches exactly.
402Payment RequiredInsufficient token balance in the project wallet. Purchase a refill pack from the Billing Hub.
422Processing FailureThe uploaded file could not be processed — blurry image, no OMR grid detected, or corrupted PDF.
503Service UnavailableThe underlying CV processing engine is temporarily unavailable. Retry after a short delay.

Error Response Shape

{
  "error": "Unauthorized",
  "detail": "Invalid or expired API key."
}

Rate Limits & Token Deduction

Token Deduction

1 token per successful API call

Concurrent Requests

No hard limit per project key

Playground Scans

Separate scan credit — no token cost

Token deductions are applied atomically after a SUCCESS response is generated. Failed requests (4xx / 5xx) do not consume tokens. Balance is tracked per global developer wallet — not per project.

Ready to integrate?

Create a free account, generate a project API key, and run your first OMR scan in minutes.

Get Started FreeView Pricing