> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optexity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inference Endpoint

> Submit automation tasks to the inference server

## POST /inference

Submits automation tasks to an Optexity inference server for asynchronous execution.

## Description

The inference endpoint is the primary way to submit automation tasks to an Optexity inference server. Tasks are enqueued and executed asynchronously in the background. The endpoint supports both local development and cloud production deployments.

## Authentication

<Info>
  Local endpoint (`http://localhost:9000/inference`) does not require authentication and is free
  to use for development and testing.
</Info>

<Info>
  Cloud endpoint (`https://inference-api.optexity.com/api/v1/inference`) requires authentication with an API
  key in the request header. API keys can be found in the Optexity dashboard under the "API Keys"
  section. This requires a paid plan. Contact us at [founders@optexity.com](mailto:founders@optexity.com) to get a paid plan.
</Info>

## Parameters

### Headers

* **`Content-Type`** `string` *required*

  Must be set to `application/json`

* **`Authorization`** `string` *required* (cloud endpoint only)

  API key for authentication. Format: `x-api-key YOUR_OPTEXITY_API_KEY`

  Not required for local endpoint

### Body Parameters

* **`endpoint_name`** `string` *required*

  Name of the automation endpoint to execute. Must match a recording/automation configured in the Optexity control plane.

* **`input_parameters`** `dict[str, list[str]]` *required*

  Input values for the automation. Keys are parameter names, values are lists of strings. Every parameter defined in the automation's `input_parameters` should be provided here.

  If a parameter is given an empty list and it is used in an `input text` action, the action will be skipped.

* **`secure_parameters`** `dict[str, list[SecureParameter]]` *optional*

  Secure parameters for the automation. Keys are parameter names, values are lists of secure parameters. Every parameter defined in the automation's `secure_parameters` should be provided here.

  These are used to securely store sensitive information like passwords, API keys, and other secrets. Please refer to the [Secure Parameters API Reference](/api-reference/schema-reference/secure-parameters) and [One Password Integration](/docs/advanced/onepassword) documentation for more information.

* **`unique_parameter_names`** `list[str]` *optional*

  Subset of keys from `input_parameters` that uniquely identify this task. Used for deduplication.

  Every name in this list must exist as a key in `input_parameters`.

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:9000/inference \
    -H "Content-Type: application/json" \
    -d '{
      "endpoint_name": "order-scraper",
      "input_parameters": {
        "username": ["admin@company.com"],
        "password": ["secretpassword"],
        "date_range": ["last-30-days"]
      },
      "unique_parameter_names": ["username", "date_range"]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "http://localhost:9000/inference",
      headers={"Content-Type": "application/json"},
      json={
          "endpoint_name": "login-flow",
          "input_parameters": {
              "email": ["user@example.com"],
              "password": ["secret123"],
          },
          "unique_parameter_names": ["email"],
      },
  )

  if response.status_code == 202:
      print("Task submitted successfully")
  else:
      print(f"Error: {response.json()}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("http://localhost:9000/inference", {
      method: "POST",
      headers: {
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          endpoint_name: "login-flow",
          input_parameters: {
              email: ["user@example.com"],
              password: ["secret123"],
          },
          unique_parameter_names: ["email"],
      }),
  });

  const data = await response.json();
  if (response.status === 202) {
      console.log("Task submitted successfully");
  } else {
      console.error("Error:", data);
  }
  ```
</CodeGroup>

### Example with Secure Parameters

```bash theme={null}
curl -X POST http://localhost:9000/inference \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_name": "login-flow",
    "input_parameters": {
      "content": ["This is the content of the page"]
    },
    "secure_parameters": {
      "username": [
        {
          "onepassword": {
            "vault_name": "optexity_automation",
            "item_name": "fedex",
            "field_name": "username"
          }
        }
      ],
      "password": [
        {
          "onepassword": {
            "vault_name": "optexity_automation",
            "item_name": "fedex",
            "field_name": "password"
          }
        }
      ]
    },
    "unique_parameter_names": ["username"]
  }'
