Examples

Examples and workflows for using the Kognitos REST API v2.

1. Check Health

Check the health and availability of the REST API v2.

Request

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

Sample Response

{
  "status": "OK"
}

2. List Processes

List all processes in a specified agent.

Request

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"

Sample Response

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

3. Get a Specific Process

Get details for a specific process by ID.

Request

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"

Sample Response

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

4. List Runs

List all runs for a specific process and agent.

Request

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"

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
}

5. Get a Specific Run

Get the status and details of a specific run.

Request

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

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

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.

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.

Request

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

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
}

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

Request

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

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..."
  }
}

Save this response — you'll need it in subsequent steps.

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.

Request

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 "[email protected]"

Sample Response

A successful upload returns a 204 status code with no response body.

204 No Content

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.

Request

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

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
}

Refer to Example 6 for more details on optional and required fields for this request.

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

For more information, check out our Frequently Asked Questions.