ComPDF AI Open API Reference

This reference follows PRD Chapter 7 and documents the 23 formal Open API capabilities, all under /api/v2/**. Auxiliary and internal extension endpoints are intentionally excluded.

1. Base URLs and authentication

Open API base URL:

text

https://api-hub.compdf.com/api/v2

Recommended authentication header:

http

Authorization: Bearer <YOUR_API_KEY>

Java Open API endpoints also accept X-API-Key, Api-Key, or a raw API key in Authorization.

The org_id returned by API-key verification is the only trusted tenant identity. Callers cannot submit org_id or leaderId. Upload APIs require user_id as the personal file owner, and Java verifies that the user belongs to the API-key organization.

2. Ownership and API count

PRD 7.1 contains 24 rows. “Change file category” and “Change file template” describe the same capability, leaving 23 unique core APIs.

Owner	Count	Scope
Java WorkFlow	17	Files, batches, tasks, templates, results, classification, and assets
Python platform	6	Reminder-rule management
Total	23	Complete PRD Chapter 7 core scope

The API Gateway must route /api/v2/rules/** to Python. Other Open API routes in this reference are provided by Java. Python must expose external reminder-rule CRUD routes authenticated with a Service API Key, and the gateway must map the public paths in this section to those routes. Existing /v1/reminder_rule/** workbench routes that require a browser login session are not valid mapping targets for this Open API.

2.1 Complete route index

Scope	Count	Section
PRD core APIs	23	Section 4

The count uses unique HTTP method and path combinations.

2.2 PRD core API quick reference

No.	Method	Path	Capability
1	POST	`/api/v2/files/upload`	Upload files/URL and create a batch
2	DELETE	`/api/v2/files`	Delete by IDs, date range, or metadata
3	PUT	`/api/v2/files/{fileId}/template`	Change template and re-extract
4	GET	`/api/v2/batches/{batchId}/tasks`	List batch tasks
5	POST	`/api/v2/tasks/{taskId}/retry`	Restart a task from its mode-specific first processing phase
6	DELETE	`/api/v2/tasks/{taskId}`	Cancel an unfinished task
7	GET	`/api/v2/templates`	List templates
8	GET	`/api/v2/templates/{templateId}/fields`	Get template fields
9	POST	`/api/v2/templates`	Create a template
10	PUT	`/api/v2/templates/{templateId}`	Update a template
11	DELETE	`/api/v2/templates/{templateId}`	Delete a template
12	POST	`/api/v2/templates/{templateId}/sample`	Replace template sample
13	POST	`/api/v2/extract/{fileId}/fields`	Add fields and re-extract
14	GET	`/api/v2/tasks/{taskId}`	Get processing result
15	PUT	`/api/v2/tasks/{taskId}`	Edit/confirm result
16	GET	`/api/v2/classify/{taskId}/result`	Get classification result
17	POST	`/api/v2/rules`	Create a reminder rule
18	PUT	`/api/v2/rules/{ruleId}`	Update a reminder rule
19	GET	`/api/v2/rules`	List reminder rules
20	GET	`/api/v2/rules/{ruleId}`	Get reminder-rule details
21	PATCH	`/api/v2/rules/{ruleId}/status`	Enable/disable a rule
22	DELETE	`/api/v2/rules/{ruleId}`	Delete a reminder rule
23	GET	`/api/v2/assets`	Get organization assets

No. 3 also has compatibility alias PUT /api/v2/files/{fileId}/category, which is not counted again.

3. Common conventions

Java response envelope:

json

{
  "code": 200,
  "message": "success",
  "data": {}
}

Java may currently return a business error with HTTP 200, so clients must also inspect the response-body code. Successful R<Void> responses always contain data:null.

Identifiers:

fileId uniquely identifies a file.
In the current Java model, taskId equals fileId. A retry overwrites the same task result rather than creating another ID.
batchId groups one or more uploaded file tasks.
The id returned in a template-list item is the template ID used by every {templateId} path.

Task-result status values are pending_parsing, parsing, parsing_failed, pending_classification, classifying, classification_failed, pending_extraction, extracting, extraction_completed, extraction_failed, and cancelled. The task-page request parameter also accepts the legacy aggregate filters pending, processing, completed, failed, and cancelled.

Batch statuses: pending, processing, completed, failed, partial_failed, cancelled, empty.

Template field configuration:

json

{
  "prompt": "Extract the invoice number.",
  "mapping": null,
  "aliases": [
    "Invoice No.",
    "Invoice Number"
  ]
}

keys contains scalar fields. tableHeaders is a map of table name to column name to field configuration. In optional elementOrder, type is key or table, and name must reference a declared field/table. A table entry must list every column exactly once in columnOrder.

3.1 Calling conventions and field names

Examples use the production host. Replace placeholders such as <YOUR_API_KEY>, <TEMPLATE_ID>, and <FILE_ID> with real values.
Multipart requests use PRD snake_case parameters. Java JSON responses use the camelCase names returned by the current implementation.
A caller cannot submit a trusted organization identity. Upload user_id, when supplied, is the file owner and must belong to the verified organization. When omitted, it defaults to the API Key's verified org_id for backward compatibility. user_email is business metadata. Neither can change the API key's organization scope.
Except for the Python reminder-rule APIs where noted, examples use the Java code:200 success envelope.

Common GET request:

bash

curl --location 'https://api-hub.compdf.com/api/v2/templates' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Common JSON request:

bash

curl --location --request PUT 'https://api-hub.compdf.com/api/v2/tasks/<TASK_ID>' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"fields":{"invoice_no":"INV-001"},"confirm":true}'

3.2 Optional-parameter behavior

Endpoint	Optional parameter	When supplied	When omitted
`POST /files/upload`	`user_id`	Uses the supplied active user after organization validation	Uses verified `org_id` as the compatibility file owner
`POST /files/upload`	`template_id`	Uses the specified enabled template available to the organization (including an enabled default template) and skips classification	Classifies against enabled organization templates and defaults that are not disabled for the organization; upload fails if no candidate is available
`POST /files/upload`	`metadata`	Persists and forwards the JSON object as described in §4.1	No metadata is stored or sent
`POST /files/upload`	`user_email`	Saves it as upload-source reference data	The upload-source email remains empty
`GET /templates`	`search` / `status`	Narrows by name and `active`/`inactive` status	Returns published organization templates and system defaults, with default status projected for the verified organization
`POST /templates/{templateId}/sample`	`page`	Saves the supplied 1-based sample page value	Uses page `1`
`DELETE /files`	`file_ids`, `date_range`, `metadata_conditions`	Conditions are unioned; metadata entries are ANDed. Valid conditions with no matching file return success with `deletedCount:0`.	At least one condition is required; otherwise returns 400
`PUT /tasks/{taskId}`	`confirm`	`confirm:false` saves without confirming; field exceptions are returned for display and do not block confirmation	Defaults to `true`

For the current template-list implementation, an unrecognized status value is treated as no status filter. Clients should only send active or inactive.

4. The 23 core Open APIs

4.1 File management (1–3)

4.1.1 Upload files

POST /api/v2/files/upload, multipart/form-data.

Parameter	Required	Description
`file`	Either file or URL	Repeat the part to upload multiple files in one batch
`url`	Either file or URL	Publicly reachable source URL
`mode`	Yes	`VisualExtract` or `LayoutExtract`
`template_id`	No	Skip classification and use this template
`metadata`	No	JSON object string used as file/batch business context; see “metadata and user_email behavior” below
`user_id`	No	File owner. If supplied, it must be an active Java user in the API-key organization. If omitted, ownership defaults to the verified `org_id` for compatibility with existing callers.
`user_email`	No	Upload-source email retained for reference only; it is not identity, authorization, or notification input

bash

curl 'https://api-hub.compdf.com/api/v2/files/upload' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -F 'file=@/path/invoice.pdf' -F 'mode=VisualExtract' \
  -F 'template_id=<TEMPLATE_ID>' -F 'user_id=<USER_ID>' \
  -F 'metadata={"order_no":"SO-1001"}'

json

{
  "code": 200,
  "message": "success",
  "data": {
    "batchId": "batch_01",
    "fileIds": [
      "file_01"
    ],
    "taskIds": [
      "file_01"
    ],
    "uploadStatus": "processing"
  }
}

Metadata and user_email behavior

metadata must be a JSON object string, for example {"order_no":"SO-1001","source":"erp"}. Java preserves the raw string in the file and batch records. Batch-task, task-detail, and classification responses return it as their metadata field. Extraction-lifecycle, confirmation, Python reminder, and Python webhook events parse it as an object and pass it through.

The delete-files metadata_conditions object performs exact matching: every supplied key/value must match the persisted metadata object. A non-object/non-JSON value can still be retained as text, but cannot reliably participate in event payloads or metadata_conditions matching.

metadata does not take part in API-key authentication, organization scope, template selection, file-owner assignment, or asset charging. Do not include passwords, keys, or other sensitive values because it can be delivered to Python reminder and webhook flows.

user_email is only saved as the file's upload-source email. The current release does not use it to validate user_id, select an organization, send email, create reminder recipients, or alter file permissions. user_id is the file owner when supplied; otherwise the verified org_id is used as the compatibility owner.

4.1.2 Delete files

DELETE /api/v2/files, JSON body. Supply at least one of file_ids, date_range, or metadata_conditions; delete_permanently defaults to false.

json

{
  "file_ids": [
    "file_01"
  ],
  "date_range": {
    "start": "2026-07-01T00:00:00",
    "end": "2026-07-31T23:59:59"
  },
  "metadata_conditions": {
    "project_id": "P-001"
  },
  "delete_permanently": false
}

Response data contains deletedCount, failedCount, failedIds, and failedReasons. failedReasons maps each failed ID to its server-side failure message.

When valid criteria match no file, this is not an error: the endpoint returns deletedCount:0, failedCount:0, and an empty failedIds array. Matching includes every file with a persisted org_id equal to the verified organization, whether created from the browser or an API key, plus historical files with no org_id whose owner belongs to that organization.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "deletedCount": 2,
    "failedCount": 0,
    "failedIds": [],
    "failedReasons": {}
  }
}

4.1.3 Change a file template/category

Recommended PRD path: PUT /api/v2/files/{fileId}/template. Compatibility alias: PUT /api/v2/files/{fileId}/category.

json

{
  "group_template_id": "<GROUP_TEMPLATE_ID>"
}

Only group_template_id is accepted: it is the template-relation ID used by the browser template/group list. The endpoint does not accept the physical template-table ID or template_id. It preserves the file-to-template-group relation and follows the browser manual-group operation. Java resolves the related real template and validates it against the API-key organization (including organization-specific default-template enablement). The response includes the resolved templateId and the applied groupTemplateId. GET /api/v2/templates currently returns physical template id values only, so it cannot supply this relation ID; do not substitute its id here.

The same fileId/taskId is re-extracted and its previous result is replaced.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "fileId": "file_01",
    "templateId": "tpl_02",
    "groupTemplateId": "group_tpl_02",
    "taskId": "file_01"
  }
}

4.2 Task management (4–6)

4.2.1 List batch tasks

GET /api/v2/batches/{batchId}/tasks?status=processing. Optional status: pending, processing, completed, failed, or cancelled.

Response data contains batchId, batchStatus, and a tasks array with file/task IDs, filename, status, phase, confirmation status, metadata, and timestamps.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "batchId": "batch_01",
    "batchStatus": "processing",
    "tasks": [
      {
        "taskId": "file_01",
        "fileId": "file_01",
        "fileName": "invoice.pdf",
        "status": "processing",
        "phase": "extracting",
        "confirmStatus": "pending",
        "metadata": "{\"order_no\":\"SO-1001\"}"
      }
    ]
  }
}

4.2.2 Restart a task

POST /api/v2/tasks/{taskId}/retry. Any task except a deleted/cancelled one can be restarted. The current implementation reuses the same taskId/fileId and clears previous results. A LayoutExtract task always restarts from parsing; a VisualExtract task restarts from extracting.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "fileId": "file_01",
    "batchId": null,
    "status": "pending",
    "mode": "LayoutExtract",
    "startPhase": "parsing",
    "createdNewTask": false
  }
}

4.2.3 Cancel a task

DELETE /api/v2/tasks/{taskId}. Only pending or processing tasks can be cancelled. An unsettled asset reservation is released. Success returns data:null.

json

{
  "code": 200,
  "message": "success",
  "data": null
}

4.3 WorkFlow (7–16)

4.3.1 List templates

GET /api/v2/templates?search=invoice&status=active. Status may be active or inactive. The response is a flat array containing the verified organization's published templates and system default templates. A default template is included unless this organization has disabled it; its status is projected to the organization's enabled/disabled state. The template identifier field is id; source is organization or default, and default templates have editable:false.

json

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "tpl_01",
      "name": "Invoice",
      "fileId": "sample_01",
      "page": 1,
      "status": 1,
      "keys": {},
      "tableHeaders": {},
      "elementOrder": []
    }
  ]
}

4.3.2 Get template fields

GET /api/v2/templates/{templateId}/fields. Returns keys, tableHeaders, and optional elementOrder.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "keys": {
      "invoice_no": {
        "prompt": "Extract invoice number",
        "mapping": null,
        "aliases": []
      }
    },
    "tableHeaders": {},
    "elementOrder": []
  }
}

4.3.3 Create a template

Create the template with its sample file and field definition according to the request contract.

json

{
  "name": "Invoice",
  "fileId": "sample_01",
  "page": 1,
  "keys": {
    "invoice_no": {
      "prompt": "Extract invoice number",
      "mapping": null,
      "aliases": []
    }
  },
  "tableHeaders": {},
  "elementOrder": [
    {
      "type": "key",
      "name": "invoice_no",
      "columnOrder": null
    }
  ]
}

Name, sample fileId, and at least one scalar or table field are required. Response data is the new template ID.

json

{
  "code": 200,
  "message": "success",
  "data": "tpl_01"
}

4.3.4 Update a template

PUT /api/v2/templates/{templateId}. Uses the same field structure as creation and preserves the existing sample association. Success returns data:null.

json

{
  "code": 200,
  "message": "success",
  "data": null
}

4.3.5 Delete a template

DELETE /api/v2/templates/{templateId}. Performs a soft delete. Success returns data:null.

json

{
  "code": 200,
  "message": "success",
  "data": null
}

4.3.6 Upload or replace a template sample

POST /api/v2/templates/{templateId}/sample, multipart file, optional page defaulting to 1. Returns sampleFileId, fileName, and fileSize.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "sampleFileId": "sample_02",
    "fileName": "invoice.pdf",
    "fileSize": 102400
  }
}

4.3.7 Extract custom fields

POST /api/v2/extract/{fileId}/fields.

json

{
  "keys": {
    "purchase_order": {
      "prompt": "Extract PO number",
      "mapping": null,
      "aliases": [
        "PO"
      ]
    }
  },
  "tableHeaders": {}
}

The fields are merged into the file's template snapshot and the same file task is re-extracted with a new asset reservation.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "fileId": "file_01",
    "status": "pending"
  }
}

4.3.8 Get a task/file result

GET /api/v2/tasks/{taskId}. Returns status, phase, confirmation status, input, final fields/tables, ordered elements, raw parsing JSON for LayoutExtract, field exceptions, page consumption, metadata, and timestamps. It also returns batchId, taskType, templateId, groupTemplateId, templateName, and originalFile. extractionResult is the same final result as the compatibility field output; parsingResult is the parsed-object form of compatibility field layoutOutput; fieldExceptionDetails is the parsed form of compatibility field fieldExceptions. phase is only meaningful while work is pending or processing and is null for completed, failed, or cancelled tasks. error is exposed only for failed tasks, so a successful/retried task cannot retain a stale failure message.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "fileId": "file_01",
    "fileName": "invoice.pdf",
    "status": "completed",
    "phase": null,
    "confirmStatus": "pending",
    "metadata": "{\"order_no\":\"SO-1001\"}",
    "output": {
      "fields": {
        "invoice_no": "INV-001"
      },
      "tables": {},
      "orderedElements": []
    },
    "layoutOutput": null,
    "fieldExceptions": "[]",
    "input": {
      "fileId": "file_01",
      "templateId": "tpl_01",
      "templateName": "Invoice",
      "mode": "VisualExtract"
    },
    "consumption": {
      "pages": 1
    }
  }
}

4.3.9 Update a task/file result

PUT /api/v2/tasks/{taskId}.

json

{
  "fields": {
    "invoice_no": "INV-001-R"
  },
  "tables": {},
  "confirm": true
}

Supply fields or tables. Only completed, unconfirmed tasks can be edited. Field exceptions are returned for display and do not block confirmation.

confirm currently defaults to true; explicitly send false to save without confirming. expectedUpdateDate is accepted for backward compatibility but currently ignored.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "fileId": "file_01",
    "fileName": "invoice.pdf",
    "status": "completed",
    "phase": null,
    "confirmStatus": "confirmed",
    "metadata": "{\"order_no\":\"SO-1001\"}",
    "error": null,
    "updateDate": "2026-07-22T08:05:00",
    "output": {
      "fields": {
        "invoice_no": "INV-001-R"
      },
      "tables": {},
      "orderedElements": []
    },
    "layoutOutput": null,
    "fieldExceptions": "[]",
    "input": {
      "fileId": "file_01",
      "templateId": "tpl_01",
      "templateName": "Invoice",
      "mode": "VisualExtract"
    },
    "consumption": {
      "pages": 1
    }
  }
}

4.3.10 Get classification result

GET /api/v2/classify/{taskId}/result. Returns taskId, status, templateId, template name, optional confidence, and metadata.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "file_01",
    "status": "completed",
    "templateId": "tpl_01",
    "templateName": "Invoice",
    "confidence": null,
    "metadata": "{}"
  }
}

4.4 Reminder rules (17–22, Python)

Common rule body:

json

{
  "name": "Large invoice",
  "template_id": "tpl_01",
  "conditions": [
    {
      "field": "total_amount",
      "operator": "gt",
      "value": 10000,
      "logic": "AND"
    }
  ],
  "frequency": "on_extract_complete",
  "channels": [
    "in_app",
    "email"
  ],
  "recipients": {
    "members": [],
    "field_bindings": [],
    "webhook_ids": []
  },
  "title_template": "Invoice alert {file_name}",
  "content_template": "Total: {total_amount}"
}

No.	Method	Path	Contract
17	`POST`	`/api/v2/rules`	Create a rule and return its ID, name, status, and creation time
18	`PUT`	`/api/v2/rules/{ruleId}`	Update any supplied rule fields
19	`GET`	`/api/v2/rules?status=active`	List rules; status is optional (`active`/`inactive`)
20	`GET`	`/api/v2/rules/{ruleId}`	Return complete rule configuration
21	`PATCH`	`/api/v2/rules/{ruleId}/status`	Body `{"status":"active"}` or `{"status":"inactive"}`
22	`DELETE`	`/api/v2/rules/{ruleId}`	Permanently delete a rule

Python owns condition evaluation, notifications, email, webhook delivery/retries, and 24-hour deduplication. Python responses commonly use code:0 for success.

4.4.1 Create a reminder rule

name, template_id, conditions, frequency, channels, recipients, title_template, and content_template are required. The name is limited to 50 characters and must be unique within the organization. The title and content are limited to 100 and 500 characters respectively.

frequency accepts daily, hourly, on_extract_complete, or on_result_confirm. channels can contain in_app, email, and webhook. Condition logic is AND or OR; supported comparison operators depend on whether the selected field is numeric, text, or date.

bash

curl --location 'https://api-hub.compdf.com/api/v2/rules' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Large invoice",
    "template_id": "tpl_01",
    "conditions": [
      {"field": "total_amount", "operator": "gt", "value": 10000, "logic": "AND"}
    ],
    "frequency": "on_extract_complete",
    "channels": ["in_app", "email"],
    "recipients": {"members": [], "field_bindings": [], "webhook_ids": []},
    "title_template": "Invoice alert {file_name}",
    "content_template": "Total: {total_amount}"
  }'

json

{
  "code": 0,
  "message": "success",
  "data": {
    "rule_id": "rule_01",
    "name": "Large invoice",
    "status": "active",
    "created_at": "2026-07-22T10:00:00Z"
  }
}

4.4.2 Update a reminder rule

The body may contain any field accepted by creation. Only submitted fields are changed.

json

{
  "name": "Very large invoice",
  "conditions": [
    {
      "field": "total_amount",
      "operator": "gte",
      "value": 20000,
      "logic": "AND"
    }
  ]
}

The response data contains the complete updated rule.

4.4.3 List reminder rules

The optional status query parameter is active or inactive. Omitting it returns all rules in the current organization.

json

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "rule_id": "rule_01",
      "name": "Large invoice",
      "template_id": "tpl_01",
      "status": "active",
      "channels": [
        "in_app",
        "email"
      ],
      "frequency": "on_extract_complete",
      "created_at": "2026-07-22T10:00:00Z",
      "updated_at": "2026-07-22T10:00:00Z"
    }
  ]
}

4.4.4 Get reminder-rule details

The ruleId path parameter is required. A key can only read rules in its verified organization.

json

{
  "code": 0,
  "message": "success",
  "data": {
    "rule_id": "rule_01",
    "name": "Large invoice",
    "template_id": "tpl_01",
    "conditions": [
      {
        "field": "total_amount",
        "operator": "gt",
        "value": 10000,
        "logic": "AND"
      }
    ],
    "frequency": "on_extract_complete",
    "channels": [
      "in_app",
      "email"
    ],
    "recipients": {
      "members": [],
      "field_bindings": [],
      "webhook_ids": []
    },
    "title_template": "Invoice alert {file_name}",
    "content_template": "Total: {total_amount}",
    "status": "active"
  }
}

4.4.5 Enable or disable a reminder rule

json

{
  "status": "inactive"
}

json

{
  "code": 0,
  "message": "success",
  "data": {
    "rule_id": "rule_01",
    "status": "inactive"
  }
}

4.4.6 Delete a reminder rule

There is no body. Deletion is permanent. The PRD specifies HTTP 204 No Content; if the API Gateway wraps responses, follow the Python API response in the deployed environment.

4.5 Assets (23)

4.5.1 Get asset information

GET /api/v2/assets. Returns account type, expiry, and product balances. Extraction products include used, withholding, remaining, total, and limits.

json

{
  "code": 200,
  "message": "success",
  "data": {
    "accountType": "paid",
    "expireTime": null,
    "products": [
      {
        "productType": "extract",
        "productName": "Extraction",
        "unit": "page",
        "used": 20,
        "withholding": 5,
        "remaining": 975,
        "total": 1000,
        "progress": 2,
        "fileLimit": null,
        "singleFileSizeLimitMB": 100
      }
    ]
  }
}

5. Complete request parameter index

Every endpoint requires an API Key header as defined in Section 1. The table below lists the path, query, form, and JSON body fields for every Open API. “None” means that the endpoint accepts no business parameters beyond its path parameters and authentication header. Resource IDs in paths must be URL-encoded.

API	Location	Field	Required	Details
1 `POST /files/upload`	form	`file`	File or `url`	One or more files; either `file` or `url` must be supplied.
1 `POST /files/upload`	form	`url`	`url` or file	A source URL reachable by the server.
1 `POST /files/upload`	form	`mode`	Yes	`VisualExtract` or `LayoutExtract`.
1 `POST /files/upload`	form	`template_id`	No	An enabled template available to the organization; skips automatic classification when supplied.
1 `POST /files/upload`	form	`metadata`	No	A JSON object string for business-data pass-through; it does not affect authentication or assets.
1 `POST /files/upload`	form	`user_id`, `user_email`	No	`user_id` must belong to the organization and becomes the file owner; `user_email` is retained only as upload-source metadata.
2 `DELETE /files`	body	`file_ids`	At least one criterion	IDs of files to delete; combined with other deletion criteria as a union.
2 `DELETE /files`	body	`date_range.start`, `date_range.end`	No	ISO 8601 start and end times used to filter by upload time.
2 `DELETE /files`	body	`metadata_conditions`	No	A JSON object whose key-value pairs must all match exactly.
2 `DELETE /files`	body	`delete_permanently`	No	Boolean; `true` permanently deletes matched files.
3 `PUT /files/{fileId}/template`	path	`fileId`	Yes	ID of the file whose template is being changed.
3 `PUT /files/{fileId}/template`	body	`group_template_id`	Yes	Template-relation ID used by the browser template/group list.
4 `GET /batches/{batchId}/tasks`	path	`batchId`	Yes	Batch ID returned by upload.
4 `GET /batches/{batchId}/tasks`	query	`status`	No	`pending`, `processing`, `completed`, `failed`, or `cancelled`.
5 `POST /tasks/{taskId}/retry`	path	`taskId`	Yes	Task to restart; deleted or cancelled tasks cannot be restarted.
5 `POST /tasks/{taskId}/retry`	body/query	None	No	No business request body or query parameter.
6 `DELETE /tasks/{taskId}`	path	`taskId`	Yes	Only a pending or processing task can be cancelled.
6 `DELETE /tasks/{taskId}`	body/query	None	No	No business request body or query parameter.
7 `GET /templates`	query	`search`	No	Filters templates by name.
7 `GET /templates`	query	`status`	No	`active` or `inactive`.
8 `GET /templates/{templateId}/fields`	path	`templateId`	Yes	Template ID.
8 `GET /templates/{templateId}/fields`	body/query	None	No	No business request body or query parameter.
9 `POST /templates`	body	`name`, `fileId`, `page`	`name`, `fileId`	Template name, sample-file ID, and 1-based sample page; `page` defaults to `1`.
9 `POST /templates`	body	`keys`, `tableHeaders`	At least one	Scalar or table field definitions; see Section 3.
9 `POST /templates`	body	`elementOrder`	No	Mixed display order; entries contain `type` and `name`, with `columnOrder` for tables.
10 `PUT /templates/{templateId}`	path	`templateId`	Yes	ID of the template to update.
10 `PUT /templates/{templateId}`	body	`name`, `fileId`, `page`, `keys`, `tableHeaders`, `elementOrder`	No	Uses the creation field structure and preserves the current sample association.
11 `DELETE /templates/{templateId}`	path	`templateId`	Yes	ID of the template to soft-delete.
11 `DELETE /templates/{templateId}`	body/query	None	No	No business request body or query parameter.
12 `POST /templates/{templateId}/sample`	path	`templateId`	Yes	ID of the template whose sample is being replaced.
12 `POST /templates/{templateId}/sample`	form	`file`, `page`	`file`	Sample file and optional 1-based page; `page` defaults to `1`.
13 `POST /extract/{fileId}/fields`	path	`fileId`	Yes	File to augment with fields and re-extract.
13 `POST /extract/{fileId}/fields`	body	`keys`, `tableHeaders`	At least one	Scalar or table fields merged into the current template snapshot.
14 `GET /tasks/{taskId}`	path	`taskId`	Yes	Task whose status and result are requested.
14 `GET /tasks/{taskId}`	body/query	None	No	No business request body or query parameter.
15 `PUT /tasks/{taskId}`	path	`taskId`	Yes	Completed, unconfirmed task to update.
15 `PUT /tasks/{taskId}`	body	`fields`, `tables`	At least one	Scalar-field or table result data.
15 `PUT /tasks/{taskId}`	body	`confirm`	No	Defaults to `true`; use `false` to save without confirming.
16 `GET /classify/{taskId}/result`	path	`taskId`	Yes	Classification task ID.
16 `GET /classify/{taskId}/result`	body/query	None	No	No business request body or query parameter.
Rule 1 `POST /rules`	body	`name`, `template_id`, `conditions`, `frequency`, `channels`, `recipients`, `title_template`, `content_template`	Yes	Creates a reminder rule; success returns HTTP 201.
Rule 2 `PUT /rules/{ruleId}`	path/body	`ruleId`; submitted rule fields	`ruleId`	Updates submitted fields and returns the complete public rule DTO.
Rule 3 `GET /rules`	query	`status`	No	`active` or `inactive`; omit it to return all rules in the organization.
Rule 4 `GET /rules/{ruleId}`	path	`ruleId`	Yes	Returns rule details within the API Key organization.
Rule 5 `PATCH /rules/{ruleId}/status`	path/body	`ruleId`, `status`	Yes	`status` is `active` or `inactive`.
Rule 6 `DELETE /rules/{ruleId}`	path	`ruleId`	Yes	Permanently deletes the rule; success returns HTTP 204 with no body.
23 `GET /assets`	body/query	None	No	No business request body, path parameter, or query parameter.

6. Recommended workflow and error handling

Typical automation flow:

Call GET /api/v2/templates and retain the template id. To create a template, upload its sample first.
Upload one or more files with POST /api/v2/files/upload. Optionally supply an in-organization user_id; omitting it defaults ownership to the verified org_id. Retain batchId and taskIds.
Use the batch endpoint for multi-file progress or poll GET /api/v2/tasks/{taskId} for one file.
Read output when status=completed. When status=failed, inspect error, correct the cause, and retry if appropriate.
Use PUT /api/v2/tasks/{taskId} for manual edits. Send confirm:false to save without confirmation.

Code	Meaning/action
400	Invalid parameter, state, or template configuration; correct the request using `message`
401	Missing or invalid API key
403	A caller-supplied upload `user_id` does not belong to the API-key organization
404	Resource absent or not owned by the verified organization
409	Operation is invalid in the current state or an optimistic-lock conflict
415	Unsupported file extension

Do not rely on HTTP status alone. Java may currently return HTTP 200 while response-body code contains a business error.

A missing query/form parameter explicitly identifies the field:

json

{
  "code": 400,
  "message": "Required parameter 'mode' is missing",
  "data": {
    "mode": "required"
  }
}

A missing multipart file field uses the same structure, for example data.file="required".

ComPDF AI Open API Reference ​

1. Base URLs and authentication ​

2. Ownership and API count ​

2.1 Complete route index ​

2.2 PRD core API quick reference ​

3. Common conventions ​

3.1 Calling conventions and field names ​

3.2 Optional-parameter behavior ​

4. The 23 core Open APIs ​

4.1 File management (1–3) ​

4.1.1 Upload files ​

Metadata and user_email behavior ​

4.1.2 Delete files ​

4.1.3 Change a file template/category ​

4.2 Task management (4–6) ​

4.2.1 List batch tasks ​

4.2.2 Restart a task ​

4.2.3 Cancel a task ​

4.3 WorkFlow (7–16) ​

4.3.1 List templates ​

4.3.2 Get template fields ​

4.3.3 Create a template ​

4.3.4 Update a template ​

4.3.5 Delete a template ​

4.3.6 Upload or replace a template sample ​

4.3.7 Extract custom fields ​

4.3.8 Get a task/file result ​

4.3.9 Update a task/file result ​

4.3.10 Get classification result ​

4.4 Reminder rules (17–22, Python) ​

4.4.1 Create a reminder rule ​

4.4.2 Update a reminder rule ​

4.4.3 List reminder rules ​

4.4.4 Get reminder-rule details ​

4.4.5 Enable or disable a reminder rule ​

4.4.6 Delete a reminder rule ​

4.5 Assets (23) ​

4.5.1 Get asset information ​

5. Complete request parameter index ​

6. Recommended workflow and error handling ​

ComPDF AI Open API Reference

1. Base URLs and authentication

2. Ownership and API count

2.1 Complete route index

2.2 PRD core API quick reference

3. Common conventions

3.1 Calling conventions and field names

3.2 Optional-parameter behavior

4. The 23 core Open APIs

4.1 File management (1–3)

4.1.1 Upload files

Metadata and user_email behavior

4.1.2 Delete files

4.1.3 Change a file template/category

4.2 Task management (4–6)

4.2.1 List batch tasks

4.2.2 Restart a task

4.2.3 Cancel a task

4.3 WorkFlow (7–16)

4.3.1 List templates

4.3.2 Get template fields

4.3.3 Create a template

4.3.4 Update a template

4.3.5 Delete a template

4.3.6 Upload or replace a template sample

4.3.7 Extract custom fields

4.3.8 Get a task/file result

4.3.9 Update a task/file result

4.3.10 Get classification result

4.4 Reminder rules (17–22, Python)

4.4.1 Create a reminder rule

4.4.2 Update a reminder rule

4.4.3 List reminder rules

4.4.4 Get reminder-rule details

4.4.5 Enable or disable a reminder rule

4.4.6 Delete a reminder rule

4.5 Assets (23)

4.5.1 Get asset information

5. Complete request parameter index

6. Recommended workflow and error handling