The Kolena API provides a straight forward way to push data to your agents and retrieve results.

​
Create an Agent in the Web UI

We recommend creating your agent in the web UI at https://agents.kolena.com. This is the easiest way to create prompts and validate results on a sample set of files. See our guide on Creating an Agent for more details.

Once you have created your agent, you can call its API methods by using its agent ID. You can find this in the URL of the agent page or by clicking the “Copy Agent ID” button on the agent’s overview page next to the Agent name.

​
Push Data to an Agent

Once you have an agent created, upload files to a new run using the POST /api/v1/client/agents/{agent_id}/runs method. Files are uploaded as multipart form data in this request. The response body will be a JSON object containing the run_id, which you can use to retrieve results later.

To authenticate your API requests, you need to set the Authorization header with your API key. See Managing API Keys for details.

​
Retrieve Results from an Agent

Results for an agent run can be retrieved using the GET /api/v1/client/agents/{agent_id}/runs method. This will return a list of all runs for the agent. Optionally, you can retrieve a single run using the run_id query parameter.

The response body is a JSON object of the following format:

{
    "agent_id": 1,
    "run_id": 1,
    "run_url": "https://agents.kolena.com/my_org/agents/1/runs/1",
    "created": "2025-01-01T00:00:00",
    "updated": "2025-01-05T00:00:00",
    "files": [
      "demo1.pdf",
      "demo2.csv"
    ],
    "order": [
      "prompt_1",
      "prompt_2"
    ],
    "data": {
      "prompt_1": {
        "metadata": {
          "citations": [
            {
              "file": "demo1.pdf",
              "pages": [
                2,
                5
              ]
            }
          ],
          "confidence": 1,
          "reasoning": "Looking at file demo1.pdf, ..."
        },
        "value": "foo"
      },
      "prompt_2": {
        "metadata": {
          "citations": [
            {
              "file": "demo2.csv",
              "pages": []
            }
          ],
          "confidence": 0.9,
          "reasoning": "The order amount is listed in demo2.csv"
        },
        "value": 123
      }
    }
}

Note in particular the data field, which contains the results of the agent run. data is a dictionary keyed by the prompt names you created in the Web UI for the agent. Each entry in data contains the results for that prompt, including:

  • value: The actual result value returned by the agent for that prompt.
  • metadata: Additional information about the result, such as reasoning, citations, and confidence.

Results can also be retrieved by setting up a webhook connection.