# FAQ ### 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="" 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 **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: ```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 **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` | 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.kognitos.com/legacy/legacy-experience/rest-api/faq.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.