```

## Response

### Success Response (202 Accepted)

The task has been enqueued and will execute asynchronously.

```json theme={null}
{
    "success": true,
    "message": "Task has been allocated"
}
```

**Response Fields:**

| Field     | Type    | Description                                  |
| --------- | ------- | -------------------------------------------- |
| `success` | boolean | Indicates whether the request was successful |
| `message` | string  | Status message describing the result         |

## Error Responses

### 400 Bad Request

Returned when request parameters are invalid.

```json theme={null}
{
    "success": false,
    "message": "unique_parameter_names contains key 'username' not found in input_parameters"
}
```

**Common causes:**

* `unique_parameter_names` contains a key that doesn't exist in `input_parameters`
* Parameter values are not lists of strings
* Missing required `endpoint_name` or `input_parameters` fields

### 404 Not Found

Returned when the specified endpoint does not exist.

```json theme={null}
{
    "success": false,
    "message": "Endpoint 'invalid-endpoint' not found"
}
```

**Common causes:**

* `endpoint_name` doesn't match any configured automation
* Endpoint has been deleted or is not accessible

### 401 Unauthorized

Returned when authentication fails (cloud endpoint only).

```json theme={null}
{
    "success": false,
    "message": "Invalid or missing API key"
}
```

**Common causes:**

* Missing `Authorization` header
* Invalid API key format
* Expired or revoked API key

### 500 Internal Server Error

Returned when an unexpected server error occurs.

```json theme={null}
{
    "success": false,
    "message": "Control plane error: Network issue or invalid API key"
}
```

**Common causes:**

* Network connectivity issues with the control plane
* Control plane service unavailable
* Internal server configuration errors

## How It Works

1. The inference server receives the `InferenceRequest`
2. It forwards the request to the Optexity control plane at `inference-api.optexity.com`
3. The control plane returns a serialized `Task` object containing the full workflow
4. The task is enqueued locally for background execution
5. A `202 Accepted` response is returned immediately
6. The browser automation executes asynchronously

## Validation

The endpoint validates:

1. All `unique_parameter_names` exist in `input_parameters`
2. All parameter values are lists of strings
3. The `endpoint_name` matches a valid automation

## Configuration

The endpoint uses these settings from environment variables:

| Setting              | Default            | Description                              |
| -------------------- | ------------------ | ---------------------------------------- |
| `OPTEXITY_API_KEY`   | Required           | API key for control plane authentication |
| `INFERENCE_ENDPOINT` | `api/v1/inference` | Control plane endpoint path              |

<AccordionGroup>
  <Accordion title="Task Object Structure">
    The control plane returns a `Task` object with this structure:

    ```python theme={null}
    class Task:
        task_id: str                          # Unique identifier
        user_id: str                          # Owner of the task
        recording_id: str                     # Source automation ID
        automation: Automation                # Full workflow
        input_parameters: dict[str, list[str]]
        unique_parameter_names: list[str]
        unique_parameters: dict[str, list[str]] | None

        # Lifecycle
        created_at: datetime
        allocated_at: datetime | None
        started_at: datetime | None
        completed_at: datetime | None
        status: "queued" | "allocated" | "running" | "success" | "failed" | "cancelled"
        error: str | None

        # Retry configuration
        retry_count: int = 0
        max_retries: int = 1

        # Storage paths
        save_directory: Path
        task_directory: Path | None
        logs_directory: Path | None
        downloads_directory: Path | None
        log_file_path: Path | None

        # Deduplication
        dedup_key: str

        # Authentication
        api_key: str
    ```
  </Accordion>
</AccordionGroup>

## Related

* [Health Endpoints](/api-reference/health-endpoints) - Monitor task status
* [Getting Started Guide](/docs/getting-started) - Server setup
* [Automation Schema](/api-reference/automation-schema) - Task definition