> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/rest-api/examples.md).

# Examples

Examples and workflows for using the Kognitos REST API v2.

### 1. Check Health

Check the health and availability of the REST API v2.

{% tabs %}
{% tab title="Request" %}

```bash
curl -X GET "https://rest-api.app.kognitos.com/v2/health" \
    -H "x-api-key: YOUR_API_KEY"
```

{% endtab %}

{% tab title="Sample Response" %}

```
{
  "status": "OK"
}
```

{% endtab %}
{% endtabs %}

### 2. List Processes

List all processes in a specified agent.

{% tabs %}
{% tab title="Request" %}

```bash
curl -X GET "https://rest-api.app.kognitos.com/v2/processes?agent_id=YOUR_AGENT_ID&limit=10" \
  -H "x-api-key: YOUR_API_KEY"
```

{% endtab %}

{% tab title="Sample Response" %}

```
{
  "items": [
    {
      "id": "b4fznghynbdemslfd5k044fgd",
      "name": "Process invoice",
      "agent_id": "a7xm2kp9qwj3v5nh8t4c6r1e9z",
      "stage": "Published"
    }
  ],
  "continuation_token": null
}
```

{% endtab %}
{% endtabs %}

### 3. Get a Specific Process

Get details for a specific process by ID.

{% tabs %}
{% tab title="Request" %}

```bash
curl -X GET "https://rest-api.app.kognitos.com/v2/processes/YOUR_PROCESS_ID?agent_id=YOUR_AGENT_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

{% endtab %}

{% tab title="Sample Response" %}

```
{
  "agent_id": "a7xm2kp9qwj3v5nh8t4c6r1e9z",
  "id": "b4fznghynbdemslfd5k044fgd",
  "name": "Process invoice",
  "stage": "Draft"
}
```

{% endtab %}
{% endtabs %}

### 4. List Runs

List all runs for a specific process and agent.

{% tabs %}
{% tab title="Request" %}

```bash
curl -X GET "https://rest-api.app.kognitos.com/v2/runs?process_id=YOUR_PROCESS_ID&agent_id=YOUR_AGENT_ID&limit=10" \
  -H "x-api-key: YOUR_API_KEY"
```

{% endtab %}

{% tab title="Sample Response" %}

```
{
  "items": [
    {
      "id": "9nvx1hdm9bd74rp585oe81t5i",
      "name": "Process invoice 42",
      "process_id": "b4fznghynbdemslfd5k044fgd",
      "agent_id": "a7xm2kp9qwj3v5nh8t4c6r1e9z",
      "stage": "Published",
      "status": "Succeeded",
      "created_at": "2021-01-01T12:00:00",
      "file_ids": null,
      "outputs": null
    }
  ],
  "continuation_token": null
}
```

{% endtab %}
{% endtabs %}

### 5. Get a Specific Run

Get the status and details of a specific run.

{% tabs %}
{% tab title="Request" %}

```bash
curl -X GET "https://rest-api.app.kognitos.com/v2/runs/YOUR_RUN_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

{% endtab %}

{% tab title="Sample Response" %}

```
{
  "id": "9nvx1hdm9bd74rp585oe81t5i",
  "name": "Process invoice 42",
  "process_id": "b4fznghynbdemslfd5k044fgd",
  "agent_id": "a7xm2kp9qwj3v5nh8t4c6r1e9z",
  "stage": "Published",
  "status": "Succeeded",
  "created_at": "2021-01-01T12:00:00",
  "file_ids": null,
  "outputs": [
    {
      "name": "total_items",
      "value": 42
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### 6. Start a New Run

Trigger a new process run *(without a file upload)*. The request body must be sent as **JSON** with the following fields:

#### Required Fields

| Field        | Description                                                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`       | The process name (e.g., "to process the invoices")                                                                                     |
| `process_id` | The unique identifier of the process you want to execute.                                                                              |
| `agent_id`   | The unique identifier of the agent that will execute the process.                                                                      |
| `stage`      | The version of the process to run. Use `"Published"` for production processes or `"Draft"` for testing processes still in development. |

#### Optional Fields

| Field      | Description                                                                                                                                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputs`   | An array of input parameters to pass to your process. Each input is an object with `name` (the name of the data element/fact as defined in your process) and `value` (the actual value for that data element/fact). |
| `file_ids` | An array of file IDs for the run.                                                                                                                                                                                   |

{% hint style="success" %}
This example shows how to start a new run *without* a file upload. To start a run *with* a file upload and learn how to specify **file\_ids**, see [Example 7](#id-7.-start-a-new-run-with-file-upload).
{% endhint %}

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://rest-api.app.kognitos.com/v2/runs" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "to process the invoices",
    "process_id": "b4fznghynbdemslfd5k044fgd",
    "agent_id": "a7xm2kp9qwj3v5nh8t4c6r1e9z",
    "stage": "Published",
    "inputs": [
        {
            "name": "invoice number", 
            "value": "INV-2024-001"
        },
        {
            "name": "customer id",
            "value": "CUST-12345" 
        },
        {
            "name": "amount",
            "value": "1500.00"
        }
    ]
  }'
```

