API Integration

Cost Units Public API

North's Cost Units feature enables you to track and manage custom cost metrics within your cloud financial operations. With the Public API, you can programmatically upload and retrieve cost unit data from outside the North UI, using secure API keys for authentication.

When to Use the Public API

Use the Public API when you want to:

• Automate recurring metric uploads from an internal data pipeline or warehouse

• Sync business metrics from a third-party system on a schedule

• Retrieve Cost Unit data programmatically for custom dashboards or reports

• Integrate metric uploads into CI/CD or ETL workflows

Creating API Keys

Before you can use the Public API, you need to create an API key within the North application. API keys provide secure, programmatic access to your cost unit data without requiring interactive authentication.

Key Management in the North UI

To create an API key within the North application:

1. Navigate to the Streams tab in app.north.cloud

2. Open the API Keys management section

3. Provide a name for the key (for example, "Production Pipeline" or "Weekly Sync")

4. Optionally set an expiration date (maximum 365 days from creation)

5. Click Create

6. Copy and save the API key immediately. The full key is only shown once at creation time and cannot be retrieved later.

API keys use the format north_api_{secret_hash}.

Viewing API Keys

The API Keys section displays all active keys for your organization, including:

• Key name

• Date created

• Expiration date (if set)

• Last used timestamp

Revoking API Keys

To revoke a key, click the delete action next to the key you want to remove. Revoked keys are immediately deactivated and can no longer be used to authenticate API requests.

Important: When you create a new API key, it will be displayed only once. Make sure to save it securely, as it cannot be retrieved later. If you lose an API key, you'll need to create a new one and revoke the old key.

Each API key is scoped to your organization and provides access to all cost units within your account. The key is validated on every API request to ensure secure access to your data.

Public API Endpoints

The Public API provides two endpoints for interacting with your cost units:

• GET /public/cost-units - Retrieve existing cost unit data

• POST /public/cost-units - Update cost unit data with new metrics

Note: The Public API supports updating existing cost units only. To create new cost units, use the North UI or internal API endpoints.

Authentication

All Public API requests require authentication using an API key. Include your API key in the Authorization header of each request:

Authorization: ApiKey north_api_{your_key}

The API key is validated on every request. Requests with missing, invalid, expired, or revoked keys will receive a 403 response.

Additionally, you must include your account_number as a query parameter in all requests. The API validates that the account number matches the organization associated with your API key.

Base URL

https://api.north.cloud

GET /public/cost-units

Retrieve data from an existing cost unit.

GET /public/cost-units

Headers

Header	Required	Description
Authorization	Yes	Your API key in the following format: ApiKey <your-api-key>
Content-Type	No	Content type (not required for GET requests)

Query Parameters

