# Classify ## Create Classify Job **post** `/api/v2/classify` Create a classify job. Classifies a document against a set of rules. Set `file_input` to a file ID (`dfl-...`) or parse job ID (`pjb-...`), and provide either inline `configuration` with rules or a `configuration_id` referencing a saved preset. Each rule has a `type` (the label to assign) and a `description` (natural language criteria). The classifier returns the best matching rule with a confidence score. The job runs asynchronously. Poll `GET /classify/{job_id}` to check status and retrieve results. ### Query Parameters - `organization_id: optional string` - `project_id: optional string` ### Cookie Parameters - `session: optional string` ### Body Parameters - `configuration: optional ClassifyConfiguration` Configuration for a classify job. - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. - `configuration_id: optional string` Saved configuration ID - `file_id: optional string` Deprecated: use file_input instead - `file_input: optional string` File ID or parse job ID to classify - `parse_job_id: optional string` Deprecated: use file_input instead - `transaction_id: optional string` Idempotency key scoped to the project. Reusing a key returns the original job; the new request body is ignored. - `webhook_configurations: optional array of object { webhook_events, webhook_headers, webhook_output_format, 2 more }` Outbound webhook endpoints to notify on job status changes - `webhook_events: optional array of "classify.cancelled" or "classify.error" or "classify.partial_success" or 25 more` Events to subscribe to (e.g. 'parse.success', 'extract.error'). If null, all events are delivered. - `"classify.cancelled"` - `"classify.error"` - `"classify.partial_success"` - `"classify.pending"` - `"classify.running"` - `"classify.success"` - `"extract.cancelled"` - `"extract.error"` - `"extract.partial_success"` - `"extract.pending"` - `"extract.success"` - `"parse.cancelled"` - `"parse.error"` - `"parse.partial_success"` - `"parse.pending"` - `"parse.running"` - `"parse.success"` - `"sheets.cancelled"` - `"sheets.error"` - `"sheets.partial_success"` - `"sheets.pending"` - `"sheets.success"` - `"split.cancelled"` - `"split.error"` - `"split.pending"` - `"split.processing"` - `"split.success"` - `"unmapped_event"` - `webhook_headers: optional map[string]` Custom HTTP headers sent with each webhook request (e.g. auth tokens) - `webhook_output_format: optional string` Response format sent to the webhook: 'string' (default) or 'json' - `webhook_signing_secret: optional string` Shared signing secret used to sign webhook deliveries. When set, each request includes an HMAC-SHA256 signature of the request body in the 'LC-Signature' header (value 'sha256='). Recompute the HMAC over the raw request body with this secret to verify the delivery is authentic. - `webhook_url: optional string` URL to receive webhook POST notifications ### Returns - `id: string` Unique identifier - `configuration: ClassifyConfiguration` Classify configuration used for this job - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job (FILE or PARSE_JOB) - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` ID of the input file or parse job - `project_id: string` Project this job belongs to - `status: "COMPLETED" or "FAILED" or "PENDING" or "RUNNING"` Current job status: PENDING, RUNNING, COMPLETED, or FAILED - `"COMPLETED"` - `"FAILED"` - `"PENDING"` - `"RUNNING"` - `user_id: string` User who created this job - `configuration_id: optional string` Product configuration ID - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if job failed - `parse_job_id: optional string` Associated parse job ID - `result: optional ClassifyResult` Result of classifying a document. - `confidence: number` Confidence score between 0.0 and 1.0 - `reasoning: string` Why the document matched (or didn't match) the returned rule - `type: string` Matched rule type, or null if no rule matched - `transaction_id: optional string` Idempotency key - `updated_at: optional string` Update datetime ### Example ```http curl https://api.cloud.llamaindex.ai/api/v2/classify \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "id", "configuration": { "rules": [ { "description": "contains invoice number, line items, and total amount", "type": "invoice" } ], "mode": "FAST", "parsing_configuration": { "lang": "en", "max_pages": 10, "target_pages": "1,3,5-7" } }, "document_input_type": "file_id", "file_input": "file_input", "project_id": "project_id", "status": "COMPLETED", "user_id": "user_id", "configuration_id": "configuration_id", "created_at": "2019-12-27T18:11:19.117Z", "error_message": "error_message", "parse_job_id": "parse_job_id", "result": { "confidence": 0, "reasoning": "reasoning", "type": "type" }, "transaction_id": "transaction_id", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## List Classify Jobs **get** `/api/v2/classify` List classify jobs with optional filtering and pagination. Filter by `status`, `configuration_id`, specific `job_ids`, or creation date range. ### Query Parameters - `configuration_id: optional string` Filter by configuration ID - `created_at_on_or_after: optional string` Include items created at or after this timestamp (inclusive) - `created_at_on_or_before: optional string` Include items created at or before this timestamp (inclusive) - `job_ids: optional array of string` Filter by specific job IDs - `organization_id: optional string` - `page_size: optional number` Number of items per page - `page_token: optional string` Token for pagination - `project_id: optional string` - `status: optional "COMPLETED" or "FAILED" or "PENDING" or "RUNNING"` Filter by job status - `"COMPLETED"` - `"FAILED"` - `"PENDING"` - `"RUNNING"` ### Cookie Parameters - `session: optional string` ### Returns - `items: array of object { id, configuration, document_input_type, 11 more }` The list of items. - `id: string` Unique identifier - `configuration: ClassifyConfiguration` Classify configuration used for this job - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job (FILE or PARSE_JOB) - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` ID of the input file or parse job - `project_id: string` Project this job belongs to - `status: "COMPLETED" or "FAILED" or "PENDING" or "RUNNING"` Current job status: PENDING, RUNNING, COMPLETED, or FAILED - `"COMPLETED"` - `"FAILED"` - `"PENDING"` - `"RUNNING"` - `user_id: string` User who created this job - `configuration_id: optional string` Product configuration ID - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if job failed - `parse_job_id: optional string` Associated parse job ID - `result: optional ClassifyResult` Result of classifying a document. - `confidence: number` Confidence score between 0.0 and 1.0 - `reasoning: string` Why the document matched (or didn't match) the returned rule - `type: string` Matched rule type, or null if no rule matched - `transaction_id: optional string` Idempotency key - `updated_at: optional string` Update datetime - `next_page_token: optional string` A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages. - `total_size: optional number` The total number of items available. This is only populated when specifically requested. The value may be an estimate and can be used for display purposes only. ### Example ```http curl https://api.cloud.llamaindex.ai/api/v2/classify \ -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" ``` #### Response ```json { "items": [ { "id": "id", "configuration": { "rules": [ { "description": "contains invoice number, line items, and total amount", "type": "invoice" } ], "mode": "FAST", "parsing_configuration": { "lang": "en", "max_pages": 10, "target_pages": "1,3,5-7" } }, "document_input_type": "file_id", "file_input": "file_input", "project_id": "project_id", "status": "COMPLETED", "user_id": "user_id", "configuration_id": "configuration_id", "created_at": "2019-12-27T18:11:19.117Z", "error_message": "error_message", "parse_job_id": "parse_job_id", "result": { "confidence": 0, "reasoning": "reasoning", "type": "type" }, "transaction_id": "transaction_id", "updated_at": "2019-12-27T18:11:19.117Z" } ], "next_page_token": "next_page_token", "total_size": 0 } ``` ## Get Classify Job **get** `/api/v2/classify/{job_id}` Get a classify job by ID. Returns the job status, configuration, and classify result when complete. The result includes the matched document type, confidence score, and reasoning. ### Path Parameters - `job_id: string` ### Query Parameters - `organization_id: optional string` - `project_id: optional string` ### Cookie Parameters - `session: optional string` ### Returns - `id: string` Unique identifier - `configuration: ClassifyConfiguration` Classify configuration used for this job - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job (FILE or PARSE_JOB) - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` ID of the input file or parse job - `project_id: string` Project this job belongs to - `status: "COMPLETED" or "FAILED" or "PENDING" or "RUNNING"` Current job status: PENDING, RUNNING, COMPLETED, or FAILED - `"COMPLETED"` - `"FAILED"` - `"PENDING"` - `"RUNNING"` - `user_id: string` User who created this job - `configuration_id: optional string` Product configuration ID - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if job failed - `parse_job_id: optional string` Associated parse job ID - `result: optional ClassifyResult` Result of classifying a document. - `confidence: number` Confidence score between 0.0 and 1.0 - `reasoning: string` Why the document matched (or didn't match) the returned rule - `type: string` Matched rule type, or null if no rule matched - `transaction_id: optional string` Idempotency key - `updated_at: optional string` Update datetime ### Example ```http curl https://api.cloud.llamaindex.ai/api/v2/classify/$JOB_ID \ -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" ``` #### Response ```json { "id": "id", "configuration": { "rules": [ { "description": "contains invoice number, line items, and total amount", "type": "invoice" } ], "mode": "FAST", "parsing_configuration": { "lang": "en", "max_pages": 10, "target_pages": "1,3,5-7" } }, "document_input_type": "file_id", "file_input": "file_input", "project_id": "project_id", "status": "COMPLETED", "user_id": "user_id", "configuration_id": "configuration_id", "created_at": "2019-12-27T18:11:19.117Z", "error_message": "error_message", "parse_job_id": "parse_job_id", "result": { "confidence": 0, "reasoning": "reasoning", "type": "type" }, "transaction_id": "transaction_id", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## Domain Types ### Classify Configuration - `ClassifyConfiguration object { rules, mode, parsing_configuration }` Configuration for a classify job. - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. ### Classify Create Request - `ClassifyCreateRequest object { configuration, configuration_id, file_id, 4 more }` Request to create a classify job. - `configuration: optional ClassifyConfiguration` Configuration for a classify job. - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. - `configuration_id: optional string` Saved configuration ID - `file_id: optional string` Deprecated: use file_input instead - `file_input: optional string` File ID or parse job ID to classify - `parse_job_id: optional string` Deprecated: use file_input instead - `transaction_id: optional string` Idempotency key scoped to the project. Reusing a key returns the original job; the new request body is ignored. - `webhook_configurations: optional array of object { webhook_events, webhook_headers, webhook_output_format, 2 more }` Outbound webhook endpoints to notify on job status changes - `webhook_events: optional array of "classify.cancelled" or "classify.error" or "classify.partial_success" or 25 more` Events to subscribe to (e.g. 'parse.success', 'extract.error'). If null, all events are delivered. - `"classify.cancelled"` - `"classify.error"` - `"classify.partial_success"` - `"classify.pending"` - `"classify.running"` - `"classify.success"` - `"extract.cancelled"` - `"extract.error"` - `"extract.partial_success"` - `"extract.pending"` - `"extract.success"` - `"parse.cancelled"` - `"parse.error"` - `"parse.partial_success"` - `"parse.pending"` - `"parse.running"` - `"parse.success"` - `"sheets.cancelled"` - `"sheets.error"` - `"sheets.partial_success"` - `"sheets.pending"` - `"sheets.success"` - `"split.cancelled"` - `"split.error"` - `"split.pending"` - `"split.processing"` - `"split.success"` - `"unmapped_event"` - `webhook_headers: optional map[string]` Custom HTTP headers sent with each webhook request (e.g. auth tokens) - `webhook_output_format: optional string` Response format sent to the webhook: 'string' (default) or 'json' - `webhook_signing_secret: optional string` Shared signing secret used to sign webhook deliveries. When set, each request includes an HMAC-SHA256 signature of the request body in the 'LC-Signature' header (value 'sha256='). Recompute the HMAC over the raw request body with this secret to verify the delivery is authentic. - `webhook_url: optional string` URL to receive webhook POST notifications ### Classify Result - `ClassifyResult object { confidence, reasoning, type }` Result of classifying a document. - `confidence: number` Confidence score between 0.0 and 1.0 - `reasoning: string` Why the document matched (or didn't match) the returned rule - `type: string` Matched rule type, or null if no rule matched ### Classify Create Response - `ClassifyCreateResponse object { id, configuration, document_input_type, 11 more }` Response for a classify job. - `id: string` Unique identifier - `configuration: ClassifyConfiguration` Classify configuration used for this job - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job (FILE or PARSE_JOB) - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` ID of the input file or parse job - `project_id: string` Project this job belongs to - `status: "COMPLETED" or "FAILED" or "PENDING" or "RUNNING"` Current job status: PENDING, RUNNING, COMPLETED, or FAILED - `"COMPLETED"` - `"FAILED"` - `"PENDING"` - `"RUNNING"` - `user_id: string` User who created this job - `configuration_id: optional string` Product configuration ID - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if job failed - `parse_job_id: optional string` Associated parse job ID - `result: optional ClassifyResult` Result of classifying a document. - `confidence: number` Confidence score between 0.0 and 1.0 - `reasoning: string` Why the document matched (or didn't match) the returned rule - `type: string` Matched rule type, or null if no rule matched - `transaction_id: optional string` Idempotency key - `updated_at: optional string` Update datetime ### Classify List Response - `ClassifyListResponse object { id, configuration, document_input_type, 11 more }` Response for a classify job. - `id: string` Unique identifier - `configuration: ClassifyConfiguration` Classify configuration used for this job - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job (FILE or PARSE_JOB) - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` ID of the input file or parse job - `project_id: string` Project this job belongs to - `status: "COMPLETED" or "FAILED" or "PENDING" or "RUNNING"` Current job status: PENDING, RUNNING, COMPLETED, or FAILED - `"COMPLETED"` - `"FAILED"` - `"PENDING"` - `"RUNNING"` - `user_id: string` User who created this job - `configuration_id: optional string` Product configuration ID - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if job failed - `parse_job_id: optional string` Associated parse job ID - `result: optional ClassifyResult` Result of classifying a document. - `confidence: number` Confidence score between 0.0 and 1.0 - `reasoning: string` Why the document matched (or didn't match) the returned rule - `type: string` Matched rule type, or null if no rule matched - `transaction_id: optional string` Idempotency key - `updated_at: optional string` Update datetime ### Classify Get Response - `ClassifyGetResponse object { id, configuration, document_input_type, 11 more }` Response for a classify job. - `id: string` Unique identifier - `configuration: ClassifyConfiguration` Classify configuration used for this job - `rules: array of object { description, type }` Classify rules to evaluate against the document (at least one required) - `description: string` Natural language criteria for matching this rule - `type: string` Document type to assign when rule matches - `mode: optional "FAST"` Classify execution mode - `"FAST"` - `parsing_configuration: optional object { lang, max_pages, target_pages }` Parsing configuration for classify jobs. - `lang: optional string` ISO 639-1 language code for the document - `max_pages: optional number` Maximum number of pages to process. Omit for no limit. - `target_pages: optional string` Comma-separated page numbers or ranges to process (1-based). Omit to process all pages. - `document_input_type: "file_id" or "parse_job_id" or "url"` Whether the input was a file or parse job (FILE or PARSE_JOB) - `"file_id"` - `"parse_job_id"` - `"url"` - `file_input: string` ID of the input file or parse job - `project_id: string` Project this job belongs to - `status: "COMPLETED" or "FAILED" or "PENDING" or "RUNNING"` Current job status: PENDING, RUNNING, COMPLETED, or FAILED - `"COMPLETED"` - `"FAILED"` - `"PENDING"` - `"RUNNING"` - `user_id: string` User who created this job - `configuration_id: optional string` Product configuration ID - `created_at: optional string` Creation datetime - `error_message: optional string` Error message if job failed - `parse_job_id: optional string` Associated parse job ID - `result: optional ClassifyResult` Result of classifying a document. - `confidence: number` Confidence score between 0.0 and 1.0 - `reasoning: string` Why the document matched (or didn't match) the returned rule - `type: string` Matched rule type, or null if no rule matched - `transaction_id: optional string` Idempotency key - `updated_at: optional string` Update datetime