API Reference · Key Extraction v3

Jobs

หนึ่งงาน = หนึ่งเอกสารเชิงตรรกะ inputs[] คือหน้า/ส่วนเรียงตามลำดับ ไม่ใช่หลายเอกสารในคำขอเดียว

Create job

POSThttps://backend.aksonocr.com/api/v3/key-extract/jobs

	ค่า
HTTP	202 + header Location
Auth	`X-API-Key`
Idempotency	`Idempotency-Key` (จำเป็น)

Headers

Header	จำเป็น	รายละเอียด
`X-API-Key`	ใช่	คีย์จาก Dashboard
`Idempotency-Key`	ใช่	1–255 ตัวอักษร ขอบเขตต่อ tenant + endpoint

Idempotency

คีย์เดิม + body เดิม คืนงานเดิมโดยไม่คิดเงินซ้ำ คีย์เดิม + body ต่างได้ 409 idempotency_conflict

Body

ฟิลด์	ชนิด	จำเป็น	รายละเอียด
`inputs`	object[]	ใช่	อย่างน้อย 1 สูงสุด 50 ตามลำดับหน้า
`inputs[].file_id`	string	ใช่	จาก POST /files
`inputs[].pages`	integer[]	ไม่	หน้า PDF 1-based ไม่ซ้ำ ห้ามใช้กับรูป
`data_schema`	object	XOR	JSON Schema subset — รากเป็น object
`template`	object	XOR	{ id, version? } ถ้าไม่ระบุ version จะล็อก latest ตอนรับงาน
`instructions`	string	ไม่	≤ 10,000 ตัวอักษร ห้ามเปลี่ยน schema
`output.evidence`	enum	ไม่	bbox (ค่าเริ่มต้น) \| none
`review_threshold`	number	ไม่	0–1 ค่าเริ่มต้น 0.8
`client_reference`	string	ไม่	สะท้อนกลับ ไม่ส่งเข้าโมเดล ≤ 255
`webhook_id`	string	ไม่	id ที่ลงทะเบียนแล้ว — ไม่รับ URL
`retention_hours`	integer	ไม่	1–168 ค่าเริ่มต้น 24

ส่ง template หรือ data_schema อย่างใดอย่างหนึ่ง ฟิลด์ที่ไม่รู้จักจะถูกปฏิเสธ

curl -sS -X POST 'https://backend.aksonocr.com/api/v3/key-extract/jobs' \
  -H 'X-API-Key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: invoice-2026-001' \
  -d '{
    "client_reference": "invoice-2026-001",
    "inputs": [{ "file_id": "file_01J9..." }],
    "data_schema": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "invoice_no": { "type": "string", "description": "เลขที่ใบแจ้งหนี้" },
        "total": { "type": "number" }
      },
      "required": ["invoice_no"]
    },
    "output": { "evidence": "bbox" },
    "review_threshold": 0.8
  }'

Response 202

json

{
  "id": "ext_01JBY7...",
  "status": "queued",
  "client_reference": "invoice-2026-001",
  "created_at": "2026-09-06T10:00:00Z",
  "configuration": {
    "template": null,
    "schema_sha256": "5d3a...",
    "output": { "evidence": "bbox" },
    "review_threshold": 0.8
  },
  "links": {
    "self": "/api/v3/key-extract/jobs/ext_01JBY7...",
    "result": "/api/v3/key-extract/jobs/ext_01JBY7.../result"
  },
  "request_id": "req_01J..."
}

Get job (poll)

GEThttps://backend.aksonocr.com/api/v3/key-extract/jobs/{job_id}

คืนสถานะและความคืบหน้าเท่านั้น ไม่มีผลเต็ม แนะนำ backoff 2–5 วินาที เคารพ Retry-After

json

{
  "id": "ext_01JBY7...",
  "status": "processing",
  "progress": { "pages_total": 3, "pages_completed": 2 },
  "created_at": "2026-09-06T10:00:00Z",
  "started_at": "2026-09-06T10:00:01Z",
  "completed_at": null,
  "expires_at": "2026-09-07T10:00:00Z",
  "links": {
    "self": "/api/v3/key-extract/jobs/ext_01JBY7...",
    "result": "/api/v3/key-extract/jobs/ext_01JBY7.../result"
  },
  "request_id": "req_01J..."
}

status	ความหมาย
`queued`	รอเข้าคิว
`processing`	กำลังประมวลผล
`cancelling`	กำลังยกเลิก
`completed`	เสร็จ — ดึง /result ได้
`failed`	ล้มเหลว — อ่าน error
`cancelled`	ยกเลิกแล้ว
`expired`	หมดอายุตาม retention

client ควรมี default branch สำหรับสถานะใหม่ งาน failed มี error.code / message / retryable

List jobs

GEThttps://backend.aksonocr.com/api/v3/key-extract/jobs

Query	ชนิด	รายละเอียด
`status`	enum	กรองตามสถานะงาน
`cursor`	string	opaque cursor จากหน้าก่อน
`limit`	integer	1–100 ค่าเริ่มต้น 20

json

{
  "data": [{ "id": "ext_01JBY7...", "status": "completed" }],
  "has_more": true,
  "next_cursor": "cur_01J...",
  "request_id": "req_01J..."
}

Cancel job

POSThttps://backend.aksonocr.com/api/v3/key-extract/jobs/{job_id}/cancel

Best-effort ได้ 202 ถ้ายกเลิกจาก queued/processing งานที่จบแล้วได้ 409 already_terminal

Delete job

DELETEhttps://backend.aksonocr.com/api/v3/key-extract/jobs/{job_id}

204 ลบผลและปล่อย lease ของไฟล์ในงานนี้ ไม่ลบไฟล์ที่งานอื่นยังใช้อยู่

Errors

HTTP	code
400	`invalid_request, unknown_property, input_conflict`
409	`idempotency_conflict, already_terminal`
410	`file_expired`
413	`page_limit_exceeded`
422	`invalid_schema, unreadable_document`
429	`rate_limited`
503	`temporarily_unavailable, queue_full`

Files

Result