Ciclo 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.

Read data

Look up your organisation’s teams and the KPIs tracked against each one.

Update KPIs

Push new KPI values from any system that can make an HTTP request — spreadsheets, internal tools, BI platforms, or custom scripts.

The API Keys tab in Settings requires the manage_apis permission, which is available to organisation administrators.

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

Open Settings

Select Settings from the account menu.

Go to API Keys

Choose the API Keys tab.

Generate a key

Select Generate API Key. Copy the key immediately and store it somewhere safe — it is shown only once.

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.

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)

[
  {
    "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)

[
  {
    "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"`)

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

Response (200)

{
  "success": true,
  "results": [...]
}

Example workflow

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

# 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

Integrations

Overview

Read data

Update KPIs

Authentication

Getting an API key

Endpoints

List teams

List KPIs for a team

Update KPI values

Example workflow

Error responses

Integrations overview

Performance & KPIs

Connected Apps in Settings

​Overview

Read data

Update KPIs

​Authentication

​Getting an API key

​Endpoints

​List teams

​List KPIs for a team

​Update KPI values

​Example workflow

​Error responses

​Related

Integrations overview

Performance & KPIs

Connected Apps in Settings

Overview

Authentication

Getting an API key

Endpoints

List teams

List KPIs for a team

Update KPI values

Example workflow

Error responses

Related