FAQ

Frequently Asked Questions for the Kognitos REST API.

1. How do I get an API Key?

  1. Log in to your Kognitos account.

  2. Navigate to User Icon > API Keys.

  3. Click on New API Key. Assign it a name and a scope.

  4. Click Create to generate your secret key. Store the key securely, as it won't be shown again.

Check out the API Keys guide for more details on creating and managing API keys.

2. How do I get an agent ID?

There are two ways you can get an agent ID:

Option 1: Copy API Endpoint

  1. Navigate to Processes and click into a process.

  2. Click on the menu in the top-right ( ⋮ ) and select Copy API Endpoint.

  3. Copy the agent_id from the API Information that appears.

Option 2: View All Agents

Click on the agent dropdown menu and select View All to see a complete list of all your agents with their corresponding IDs:

3. How do I get a process ID?

Option 1: Copy API Endpoint

  1. Navigate to Processes and click into a process.

  2. Click on the menu in the top-right ( ⋮ ) and select Copy API Endpoint.

  3. Copy the process_id from the API Information that appears.

Option 2: Via API

Make a GET request to /v2/processes. Replace YOUR_AGENT_ID with your agent ID and YOUR_API_KEY with your API key in the following request:

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

Look for the id in the response, which is the process ID:


        {
            "agent_id": "9xk2m3pd7tq8v1za4b5n6c7e8f",
            "stage": "Published",
            "id": "a1b2c3d4e5f6g7h8i9j0klmn1",
            "name": "extract company names from resumes"
        },
        {
            "agent_id": "9xk2m3pd7tq8v1za4b5n6c7e8f",
            "stage": "Draft",
            "id": "o9p8q7r6s5t4u3v2w1x0yzab2",
            "name": "summarize customer feedback comments"
        }
    ],
    "continuation_token": null
}

4. How do I get a run ID?

Make a GET request to /v2/runs to retrieve a list of runs. Replace YOUR_PROCESS_ID, YOUR_AGENT_ID, and YOUR_API_KEY with your actual values:

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"

Look for the id in the response, which is the run ID:

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

5. How do I start a new run using the API?

Without Files

To trigger a new run without file uploads, see Example 6: Start a New Run, which shows how to make a POST request to /v2/runs, include required fields (name, process_id, agent_id, stage) and pass optional input parameters.

With One or More Files

To trigger a new run with one or more files, see Example 7: Start a New Run (with File Upload), which shows the complete 3-step workflow:

  1. Make a POST request to /v2/files

  2. Make a POST request to the upload URL obtained in Step #1

  3. Make a POST request to /v2/runs to start a run with the file ID in the file_ids array

6. How do I populate the outputs when getting a run's result?

When you retrieve a run via GET /v2/runs/{run_id}, the API returns facts that start with "the output" in the outputs field of the response.

In your automation process, define facts like the output value or the output invoice number at the top level (not within a subprocess or indented blocks). For example:

the output invoice number
the output total amount
the output status

API Response

When you call GET /v2/runs/{run_id}, you'll receive:

{
  "id": "9nvx1hdm9bd74rp585oe81t5i",
  "name": "Process invoice 42",
  "status": "Succeeded",
  "outputs": [
    {
      "name": "invoice number",
      "value": "INV-2024-001"
    },
    {
      "name": "total amount",
      "value": 1500.00
    },
    {
      "name": "status",
      "value": "processed"
    }
  ]
}

7. How do I make API requests with Postman?

Import our pre-built Postman collection to quickly call all Kognitos REST API endpoints.

22KB
kognitos-rest-api-postman-collection.json
Open

Step 1: Import the Collection

  1. Download the Kognitos REST API Postman Collection (above).

  2. Open Postman and click Import.

  3. Select the downloaded JSON file. The collection will appear in your workspace with all endpoints organized.

Step 2: Set Up Environment Variables

Create environment variables:

Variable
Description
Example Value

api_key

Your API key

your-api-key-here

base_url

API base URL for your region

https://rest-api.app.kognitos.com

agent_id

Your agent ID

a7xm2kp9qwj3v5nh8t4c6r1e9z

process_id

Your process ID

b4fzn1ghy2nbd3ems6lfd5k044fgd

  1. Save the environment and select it from the dropdown.

Step 3: Make Requests

The collection includes pre-configured requests for all endpoints. The x-api-key header and base URLs use the environment variables you set up, so you can start making requests immediately.

8. How can I import Postman output into Kognitos?

  1. Save the response from Postman as a .json file and upload it to your Kognitos automation.

  2. In your automation, write the following lines to upload and open the JSON file:

the file
open the json at the file

You can also use the HTTP book to make API requests directly from Kognitos instead of Postman. See FAQ #10 for more details.

10. How do I call the Kognitos REST API from within an automation?

You can make requests to the Kognitos REST API directly from within a Kognitos playground or process automation using the HTTP book.

Example: Get All Processes

create a json
use the above as the headers
set the headers's "x-api-key" to "YOUR_API_KEY"
retrieve "https://rest-api.app.kognitos.com/v2/processes?agent_id=YOUR_AGENT_ID"
... the headers is the headers
the output is the above

Example: Get a Specific Run

create a json
use the above as the headers
set the headers's "x-api-key" to "YOUR_API_KEY"
retrieve "https://rest-api.app.kognitos.com/v2/runs/YOUR_RUN_ID"
... the headers is the headers
the output is the above

Example: Start a New Run

create a json
use the above as the headers
set the headers's "x-api-key" to "YOUR_API_KEY"

create a json
use the above as the request body
set the request body's "name" to "Process invoice"
set the request body's "process_id" to "YOUR_PROCESS_ID"
set the request body's "agent_id" to "YOUR_AGENT_ID"
set the request body's "stage" to "Published"

post the request body to "https://rest-api.app.kognitos.com/v2/runs"
... the headers is the headers

the output is the above
PreviousExamplesNextProcesses

Last updated

Was this helpful?