> 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/faq.md).

# 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.

{% hint style="info" %}
Check out the [**API Keys**](/legacy/legacy-experience/account/api-keys.md) guide for more details on creating and managing API keys.
{% endhint %}

{% @supademo/embed url="<https://app.supademo.com/demo/cmdyu4k1e08pih5wkacfe3gxs>" demoId="cmdyu4k1e08pih5wkacfe3gxs" %}

***

### 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 <kbd>**Processes**</kbd> and click into a process.
2. Click on the menu in the top-right ( <kbd>⋮</kbd> ) and select <kbd>**Copy API Endpoint**</kbd>.
3. Copy the **agent\_id** from the API Information that appears.

<figure><img src="https://681267560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyXsMyN9vMn8AoQ4BYIwT%2Fuploads%2Fgit-blob-35957623a830299bfb73e3e6d0dc778d745bccb9%2Fcopy-agent-id.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Option 2: View All Agents

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

<figure><img src="https://681267560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyXsMyN9vMn8AoQ4BYIwT%2Fuploads%2Fgit-blob-dcff63b97a35a817fdb4d7ddaddc8645daa9da32%2Fview-all-agents-dropdown.png?alt=media" alt=""><figcaption></figcaption></figure>

***

### 3. How do I get a process ID?

#### Option 1: Copy API Endpoint

1. Navigate to <kbd>**Processes**</kbd> and click into a process.
2. Click on the menu in the top-right ( <kbd>⋮</kbd> ) and select <kbd>**Copy API Endpoint**</kbd>.
3. Copy the **process\_id** from the API Information that appears.

<figure><img src="https://681267560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyXsMyN9vMn8AoQ4BYIwT%2Fuploads%2Fgit-blob-bde2cc3e6efa6d852356dc8c1bc91b213bbc895c%2Fcopy-process-id.png?alt=media" alt=""><figcaption></figcaption></figure>

#### 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:

```bash
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:

```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"
```

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**](https://docs.kognitos.com/legacy/legacy-experience/rest-api/pages/JTObyzlpYAkBZm0SbUto#id-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)**](https://docs.kognitos.com/legacy/legacy-experience/rest-api/pages/JTObyzlpYAkBZm0SbUto#id-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:

```json
{
  "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.

{% file src="/files/TehpXpnrAf8cmqZ1bCw4" %}

#### **Step 1: Import the Collection**

1. Download the **Kognitos REST API Postman Collection** (above).
2. Open Postman and click <kbd>**Import**</kbd>.
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`     |

3. 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:

```klang
the file
open the json at the file
```

{% hint style="success" %}
You can also use the [**HTTP book**](/legacy/legacy-experience/books/reference/http.md) to make API requests directly from Kognitos instead of Postman. See [**FAQ #10**](#id-10.-how-do-i-call-the-kognitos-rest-api-from-within-an-automation) for more details.
{% endhint %}

***

### 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**](/legacy/legacy-experience/books/reference/http.md) 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
```