Push Measurement API

Audience: Admin, Developer
Page Type: How-To + Reference
Plan Feature: kpi_push_measurement (must be enabled for your tenant)

---

Overview

The Push Measurement API allows external systems to send KPI measurements directly to COS via HTTP requests authenticated with API keys. Unlike the Pull model (where COS fetches data from your APIs), the Push model lets your CI/CD pipelines, cron jobs, or applications send measurements whenever they're ready.

How It Works

External System                          COS
─────────────────                  ─────────────
                                   
  Your App / CI/CD  ──POST──►  /integrations/push/measurement
  (with x-api-key)               │
                                 ├─ Validate API key
                                 ├─ Verify KPI ownership
                                 └─ Write measurement

---

Prerequisites

1. Plan Feature: kpi_push_measurement must be enabled
2. API Key: At least one active API key for your tenant
3. KPI ID: The UUID of the KPI you want to send measurements for
4. KPI Type: One of the supported KPI entity types

Supported KPI Types

Type	Description
SWOT_KPI	SWOT Analysis KPI
PESTLE_KPI	PESTLE Analysis KPI
THEME_KPI	Strategic Theme KPI
KPI_DEFINITION	Standalone KPI Definition
BSC_KPI	Balanced Scorecard KPI
ASIS_KPI	As-Is Analysis KPI
OKR_KEY_RESULT	OKR Key Result
PRODUCT_SCORECARD_KPI	Product Scorecard KPI

---

Managing API Keys

Create an API Key

Navigate to Platform → API Keys in the COS sidebar, or go to /platform/api-keys.

1. Click New API Key
2. Enter a descriptive name (e.g., "CI/CD Pipeline", "Monitoring System")
3. Optionally set an expiration date
4. Click Create
5. Copy the key immediately — it will not be shown again

warning

API keys are only displayed once at creation time. Store the key securely (e.g., in a secrets manager or environment variable). If you lose the key, you must create a new one.

Revoke an API Key

If a key is compromised or no longer needed, click the delete button on the key row and confirm. Revoked keys cannot be reactivated.

Plan Limits

Plan	Max API Keys
Free	3
Business	5
Enterprise	Unlimited

---

Sending Measurements

Single Measurement

curl -X POST https://your-cos-instance.com/api/integrations/push/measurement \
  -H "x-api-key: cos_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "kpiId": "kpi-uuid-here",
    "kpiType": "KPI_DEFINITION",
    "actual": 85.5,
    "target": 100,
    "periodStart": "2025-06-01T00:00:00Z",
    "periodEnd": "2025-06-30T23:59:59Z"
  }'

Batch Measurements (up to 50)

curl -X POST https://your-cos-instance.com/api/integrations/push/measurements/batch \
  -H "x-api-key: cos_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": [
      {
        "kpiId": "kpi-uuid-1",
        "kpiType": "KPI_DEFINITION",
        "actual": 85.5,
        "target": 100,
        "periodStart": "2025-06-01T00:00:00Z",
        "periodEnd": "2025-06-30T23:59:59Z"
      },
      {
        "kpiId": "kpi-uuid-2",
        "kpiType": "BSC_KPI",
        "actual": 42,
        "periodStart": "2025-06-01T00:00:00Z",
        "periodEnd": "2025-06-30T23:59:59Z"
      }
    ]
  }'

Request Fields

Field	Type	Required	Description
kpiId	string	✅	UUID of the KPI
kpiType	string	✅	KPI entity type (see table above)
actual	number	✅	The actual/realized measurement value
target	number	❌	Target value for the period
forecast	number	❌	Forecasted value
periodStart	string	❌	ISO 8601 date. Defaults to start of current month
periodEnd	string	❌	ISO 8601 date. Defaults to end of current month

---

Code Examples

Python

import requests

API_KEY = "cos_your_api_key_here"
BASE_URL = "https://your-cos-instance.com/api"

response = requests.post(
    f"{BASE_URL}/integrations/push/measurement",
    headers={
        "x-api-key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "kpiId": "kpi-uuid-here",
        "kpiType": "KPI_DEFINITION",
        "actual": 85.5,
        "target": 100,
    },
)

print(response.status_code, response.json())

JavaScript / Node.js

const API_KEY = 'cos_your_api_key_here';
const BASE_URL = 'https://your-cos-instance.com/api';

const response = await fetch(`${BASE_URL}/integrations/push/measurement`, {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    kpiId: 'kpi-uuid-here',
    kpiType: 'KPI_DEFINITION',
    actual: 85.5,
    target: 100,
  }),
});

const data = await response.json();
console.log(data);

---

Authentication

All Push API requests must include the x-api-key header with a valid, active API key.

Error Responses

Status	Meaning
401	Missing or invalid API key
403	Key is revoked, expired, or tenant is inactive
400	Invalid request body (validation)
404	KPI not found or not owned by tenant
429	Rate limit exceeded

Security Notes

• API keys are hashed (SHA-256) before storage — COS never stores raw keys
• Keys are identified by a 8-character prefix (cos_xxxx) for management
• lastUsedAt is updated on each successful request
• Set expiration dates for rotating keys on a schedule
• Revoke keys immediately if compromised

---

In-App Push Snippet

When viewing a KPI detail drawer, the Push API section (visible when kpi_push_measurement is enabled) provides ready-to-use code snippets with the KPI ID and type pre-filled. Just replace YOUR_API_KEY with your actual key.

---

Push vs Pull Comparison

Aspect	Push API	Pull Integration
Direction	External → COS	COS → External
Auth	API Key (x-api-key)	JWT + configured endpoint auth
Schedule	On-demand (caller decides)	Cron-based (COS scheduler)
Setup	Create API key, send HTTP POST	Configure endpoint + binding
Plan Feature	kpi_push_measurement	kpi_api_integration
Best For	CI/CD, event-driven, webhooks	Periodic polling of external APIs