# Examples ### 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 %} --- # 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/examples.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.