**API versions** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=en)

# Durable report tasks

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

## Operations

## POST /ai-tasks/report-export

Start a durable private report export

`start_report_export_task`

Opt-in durable report-export task pilot. Disabled installations return 503 MCP_TASKS_DISABLED without calling the task engine or report source. Organisation API-key ownership is private to the exact authenticated key; root, system and campaign-restricted credentials are refused. Current credentials, organisation and all source grants are revalidated before every disclosure or command. Requires statistics:read plus source dataset/relation scopes: contacts/interactions=contacts:read, paiements=paiements:read, abonnements=abonnements:read, promesses=promesses:read, forms_submit=forms:read AND forms_submit:read, cerfas=receipts:read. forms_submit also requires a current same-organisation non-deleted form UUID. Use the authorised Explorer catalogue. The existing ReportExportRequest is reused unchanged: one requested page of at most 200 rows or a bounded aggregate of at most 30 groups, never a full dataset or transaction snapshot. Original raw units, currencies, format limits and PDF glyph restrictions still apply. No financial mutation, email or public share is created. The pilot expires at the source deadline, at most 600 seconds after creation; the general ceiling of 7 days after completion does not extend this shorter lifetime. Reads, retries and reconnects never renew expiry. No additional Unisoft confirmation step; the AI harness controls its own write approvals.