Parameter	Required	Type	Description
account_number	Yes	string	Your AWS account number (validated against the API key's organization)
costUnitId	Yes	string	Cost unit identifier (e.g., bu-123:cu-456)

Example Request

GET /public/cost-units?account_number=123456789&costUnitId=bu-123:cu-456 Authorization: north_api_AbCdEfGhIjKlMnOpQrStUvWx

Response

Success (200 OK):

{ "status": "success", "message": "Cost unit retrieved successfully", "data": { "businessUnitId": "bu-123", "costUnitId": "cu-456", "status": "processed", "data": { "2024-01-01": { "metric": "100.50" }, "2024-01-02": { "metric": "150.75" } }, "errors": [], "warnings": [], "metadata": { "name": "Impressions", "type": "numerator", "granularity": "daily", "description": "Ad impressions" }, "createdAt": "2024-01-10T12:00:00", "updatedAt": "2024-01-15T08:30:00" }, "meta": { "count": 1, "scannedCount": 1 }, "error": null }

Error Responses:

• 400 Bad Request: Missing required parameters, invalid format, or business unit ownership validation failed

• 401 Unauthorized: Invalid or missing API key

• 403 Forbidden: API key does not have access to the requested resource

• 500 Internal Server Error: An internal error occurred while processing your request

POST /public/cost-units

Update an existing cost unit with new data points. This endpoint supports both merging new data with existing data and completely replacing existing data.

POST /public/cost-units

Headers

Header	Required	Description
Authorization	Yes	Your API key: ApiKey {your_key}
Content-Type	Yes	Must be application/json

Query Parameters

Parameter	Required	Type	Description
account_number	Yes	string	Your AWS account number (validated against the API key's organization)
replace	No	boolean	When true, completely replaces existing data instead of merging. Default: false

Request Body

Field	Required	Type	Description
costUnitId	Yes	string	Cost unit identifier (required - updates only, no creation via public API).
data	Yes	array	List of data points with date and metric values

Data Point Structure

Each item in the data array must contain:

Field	Required	Type	Description
date	Yes	string (date)	Date in YYYY-MM-DD format (e.g., "2024-01-15")
metric	Yes	string	Metric value as string (will be validated as decimal number)

Example Request

POST /public/cost-units?account_number=123456789 Authorization: north_api_AbCdEfGhIjKlMnOpQrStUvWx Content-Type: application/json { "costUnitId": "bu-123:cu-456", "data": [ { "date": "2024-01-15", "metric": "100.50" } ] }

Response

Success (200 OK):

{ "status": "success", "message": "Cost unit processed successfully", "data": { "businessUnitId": "bu-123", "costUnitId": "cu-456", "dataPoints": 2, "errorsCount": 0, "warningsCount": 0, "errors": [], "warnings": [], "processedData": { "2024-01-15": { "metric": "100.50" }, "2024-01-16": { "metric": "150.75" } } } }

Error Responses:

• 400 Bad Request: Missing required fields, invalid date format, invalid metric value, or business unit ownership validation failed

• 401 Unauthorized: Invalid or missing API key

• 403 Forbidden: API key does not have access to the requested resource

• 500 Internal Server Error: An internal error occurred while processing your request

Data Merging vs. Replacement

The POST endpoint supports two modes of operation:

• Merge (default): When replace=false or omitted, new data points are merged with existing data. If a date already exists, the new metric value will update the existing value.

• Replace: When replace=true, all existing data in the cost unit is completely replaced with the new data array. This is useful for removing dates from a cost unit by sending an array that excludes those dates.

Tip: Use replace=true when you want to ensure your cost unit contains exactly the data points you send, removing any dates that aren't included in your request.

Data Validation Notes

When uploading data via the POST endpoint, keep in mind:

• metadata and viewId fields are ignored if provided. Existing metadata is preserved.

• Future dates are rejected. For daily granularity, the current date is also rejected.

• Duplicate dates within a single request are rejected.

• Metric values are rounded to 2 decimal places.

Examples

Retrieve a Cost Unit

curl -X GET \ "https://api.north.cloud/public/cost-units?account_number=123456789&costUnitId=bu-123:cu-456" \ -H "Authorization: ApiKey north_api_AbCdEfGhIjKlMnOpQrStUvWx"

Upload Data to a Cost Unit

curl -X POST \ "https://api.north.cloud/public/cost-units?account_number=123456789" \ -H "Authorization: ApiKey north_api_AbCdEfGhIjKlMnOpQrStUvWx" \ -H "Content-Type: application/json" \ -d '{ "costUnitId": "bu123:cu-456", "data": [ {"date": "2024-01-01", "metric": "1500.00"}, {"date": "2024-01-02", "metric": "1620.50"} ] }'

Best Practices

• Secure Your API Keys: Treat API keys like passwords. Store them securely and never commit them to version control or share them publicly.

• Use Key Expiration: Set expiration dates on your API keys to ensure regular rotation and limit exposure if a key is compromised.

• Monitor Key Usage: Regularly review your active API keys and revoke any that are no longer needed.

• Validate Data Before Sending: Ensure dates are in YYYY-MM-DD format and metric values are valid decimal numbers before making API calls.

• Handle Errors Gracefully: Implement proper error handling in your integration to handle authentication failures, validation errors, and rate limiting.