> This page is optimized for agents. Use the linked Markdown pages and llms.txt indexes for related API content.

# Classify Async

> Async classify endpoint.
>
> Persists a pollable job row, then runs the same classify CPU-worker pipeline
> without awaiting the result. Clients poll ``GET /job/{job_id}``.

- Product: Reducto API
- Section: Classify
- Snapshot: Current
- Method: `POST`
- Path: `/classify_async`

## Request body

Required: yes  
Content types: `application/json`  

### `model`

Type: `string`  
Required: no  
Allowed values: `default`, `accurate`  
Default: `default`  

The classification model to use. Set to "accurate" to run Deep Classify for higher accuracy on hard documents. Defaults to "default".

### `priority`

Type: `boolean`  
Required: no  
Default: `true`  

Workers poll the priority queue ahead of the standard queue, so priority jobs start sooner when there is queued work; sync jobs are prioritized above async jobs by default.

### `async`

Type: `config__v3__AsyncConfig`  
Required: no  

The configuration options for asynchronous processing. Used by /classify_async.

#### `metadata`

Type: `unknown`  
Required: no  

JSON metadata included in webhook request body. Defaults to None.

#### `priority`

Type: `boolean`  
Required: no  
Default: `false`  

Workers poll the priority queue ahead of the standard queue, so priority jobs start sooner when there is queued work; sync jobs are prioritized above async jobs by default.

#### `webhook`

Type: `SvixWebhookConfig | DirectWebhookConfig`  
Required: no  

The webhook configuration for the asynchronous processing.

##### SvixWebhookConfig

Type: `SvixWebhookConfig`  

###### `mode`

Type: `string`  
Required: no  
Default: `svix`  

###### `channels`

Type: `string[]`  
Required: no  

A list of Svix channels the message will be delivered down, omit to send to all channels.

###### string

Type: `string`  

##### DirectWebhookConfig

Type: `DirectWebhookConfig`  

###### `mode`

Type: `string`  
Required: no  
Default: `direct`  

###### `url`

Type: `string`  
Required: yes  

##### unknown

Type: `unknown`  

### `force_url_result`

Type: `boolean`  
Required: no  
Default: `false`  

Force the endpoint result to be returned in URL form.

### `input`

Type: `string | string[] | UploadResponse`  
Required: yes  

The URL of the document to be classified. You can provide one of the following:
1. A publicly available URL
2. A presigned S3 URL
3. A reducto:// prefixed URL obtained from the /upload endpoint after directly uploading a document

#### string

Type: `string`  

#### string[]

Type: `string[]`  

##### string

Type: `string`  

#### UploadResponse

Type: `UploadResponse`  

##### `file_id`

Type: `string`  
Required: yes  

##### `presigned_url`

Type: `string`  
Required: no  

###### string

Type: `string`  

###### unknown

Type: `unknown`  

### `classification_schema`

Type: `ClassificationCategory[]`  
Required: no  

A list of classification categories and their matching criteria.

#### ClassificationCategory

Type: `ClassificationCategory`  

A single classification category with its matching criteria.

##### `category`

Type: `string`  
Required: yes  

The category name/label that documents will be classified into (e.g., 'invoice', 'contract', 'receipt').

##### `criteria`

Type: `string[]`  
Required: yes  

A list of criteria, keywords, or descriptions that define what characteristics a document must have to be classified into this category (e.g., ['contains billing information', 'has itemized charges']).

###### string

Type: `string`  

### `category_groups`

Type: `object`  
Required: no  

A mapping of higher-level classify groups to the category labels that belong to each group. When provided, the response includes `extra_metadata.grouping` with the matched group name, or `ungrouped` if the selected category is not in any group.

### `page_range`

Type: `PageRange | PageRange[] | number[]`  
Required: no  

The page range to process (1-indexed). By default, the first 5 pages are used. At most 10 pages can be selected. Only applies to PDFs; ignored for other document types.

#### PageRange

Type: `PageRange`  

##### `start`

Type: `number`  
Required: no  

The page number to start processing from (1-indexed).

###### number

Type: `number`  

###### unknown

Type: `unknown`  

##### `end`

Type: `number`  
Required: no  

The page number to stop processing at (1-indexed).

###### number

Type: `number`  

###### unknown

Type: `unknown`  

#### PageRange[]

Type: `PageRange[]`  

##### PageRange

Type: `PageRange`  

###### `start`

Type: `number`  
Required: no  

The page number to start processing from (1-indexed).

###### number

Type: `number`  

###### unknown

Type: `unknown`  

###### `end`

Type: `number`  
Required: no  

The page number to stop processing at (1-indexed).

###### number

Type: `number`  

###### unknown

Type: `unknown`  

#### number[]

Type: `number[]`  

##### number

Type: `number`  

#### unknown

Type: `unknown`  

### `document_metadata`

Type: `string`  
Required: no  

Optional document-level metadata to include in classification prompts.

#### string

Type: `string`  

#### unknown

Type: `unknown`  

## Execute with cURL

```bash
curl -X POST "https://platform.reducto.ai/classify_async" \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"<value>"}'
```

## Responses

### Response `200`

Category: success  

Successful Response

#### `application/json`

##### Generated example

```json
{
  "job_id": "job_id"
}
```

##### Schema

###### AsyncClassifyResponse

Type: `AsyncClassifyResponse`  

###### `job_id`

Type: `string`  
Required: yes  

### Response `422`

Category: client-error  

Validation Error

#### `application/json`

##### Generated example

```json
{
  "detail": [
    {
      "loc": [
        "loc"
      ],
      "msg": "msg",
      "type": "type",
      "ctx": {}
    }
  ]
}
```

##### Schema

###### HTTPValidationError

Type: `HTTPValidationError`  

###### `detail`

Type: `ValidationError[]`  
Required: no  

###### ValidationError

Type: `ValidationError`  

###### `loc`

Type: `string | number[]`  
Required: yes  

###### string | number

Type: `string | number`  

###### string

Type: `string`  

###### number

Type: `number`  

###### `msg`

Type: `string`  
Required: yes  

###### `type`

Type: `string`  
Required: yes  

###### `input`

Type: `unknown`  
Required: no  

###### `ctx`

Type: `object`  
Required: no  

## Related representations

- [Human documentation](/api-reference/api/sections/classify/operations/classify-async/)
- [cURL Markdown](https://docs.reducto.ai/api-reference/api/curl/sections/classify/operations/classify-async.md)
