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

# Ciclo API

> Read teams and KPIs, and push KPI values into Ciclo from your own systems using the REST API.

## Overview

The Ciclo API lets external systems read and update your strategy data over HTTPS. Use it to connect internal dashboards, data pipelines, or automation scripts directly to Ciclo — without going through a third-party integration.

<CardGroup cols={2}>
  <Card title="Read data" icon="magnifying-glass">
    Look up your organisation's teams and the KPIs tracked against each one.
  </Card>

  <Card title="Update KPIs" icon="arrow-up-to-line">
    Push new [KPI](/features/performance-kpis) values from any system that can make an HTTP
    request — spreadsheets, internal tools, BI platforms, or custom scripts.
  </Card>
</CardGroup>

<Note>
  The API Keys tab in Settings requires the **manage\_apis** permission, which is available to
  organisation administrators.
</Note>

## Authentication

Every request must include an `x-api-key` header containing your API key:

```
x-api-key: your-api-key-here
```

### Getting an API key

<Steps>
  <Step title="Open Settings">
    Select **Settings** from the account menu.
  </Step>

  <Step title="Go to API Keys">
    Choose the **API Keys** tab.
  </Step>

  <Step title="Generate a key">
    Select **Generate API Key**. Copy the key immediately and store it somewhere safe — it is
    shown only once.
  </Step>
</Steps>

<Warning>
  Your API key grants read and write access to your organisation's teams and KPIs. Treat it
  like a password. Revoke keys you no longer need from the same **API Keys** tab.
</Warning>

## Endpoints

**Base URL**: `https://app.ciclostrategy.com/api/v1`

***

### List teams

Returns all teams in your organisation. Use the `id` values from this response when querying KPIs.

```
GET /teams
```

**Headers**

| Header      | Required | Value        |
| ----------- | :------: | ------------ |
| `x-api-key` |    Yes   | Your API key |

**Response (200)**

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Sales Team",
    "initials": "ST",
    "color": "emerald"
  },
  {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "name": "Operations",
    "initials": "OP",
    "color": "blue"
  }
]
```

***

### List KPIs for a team

Returns all active KPIs for the given team. Use the `id` values when updating KPI values.

```
GET /kpis?team_id={team_id}
```

**Query parameters**

| Parameter | Required | Description                          |
| --------- | :------: | ------------------------------------ |
| `team_id` |    Yes   | UUID of the team (from `GET /teams`) |

**Headers**

| Header      | Required | Value        |
| ----------- | :------: | ------------ |
| `x-api-key` |    Yes   | Your API key |

**Response (200)**

```json theme={null}
[
  {
    "id": 42,
    "name": "Monthly Recurring Revenue",
    "value": "$150,000",
    "change": "+5%",
    "change_type": "increase",
    "progress_text": "On track",
    "progress_value": 0.75,
    "target": "$200,000",
    "icon": "trending-up",
    "status": "healthy"
  }
]
```

***

### Update KPI values

Updates one or more KPIs. Pass all the updates you need in a single request.

```
PUT /kpis
```

**Headers**

| Header         | Required | Value              |
| -------------- | :------: | ------------------ |
| `x-api-key`    |    Yes   | Your API key       |
| `Content-Type` |    Yes   | `application/json` |

**Request body**

An array of update objects:

| Field          | Type   | Description                                                 |
| -------------- | ------ | ----------------------------------------------------------- |
| `kpiId`        | number | ID of the KPI to update (from `GET /kpis`)                  |
| `newValue`     | string | The new display value (e.g. `"$155,000"`, `"98%"`)          |
| `progressText` | string | Short progress label (e.g. `"On track"`, `"Behind target"`) |

```json theme={null}
[
  {
    "kpiId": 42,
    "newValue": "$155,000",
    "progressText": "On track"
  },
  {
    "kpiId": 43,
    "newValue": "98%",
    "progressText": "Target achieved"
  }
]
```

**Response (200)**

```json theme={null}
{
  "success": true,
  "results": [...]
}
```

***

## Example workflow

A typical integration maps team and KPI IDs once, then pushes updated values on a recurring schedule:

```bash theme={null}
# 1. List teams to find the team_id you need
curl https://app.ciclostrategy.com/api/v1/teams \
  -H "x-api-key: your-api-key"

# 2. List KPIs for that team to find the kpiId values
curl "https://app.ciclostrategy.com/api/v1/kpis?team_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: your-api-key"

# 3. Push updated values
curl -X PUT https://app.ciclostrategy.com/api/v1/kpis \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '[{"kpiId": 42, "newValue": "$155,000", "progressText": "On track"}]'
```

## Error responses

| Status                      | Meaning                                                                                                                      |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Missing or invalid parameters — check that `team_id` is present for KPI requests, and that the PUT body is a non-empty array |
| `401 Unauthorized`          | Missing or invalid API key                                                                                                   |
| `403 Forbidden`             | The key's user has no organisation — contact your organisation administrator                                                 |
| `500 Internal Server Error` | Unexpected server error                                                                                                      |

## Related

<CardGroup cols={2}>
  <Card title="Integrations overview" icon="plug" href="/integrations/overview" />

  <Card title="Performance & KPIs" icon="chart-line" href="/features/performance-kpis" />

  <Card title="Connected Apps in Settings" icon="gear" href="/features/admin-settings" />
</CardGroup>