Inference Endpoint

​

POST /inference

​

Description

​

Authentication

​

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 and One Password Integration 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.
• priority integer optional Queue priority for this task within its login‑queue. Lower number runs first; negatives allowed; omit (or send null) to run last.

  Value	Behaviour
  Negative (e.g. −5, −1)	Runs before all positive and null tasks
  0	Runs after negatives, before positives
  Positive (e.g. 1, 3)	Runs before null tasks
  null / omitted	Runs last (default — preserves FIFO ordering)

  Priority only reorders waiting tasks — a currently‑running task is never interrupted. Scope is per login‑queue and never affects other users or other portals.

​

Code Examples

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"]
  }'

curl -X POST https://api.optexity.com/api/v1/inference \
  -H "Content-Type: application/json" \
  -H "x-api-key: $OPTEXITY_API_KEY" \
  -d '{
    "endpoint_name": "order-scraper",
    "input_parameters": {
      "username": ["admin@company.com"],
      "date_range": ["last-30-days"]
    },
    "unique_parameter_names": ["username"],
    "priority": -1
  }'

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()}")

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);
}

​

Example with Secure Parameters

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)

{
    "success": true,
    "message": "Task has been allocated"
}

{
    "success": true,
    "message": "Task has been allocated. Check its status and output at https://dashboard.optexity.com/tasks",
    "task_id": "bf982ff9-f0af-4598-97be-2eb99c917eb0"
}

​

Error Responses

​

400 Bad Request

{
    "success": false,
    "message": "unique_parameter_names contains key 'username' not found in input_parameters"
}

• 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

{
    "success": false,
    "message": "Endpoint 'invalid-endpoint' not found"
}

• endpoint_name doesn’t match any configured automation
• Endpoint has been deleted or is not accessible

​

401 Unauthorized

{
    "success": false,
    "message": "Invalid or missing API key"
}

• Missing Authorization header
• Invalid API key format
• Expired or revoked API key

​

500 Internal Server Error

{
    "success": false,
    "message": "Control plane error: Network issue or invalid API key"
}

• 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 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

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

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

    # Queue priority (lower = higher urgency; None = last)
    priority: int | None

    # Deduplication
    dedup_key: str

    # Authentication
    api_key: str

​

Related

• Health Endpoints - Monitor task status
• Getting Started Guide - Server setup
• Automation Schema - Task definition