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

# Quickstart

> Download a task, send an answer and read your first reward

This guide takes you from a key to your first reward in three calls.

## Prerequisites

* An API key. AICME issues your lab's key when you join.
* The base URL for all requests: `https://api.aicmelabs.com`
* A task your lab is granted, and its version, such as `aicme/example-001` and `tv_3f9a1c07b2e45d18`.

Authenticate every request with your key in the `Authorization` header, as a bearer token. See
[Authentication](https://docs.aicmelabs.com/authentication.md) for details.

## Get a reward

Scoring is asynchronous: you send an answer, then poll for the reward until it's ready.

**1. Download the task**

Call `GET /v1/tasks/{task_id}/versions/{version}/package`. You get the task as a Harbor package, to run with your
agent. See [Tasks and packages](https://docs.aicmelabs.com/packages.md) for what's inside.

**2. Send an answer**

Call `POST /v1/rewards` with the task, the version you ran, and your agent's final answer. You get back a reward `id`.
Inside Harbor, the package's verifier makes this call for you.

**3. Poll for the reward**

Call `GET /v1/rewards/{id}` while `status` is `pending`, at least 5 seconds apart. It ends as `scored` or `failed`.

**4. Read the reward**

Once `status` is `scored`, read `scores.reward`, a number between 0 and 1. See [Rewards](https://docs.aicmelabs.com/rewards.md) for the other
scores and the flags.

## Full example

```bash cURL theme={null}
# 1. Download the task
curl https://api.aicmelabs.com/v1/tasks/aicme/example-001/versions/tv_3f9a1c07b2e45d18/package \
  -H "Authorization: Bearer your-api-key" \
  -o package.tar

# 2. Send an answer
curl -X POST https://api.aicmelabs.com/v1/rewards \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"task": {"id": "aicme/example-001", "version": "tv_3f9a1c07b2e45d18"}, "answer": "Your final answer here"}'

# 3. Get the reward, with the id from step 2. Repeat every 5 seconds while status is "pending"
curl https://api.aicmelabs.com/v1/rewards/REWARD_ID \
  -H "Authorization: Bearer your-api-key"
```

```python Python theme={null}
import time

import httpx

API_KEY = "your-api-key"
BASE = "https://api.aicmelabs.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def download(task_id: str, version: str) -> bytes:
    r = httpx.get(f"{BASE}/v1/tasks/{task_id}/versions/{version}/package", headers=HEADERS, timeout=60)
    r.raise_for_status()
    return r.content


def get_reward(task_id: str, version: str, answer: str) -> dict:
    task = {"id": task_id, "version": version}
    sent = httpx.post(f"{BASE}/v1/rewards", headers=HEADERS, json={"task": task, "answer": answer})
    sent.raise_for_status()
    reward_id = sent.json()["id"]

    while True:
        r = httpx.get(f"{BASE}/v1/rewards/{reward_id}", headers=HEADERS)
        r.raise_for_status()
        reward = r.json()
        if reward["status"] != "pending":
            return reward
        time.sleep(5)


with open("package.tar", "wb") as f:
    f.write(download("aicme/example-001", "tv_3f9a1c07b2e45d18"))

reward = get_reward("aicme/example-001", "tv_3f9a1c07b2e45d18", "Your final answer here")
print(reward["scores"])
```

```typescript TypeScript theme={null}
const API_KEY = "your-api-key";
const BASE = "https://api.aicmelabs.com";
const HEADERS = { Authorization: `Bearer ${API_KEY}` };

async function getReward(taskId: string, version: string, answer: string) {
  const sent = await fetch(`${BASE}/v1/rewards`, {
    method: "POST",
    headers: { ...HEADERS, "Content-Type": "application/json" },
    body: JSON.stringify({ task: { id: taskId, version }, answer }),
  });
  if (!sent.ok) throw new Error(await sent.text());
  const { id } = await sent.json();

  while (true) {
    const r = await fetch(`${BASE}/v1/rewards/${id}`, { headers: HEADERS });
    if (!r.ok) throw new Error(await r.text());
    const reward = await r.json();
    if (reward.status !== "pending") return reward;
    await new Promise((res) => setTimeout(res, 5000));
  }
}

const reward = await getReward("aicme/example-001", "tv_3f9a1c07b2e45d18", "Your final answer here");
console.log(reward.scores);
```

```json theme={null}
{
  "reward": 0.75,
  "partial": 0.75,
  "must_pass": 1.0,
  "all_pass": 0.0
}
```

## Next steps

> [card] [Rewards](https://docs.aicmelabs.com/rewards.md)
>
> The four scores, the flags, and a failed reward.

> [card] [Tasks and packages](https://docs.aicmelabs.com/packages.md)
>
> What's in a package, and how to run it with Harbor.

> [card] [Errors](https://docs.aicmelabs.com/errors.md)
>
> Every code, and which to retry.

> [card] [Limits](https://docs.aicmelabs.com/limits.md)
>
> How long an answer can be, and how long to wait.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.