{% endtab %}

{% tab title="Sample Response" %}

```
{
  "id": "9nvx1hdm9bd74rp585oe81t5i",
  "name": "to process the invoices",
  "process_id": "b4fznghynbdemslfd5k044fgd",
  "agent_id": "a7xm2kp9qwj3v5nh8t4c6r1e9z",
  "stage": "Published",
  "status": "Created",
  "created_at": "2021-01-01T12:00:00",
  "file_ids": null,
  "outputs": null
}
```

{% endtab %}
{% endtabs %}

### 7. Start a New Run (with File Upload)

Trigger a new process run with an uploaded file. This is a 3-step process.

#### Step 1

First, make a **POST request** to /v2/files to get an upload URL.

> The request body must be sent as JSON with two required fields:
>
> * `file_name`: The name of your file
> * `agent_id`: Your agent ID

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://rest-api.app.kognitos.com/v2/files" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "document.pdf",
    "agent_id": "YOUR_AGENT_ID"
  }'
```

{% endtab %}

{% tab title="Sample Response" %}

```
{
  "id": "s3://bucket/path/to/uploaded-file.pdf",
  "file_name": "document.pdf",
  "upload_url": "https://example.com/file.pdf",
  "upload_http_method": "POST",
  "upload_http_headers": {},
  "upload_fields": {
    "AWSAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "x-amz-security-token": "IQoJb3JpZ2luX2VjELv//////////...",
    "Content-Type": "application/pdf",
    "key": "path/to/file.pdf",
    "policy": "eyJ...base64_policy...",
    "signature": "abc123..."
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
Save this response — you'll need it in subsequent steps.
{% endhint %}

#### Step 2

Next, make a **POST request** to the `upload_url` from the response in Step 1.

> The request body must be sent as **form data** (`multipart/form-data`) and should include all the `upload_fields` *(key, AWSAccessKeyId, x-amz-security-token, policy, signature, Content-Type)* from the response in Step 1, plus the `file` to be uploaded.

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://example.com/file.pdf" \
  -F "key=path/to/file.pdf" \
  -F "AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE" \
  -F "x-amz-security-token=IQoJb3JpZ2luX2VjELv//////////..." \
  -F "policy=eyJ...base64_policy..." \
  -F "signature=abc123..." \
  -F "Content-Type=application/pdf" \
  -F "file=@document.pdf"
```

{% endtab %}

{% tab title="Sample Response" %}
A successful upload returns a `204` status code with no response body.

```
204 No Content
```

{% endtab %}
{% endtabs %}

#### Step 3

Finally, make a **POST request** to /v2/runs to start a new run.

> In your request body, add the `id` *(from the response in Step 1)* to the `file_ids` array.

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://rest-api.app.kognitos.com/v2/runs" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Process invoice with document",
    "process_id": "YOUR_PROCESS_ID",
    "agent_id": "YOUR_AGENT_ID",
    "stage": "Published",
    "file_ids": ["s3://bucket/path/to/uploaded-file.pdf"]
  }'
```

{% endtab %}

{% tab title="Sample Response" %}

```
{
  "id": "9nvx1hdm9bd74rp585oe81t5i",
  "name": "Process invoice with document",
  "process_id": "b4fznghynbdemslfd5k044fgd",
  "agent_id": "a7xm2kp9qwj3v5nh8t4c6r1e9z",
  "stage": "Published",
  "status": "Created",
  "created_at": "2021-01-01T12:00:00",
  "file_ids": ["s3://bucket/path/to/uploaded-file.pdf"],
  "outputs": null
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Refer to [Example 6](#id-6.-start-a-new-run) for more details on optional and required fields for this request.
{% endhint %}

### Notes

1. **Authentication**: All requests require an API key. Include your key in the `x-api-key` header.
2. **Base URLs**: All examples use the US region base URL: `https://rest-api.app.kognitos.com`. If you're in a different region, adjust the base URL accordingly:
   1. UK: `https://rest-api.uk.kognitos.com`
   2. EU: `https://rest-api.eu.kognitos.com`
3. **Placeholders**: Replace placeholder values in the requests with your actual values:
   1. `YOUR_API_KEY`: Your API key secret
   2. `YOUR_AGENT_ID`: Your agent ID
   3. `YOUR_PROCESS_ID`: Your process ID
   4. `YOUR_RUN_ID`: Your run ID

{% hint style="success" %}
For more information, check out our [**Frequently Asked Questions**](/legacy/legacy-experience/rest-api/faq.md).
{% endhint %}