Requires reports:write in addition to statistics:read. Submit the exact ReportExportCreate body with idempotencyKey and request. A durable worker executes the existing one-shot export. Repeating the same key and exact request returns the same task and may return any current state; conflicting inputs return 409. Keep this key after an uncertain response and inspect the same task. Never create a replacement merely because a worker or response is delayed. A retained RUNNING source lock is never stolen or automatically executed again.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "statistics:read",
  "additional": [
    "reports:write"
  ]
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{8,100}$"
          },
          "request": {
            "type": "object",
            "properties": {
              "format": {
                "type": "string",
                "enum": [
                  "json",
                  "csv",
                  "xlsx",
                  "pdf"
                ]
              },
              "kind": {
                "type": "string",
                "enum": [
                  "rows",
                  "aggregate"
                ]
              },
              "report": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/UnisoftRequest_729f4d152ef616c77bcd"
                  },
                  {
                    "$ref": "#/components/schemas/UnisoftRequest_411efe4dbeaae4a40e62"
                  }
                ]
              }
            },
            "required": [
              "format",
              "kind",
              "report"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "idempotencyKey",
          "request"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 201

```json
{
  "description": "Private durable task status and optional frozen artifact metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown request parameter.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Current principal or required scopes refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Private task or authorised source unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Idempotency conflict, retained execution lock or artifact not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 410

```json
{
  "description": "Task or source expired; no renewal is performed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source fields, format, file integrity or output limit refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 429

```json
{
  "description": "Current private task quota reached; inspect existing tasks before starting another export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Task pilot disabled, storage unavailable or command acknowledgement uncertain; inspect the same task before reconciling.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "statistics:read",
  "x-unisoft-additional-scopes": [
    "reports:write"
  ],
  "x-unisoft-conditional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms:read",
    "forms_submit:read",
    "receipts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "write",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /ai-tasks/{taskId}

Read a durable private task

`get_unisoft_task`

Opt-in durable report-export task pilot. Disabled installations return 503 MCP_TASKS_DISABLED without calling the task engine or report source. Organisation API-key ownership is private to the exact authenticated key; root, system and campaign-restricted credentials are refused. Current credentials, organisation and all source grants are revalidated before every disclosure or command. Requires statistics:read plus source dataset/relation scopes: contacts/interactions=contacts:read, paiements=paiements:read, abonnements=abonnements:read, promesses=promesses:read, forms_submit=forms:read AND forms_submit:read, cerfas=receipts:read. forms_submit also requires a current same-organisation non-deleted form UUID. Use the authorised Explorer catalogue. The existing ReportExportRequest is reused unchanged: one requested page of at most 200 rows or a bounded aggregate of at most 30 groups, never a full dataset or transaction snapshot. Original raw units, currencies, format limits and PDF glyph restrictions still apply. No financial mutation, email or public share is created. The pilot expires at the source deadline, at most 600 seconds after creation; the general ceiling of 7 days after completion does not extend this shorter lifetime. Reads, retries and reconnects never renew expiry. No additional Unisoft confirmation step; the AI harness controls its own write approvals.

Passive status read. Never runs a report, renders a file, retries execution, renews expiry or cleans storage. COMPLETED exposes only frozen artifact metadata; FAILED carries a stable code. The artifact is available only while current source rights and the original deadline remain valid. Another key or organisation is indistinguishable from an unknown task.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "statistics:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "taskId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Private task UUID returned by start_report_export_task."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Private durable task status and optional frozen artifact metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown request parameter.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Current principal or required scopes refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Private task or authorised source unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Idempotency conflict, retained execution lock or artifact not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 410

```json
{
  "description": "Task or source expired; no renewal is performed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source fields, format, file integrity or output limit refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 429

```json
{
  "description": "Current private task quota reached; inspect existing tasks before starting another export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Task pilot disabled, storage unavailable or command acknowledgement uncertain; inspect the same task before reconciling.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "statistics:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-conditional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms:read",
    "forms_submit:read",
    "receipts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /ai-tasks/{taskId}/cancel

Request cancellation of a durable private task

`cancel_unisoft_task`

Opt-in durable report-export task pilot. Disabled installations return 503 MCP_TASKS_DISABLED without calling the task engine or report source. Organisation API-key ownership is private to the exact authenticated key; root, system and campaign-restricted credentials are refused. Current credentials, organisation and all source grants are revalidated before every disclosure or command. Requires statistics:read plus source dataset/relation scopes: contacts/interactions=contacts:read, paiements=paiements:read, abonnements=abonnements:read, promesses=promesses:read, forms_submit=forms:read AND forms_submit:read, cerfas=receipts:read. forms_submit also requires a current same-organisation non-deleted form UUID. Use the authorised Explorer catalogue. The existing ReportExportRequest is reused unchanged: one requested page of at most 200 rows or a bounded aggregate of at most 30 groups, never a full dataset or transaction snapshot. Original raw units, currencies, format limits and PDF glyph restrictions still apply. No financial mutation, email or public share is created. The pilot expires at the source deadline, at most 600 seconds after creation; the general ceiling of 7 days after completion does not extend this shorter lifetime. Reads, retries and reconnects never renew expiry. No additional Unisoft confirmation step; the AI harness controls its own write approvals.

Requires reports:write in addition to statistics:read and an empty JSON object. Repetition is idempotent. Cancellation can stop queued work; a running task only records a request and cannot undo work already admitted. Inspect the resulting state rather than assuming cancellation succeeded. Terminal results stay terminal.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "statistics:read",
  "additional": [
    "reports:write"
  ]
}
```

### Parameters

```json
{
  "name": "taskId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Private task UUID returned by start_report_export_task."
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Private durable task status and optional frozen artifact metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown request parameter.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Current principal or required scopes refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Private task or authorised source unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Idempotency conflict, retained execution lock or artifact not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 410

```json
{
  "description": "Task or source expired; no renewal is performed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source fields, format, file integrity or output limit refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 429

```json
{
  "description": "Current private task quota reached; inspect existing tasks before starting another export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Task pilot disabled, storage unavailable or command acknowledgement uncertain; inspect the same task before reconciling.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "statistics:read",
  "x-unisoft-additional-scopes": [
    "reports:write"
  ],
  "x-unisoft-conditional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms:read",
    "forms_submit:read",
    "receipts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /ai-tasks/{taskId}/artifact

Download a frozen private task artifact

`download_unisoft_task_artifact`

Opt-in durable report-export task pilot. Disabled installations return 503 MCP_TASKS_DISABLED without calling the task engine or report source. Organisation API-key ownership is private to the exact authenticated key; root, system and campaign-restricted credentials are refused. Current credentials, organisation and all source grants are revalidated before every disclosure or command. Requires statistics:read plus source dataset/relation scopes: contacts/interactions=contacts:read, paiements=paiements:read, abonnements=abonnements:read, promesses=promesses:read, forms_submit=forms:read AND forms_submit:read, cerfas=receipts:read. forms_submit also requires a current same-organisation non-deleted form UUID. Use the authorised Explorer catalogue. The existing ReportExportRequest is reused unchanged: one requested page of at most 200 rows or a bounded aggregate of at most 30 groups, never a full dataset or transaction snapshot. Original raw units, currencies, format limits and PDF glyph restrictions still apply. No financial mutation, email or public share is created. The pilot expires at the source deadline, at most 600 seconds after creation; the general ceiling of 7 days after completion does not extend this shorter lifetime. Reads, retries and reconnects never renew expiry. No additional Unisoft confirmation step; the AI harness controls its own write approvals.

Download only the already frozen source bytes for a COMPLETED task, with attachment MIME type and safe file name. This REST-only operation never executes or renders an export. Verify byteLength and sha256 against the task metadata. No external or public download URL is created; unisoft://tasks/{taskId}/artifact identifies the corresponding authenticated MCP resource.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "statistics:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "taskId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Private task UUID returned by start_report_export_task."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Frozen private export bytes.",
  "content": {
    "application/json": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    },
    "text/csv": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    },
    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    },
    "application/pdf": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown request parameter.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Current principal or required scopes refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Private task or authorised source unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Idempotency conflict, retained execution lock or artifact not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 410

```json
{
  "description": "Task or source expired; no renewal is performed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source fields, format, file integrity or output limit refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 429

```json
{
  "description": "Current private task quota reached; inspect existing tasks before starting another export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Task pilot disabled, storage unavailable or command acknowledgement uncertain; inspect the same task before reconciling.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftTaskError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "statistics:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-conditional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms:read",
    "forms_submit:read",
    "receipts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": false
}
```

## Schemas

```json
{
  "components": {
    "schemas": {
      "UnisoftRequest_729f4d152ef616c77bcd": {
        "type": "object",
        "properties": {
          "dataset": {
            "type": "string",
            "enum": [
              "contacts",
              "interactions",
              "paiements",
              "abonnements",
              "promesses",
              "forms_submit",
              "cerfas"
            ]
          },
          "formId": {
            "type": "string",
            "format": "uuid",
            "description": "Required only for forms_submit, whose supported row mode is submission. Other datasets reject formId."
          },
          "filters": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 180,
                  "description": "Exact logical field identifier advertised by this dataset's authorised catalogue; never a database path or expression."
                },
                "op": {
                  "type": "string",
                  "enum": [
                    "contains",
                    "equals",
                    "startsWith",
                    "endsWith",
                    "in",
                    "notIn",
                    "eq",
                    "neq",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "between",
                    "before",
                    "after",
                    "isTrue",
                    "isFalse",
                    "isEmpty",
                    "isNotEmpty"
                  ]
                },
                "values": {
                  "type": "array",
                  "maxItems": 20,
                  "items": {
                    "oneOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "number"
                      }
                    ]
                  }
                }
              },
              "required": [
                "field",
                "op",
                "values"
              ],
              "additionalProperties": false
            }
          },
          "fields": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 180,
              "description": "Exact logical field identifier advertised by this dataset's authorised catalogue; never a database path or expression."
            }
          },
          "sort": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 180,
                  "description": "Exact logical field identifier advertised by this dataset's authorised catalogue; never a database path or expression."
                },
                "order": {
                  "type": "string",
                  "enum": [
                    "asc",
                    "desc"
                  ]
                }
              },
              "required": [
                "field",
                "order"
              ],
              "additionalProperties": false
            }
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 1
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          }
        },
        "required": [
          "dataset",
          "fields"
        ],
        "additionalProperties": false
      },
      "UnisoftRequest_411efe4dbeaae4a40e62": {
        "type": "object",
        "properties": {
          "dataset": {
            "type": "string",
            "enum": [
              "contacts",
              "interactions",
              "paiements",
              "abonnements",
              "promesses",
              "forms_submit",
              "cerfas"
            ]
          },
          "formId": {
            "type": "string",
            "format": "uuid",
            "description": "Required only for forms_submit, whose supported row mode is submission. Other datasets reject formId."
          },
          "filters": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 180,
                  "description": "Exact logical field identifier advertised by this dataset's authorised catalogue; never a database path or expression."
                },
                "op": {
                  "type": "string",
                  "enum": [
                    "contains",
                    "equals",
                    "startsWith",
                    "endsWith",
                    "in",
                    "notIn",
                    "eq",
                    "neq",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "between",
                    "before",
                    "after",
                    "isTrue",
                    "isFalse",
                    "isEmpty",
                    "isNotEmpty"
                  ]
                },
                "values": {
                  "type": "array",
                  "maxItems": 20,
                  "items": {
                    "oneOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "number"
                      }
                    ]
                  }
                }
              },
              "required": [
                "field",
                "op",
                "values"
              ],
              "additionalProperties": false
            }
          },
          "operation": {
            "type": "string",
            "enum": [
              "count",
              "sum",
              "avg",
              "min",
              "max"
            ]
          },
          "field": {
            "type": "string",
            "minLength": 1,
            "maxLength": 180,
            "description": "Required for sum/avg/min/max, forbidden for count. Only a root or computed NUMBER field with numericAggregate:true is accepted; MONEY and relation metrics are unsupported."
          },
          "groupBy": {
            "type": "string",
            "minLength": 1,
            "maxLength": 180,
            "description": "Optional single groupable field. Omit for one overall value. No multi-axis, date-bucket, expression or money aggregation is accepted."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30,
            "default": 12
          }
        },
        "required": [
          "dataset",
          "operation"
        ],
        "additionalProperties": false
      },
      "UnisoftTaskResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/UnisoftTask"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "UnisoftTask": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "QUEUED",
              "RUNNING",
              "COMPLETED",
              "CANCELLED",
              "FAILED"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "cancelRequested": {
            "type": "boolean"
          },
          "sourceJobId": {
            "type": "string",
            "format": "uuid"
          },
          "code": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$",
            "nullable": true
          },
          "artifact": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UnisoftTaskArtifact"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "nullable": true,
                "enum": [
                  null
                ]
              }
            ]
          }
        },
        "required": [
          "id",
          "state",
          "createdAt",
          "updatedAt",
          "expiresAt",
          "finishedAt",
          "cancelRequested",
          "sourceJobId",
          "code",
          "artifact"
        ]
      },
      "UnisoftTaskArtifact": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "uri": {
            "type": "string",
            "pattern": "^unisoft://tasks/[a-fA-F0-9-]{36}/artifact$"
          },
          "mimeType": {
            "type": "string",
            "enum": [
              "application/json",
              "text/csv",
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
              "application/pdf"
            ]
          },
          "fileName": {
            "type": "string",
            "enum": [
              "unisoft-report.json",
              "unisoft-report.csv",
              "unisoft-report.xlsx",
              "unisoft-report.pdf"
            ]
          },
          "sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "byteLength": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4194304
          }
        },
        "required": [
          "uri",
          "mimeType",
          "fileName",
          "sha256",
          "byteLength"
        ]
      },
      "UnisoftTaskError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          },
          "required": {
            "type": "array",
            "maxItems": 16,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "maxLength": 128
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string",
                "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
              },
              "location": {
                "type": "string",
                "enum": [
                  "body",
                  "path",
                  "query"
                ]
              }
            },
            "required": [
              "code"
            ]
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
