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

# Performance

> Manage OKRs, appraisals, and promotions via the API.

The Performance endpoints cover three areas — **objectives (OKRs)**, **appraisals**,
and **promotions** — for your own employees.

<Note>
  Performance is an **add-on**. The company must have it enabled — otherwise every
  `/v1/performance/*` call returns `403 MODULE_NOT_ENABLED` (a company admin enables
  it in **Settings → Modules**). Reads need `performance:read`, writes need
  `performance:write`. Writes aren't available with a `kua_test_` key (add-ons have
  no sandbox yet).
</Note>

## Objectives (OKRs)

An objective has key results and progress check-ins.

<CodeGroup>
  ```bash cURL theme={null}
  # Create an objective with a key result
  curl https://api.kuahr.com/v1/performance/objectives \
    -X POST -H "X-Api-Key: kua_live_your_key_here" -H "Content-Type: application/json" \
    -d '{
      "title": "Grow monthly active users",
      "cycleLabel": "2026 Q3",
      "cycleStart": "2026-07-01",
      "cycleEnd": "2026-09-30",
      "keyResults": [{ "description": "Reach 50k MAU", "targetValue": 50000, "unit": "users" }]
    }'

  # List / get
  curl "https://api.kuahr.com/v1/performance/objectives?cycleLabel=2026%20Q3" -H "X-Api-Key: kua_live_your_key_here"
  ```

  ```ts Node theme={null}
  const objective = await kua.performance.objectives.create({
    title: "Grow monthly active users",
    cycleLabel: "2026 Q3",
    cycleStart: "2026-07-01",
    cycleEnd: "2026-09-30",
    keyResults: [{ description: "Reach 50k MAU", targetValue: 50000, unit: "users" }],
  });

  await kua.performance.objectives.list({ cycleLabel: "2026 Q3" });
  await kua.performance.keyResults.update(objective.keyResults[0].id, { currentValue: 12000, confidenceScore: 0.7 });
  await kua.performance.checkIns.create(objective.objective.id, { note: "On track", confidence: 0.7 });
  ```

  ```python Python theme={null}
  objective = kua.performance.objectives.create(
      title="Grow monthly active users", cycle_label="2026 Q3",
      cycle_start="2026-07-01", cycle_end="2026-09-30",
      key_results=[{"description": "Reach 50k MAU", "targetValue": 50000, "unit": "users"}],
  )

  kua.performance.objectives.list(cycle_label="2026 Q3")
  kua.performance.key_results.update(objective.key_results[0].id, current_value=12000, confidence_score=0.7)
  kua.performance.check_ins.create(objective.objective.id, note="On track", confidence=0.7)
  ```
</CodeGroup>

## Appraisals

Creating a cycle **seeds a review for every active employee**; each review flows
self → manager → complete.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.kuahr.com/v1/performance/appraisal-cycles \
    -X POST -H "X-Api-Key: kua_live_your_key_here" -H "Content-Type: application/json" \
    -d '{ "name": "H2 2026 review", "opensOn": "2026-10-01", "closesOn": "2026-10-31" }'

  curl "https://api.kuahr.com/v1/performance/appraisal-cycles/{id}/reviews" -H "X-Api-Key: kua_live_your_key_here"

  curl -X POST "https://api.kuahr.com/v1/performance/reviews/{id}/manager" \
    -H "X-Api-Key: kua_live_your_key_here" -H "Content-Type: application/json" \
    -d '{ "body": "Great half", "rating": 4 }'
  ```

  ```ts Node theme={null}
  const cycle = await kua.performance.appraisalCycles.create({ name: "H2 2026 review", opensOn: "2026-10-01", closesOn: "2026-10-31" });
  const reviews = await kua.performance.appraisalCycles.reviews(cycle.id);
  await kua.performance.reviews.submitManager(reviews[0].id, { body: "Great half", rating: 4 });
  ```

  ```python Python theme={null}
  cycle = kua.performance.appraisal_cycles.create(name="H2 2026 review", opens_on="2026-10-01", closes_on="2026-10-31")
  reviews = kua.performance.appraisal_cycles.reviews(cycle.id)
  kua.performance.reviews.submit_manager(reviews[0].id, body="Great half", rating=4)
  ```
</CodeGroup>

## Promotions

An append-only record of role/salary changes (amounts in minor units, e.g. kobo):

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.kuahr.com/v1/performance/promotions \
    -X POST -H "X-Api-Key: kua_live_your_key_here" -H "Content-Type: application/json" \
    -d '{ "employeeId": "b2c3…", "fromTitle": "Engineer", "toTitle": "Senior Engineer", "toSalaryMinor": 55000000, "effectiveDate": "2026-08-01" }'

  curl "https://api.kuahr.com/v1/performance/employees/{employeeId}/promotions" -H "X-Api-Key: kua_live_your_key_here"
  ```

  ```ts Node theme={null}
  await kua.performance.promotions.create({ employeeId: "b2c3…", fromTitle: "Engineer", toTitle: "Senior Engineer", toSalaryMinor: 55_000_000, effectiveDate: "2026-08-01" });
  await kua.performance.promotions.list("b2c3…");
  ```

  ```python Python theme={null}
  kua.performance.promotions.create(employee_id="b2c3…", from_title="Engineer", to_title="Senior Engineer", to_salary_minor=55_000_000, effective_date="2026-08-01")
  kua.performance.promotions.list("b2c3…")
  ```
</CodeGroup>