> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents.kolena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Call Agents using the Kolena API

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](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](/quickstart#creating-the-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`](/api-reference/add-agent-run) 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.

<Note>
  To authenticate your API requests, you need to set the `Authorization` header with your API key. See [Managing API Keys](/api-keys) for details.
</Note>

## Retrieve Results from an Agent

Results for an Agent Run can be retrieved using the [`GET /api/v1/client/agents/{agent_id}/runs`](/api-reference/list-agent-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:

```json theme={null}
{
  "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"
  ],
  "status": "success",
  "data": {
    "prompt_1": {
      "status": "success",
      "metadata": {
        "citations": [
          {
            "file": "demo1.pdf",
            "pages": [
              2,
              5
            ]
          }
        ],
        "confidence": 1,
        "reasoning": "Looking at file demo1.pdf, ..."
      },
      "value": "foo"
    },
    "prompt_2": {
      "status": "success",
      "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 using a [webhook](/webhook).

## Get Agents information

You can list all Agents using the [`GET /api/v1/client/agents`](/api-reference/list-agents) method, and get specific
Agent information using the [`GET /api/v1/client/agents/{agent_id}`](/api-reference/get-agent) method.