Codensity Node.js SDK and API Documentation

Getting Started

Codensity is a developer platform for tracking the resource usage and sustainability impact of your software features. It instruments your codebase at the feature level and estimates the energy and carbon behind each one, so you can see which features cost the most.

The platform is built around three concepts:

Projects: A grouping for your application (e.g. my-api, data-pipeline).
Environments: Isolated contexts within a project, such as development and production.
Features: Individual code paths you want to track, identified by a key string.

Prerequisites

Node.js 18+ (or any runtime with fetch support)
A Codensity account (sign up at getcodensity.com)
A project created in the Codensity dashboard
An SDK key issued for your target environment

Installation

Install the SDK from npm:

terminal

npm install @codensity/node
# or
pnpm add @codensity/node
# or
yarn add @codensity/node

Then add your SDK key to your environment:

.env

CODENSITY_KEY=cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@api.getcodensity.com

SDK keys are prefixed with cds_live_ for production environments and cds_test_ for non-production. Never commit keys to source control.

Quick Start

Initialize the client once (typically in a shared module):

codensity.ts

import { CodensityClient } from "@codensity/node";

export const codensity = new CodensityClient({
  key: process.env.CODENSITY_KEY,  // cds_live_...@host or cds_test_...@host
  environment: "production",
});

Then wrap the feature you want to track with codensity.track():

checkout.ts

import { codensity } from "./codensity";

export async function checkoutFlow(cart: Cart) {
  return codensity.track("checkout-flow", async () => {
    // your feature logic here
    return await processCart(cart);
  });
}

How it works: codensity.track() wraps your function, measures execution time and memory, then batches the telemetry event and sends it to POST /v1/ingest/batch in the background. Your function's return value is passed through unchanged.

API Reference

The Codensity ingestion API is the only endpoint your SDK or application needs to talk to. All requests authenticate via an x-api-key header containing an SDK key issued from your project's dashboard.

Authentication

All ingestion endpoints require an SDK key passed as an HTTP header:

x-api-key: cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are hashed at rest, so the raw key is only shown once, when you create it. Revoke and rotate keys from the Environments and keys tab of your project.

Batch Ingest

POST/v1/ingest/batch

The primary ingestion endpoint. Send up to 500 metric events in a single request. The SDK batches events internally and flushes on an interval, so you rarely need to call this directly.

Request body

Field	Type	Description
`sdkVersion`required	string	The version of the SDK sending the events (e.g. "1.0.0").
`appVersion`	string	Optional version of your application.
`events`required	array	Array of metric event objects. Maximum 500 events per batch.

Event object fields

Field	Type	Description
`featureKey`required	string	Identifier for the feature being tracked (e.g. "checkout-flow"). Must match a feature registered in the project.
`environmentKey`required	string	The target environment slug (e.g. "production", "development"). Must match an environment in the project.
`executionTimeMs`required	number	Wall-clock duration of the feature execution in milliseconds.
`memoryBytes`	number	Memory allocated by the feature in bytes. Used in CO₂ calculation. Optional but recommended.
`cpuPercent`	number	CPU utilization percentage at time of execution (0–100). Optional.
`timestamp`required	string	ISO 8601 timestamp of when the event occurred on the client.
`metadata`	object	Arbitrary key/value pairs (string \| number \| boolean). Stored as JSONB. Max 20 keys.

Response

202 Accepted

Events queued for processing.

400 Bad Request

Payload failed Zod validation.

401 Unauthorized

Missing or invalid x-api-key.

Single Event

POST/v1/ingest/single

A convenience endpoint for sending one event at a time. Accepts the same fields as a single item in the batch events array, plus sdkVersion and appVersion at the root level.

Field	Type	Description
`sdkVersion`required	string	SDK version sending the event.
`appVersion`	string	Optional app version.
`featureKey`required	string	Feature identifier.
`environmentKey`required	string	Target environment slug.
`executionTimeMs`required	number	Execution duration in milliseconds.
`memoryBytes`	number	Memory used in bytes.
`cpuPercent`	number	CPU utilization at time of call.
`timestamp`required	string	ISO 8601 client-side timestamp.
`metadata`	object	Optional key/value context.

Health Check

GET/v1/ingest/health

Returns a lightweight status response. Useful for verifying SDK connectivity and confirming the API key is valid before sending production events.

// 200 OK { status: "ok", project: "my-api", environment: "production" }

SDK Examples

Choose your language or tool below. Every example uses the same HTTP API; the SDK wraps the batching and retry logic for you.

terminal

# Health check: verify your key and project
curl -X GET https://api.getcodensity.com/v1/ingest/health \
  -H "x-api-key: cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Single event
curl -X POST https://api.getcodensity.com/v1/ingest/single \
  -H "Content-Type: application/json" \
  -H "x-api-key: cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "sdkVersion": "1.0.0",
    "featureKey": "checkout-flow",
    "environmentKey": "production",
    "executionTimeMs": 145,
    "memoryBytes": 268435456,
    "timestamp": "2026-04-15T10:00:00.000Z"
  }'

# Batch (up to 500 events)
curl -X POST https://api.getcodensity.com/v1/ingest/batch \
  -H "Content-Type: application/json" \
  -H "x-api-key: cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "sdkVersion": "1.0.0",
    "events": [
      {
        "featureKey": "checkout-flow",
        "environmentKey": "production",
        "executionTimeMs": 145,
        "memoryBytes": 268435456,
        "timestamp": "2026-04-15T10:00:00.000Z"
      },
      {
        "featureKey": "search-index",
        "environmentKey": "production",
        "executionTimeMs": 32,
        "memoryBytes": 67108864,
        "timestamp": "2026-04-15T10:00:01.000Z"
      }
    ]
  }'

Note: The cURL examples are useful for testing key validity and exploring the API shape. For production use, prefer the SDK or an HTTP client that handles retries and batching.