OTM API V2
The OTM API V2 sends AI usage telemetry to Antarctica and provides model reference data used by your integration.
Use this API to:
- Retrieve supported model reference data with
GET /v2/. - Submit completed model requests with
POST /v2/usage. - Receive optional model-data update notifications through webhooks.
V2 key creation and management are available in the Unified dashboard when enabled for your organization. If dashboard access is unavailable, request a key from Antarctica. Verify a new key with a test request before production use.
Base URL
https://otm-api.antarctica.ioUse the base URL provided for your environment if it differs from the production example. Send every request over HTTPS.
Quickstart
1. Create and export a server-side API key
Create a V2 key in OTM API Keys V2 in the Unified dashboard. Set an environment, name, server location, and optional IP allow list.
The key has the form otm_<environment>_<secret> and is shown only once. Store it in a server-side secret manager or protected environment variable.
export OTM_API_KEY="otm_prod_<secret>"
export OTM_API_BASE_URL="https://otm-api.antarctica.io"Never expose the key in browser code, mobile applications, source control, URLs, analytics, or logs.
2. Verify the connection
Retrieve model reference data:
curl "$OTM_API_BASE_URL/v2/" \
--header "X-API-Key: $OTM_API_KEY"A successful response is HTTP 200:
{
"data": [
{
"model_id": "model-id",
"model_name": "Model name",
"provider": "openai",
"energy_kwh": 0.001,
"energy_per_token": 0.000001,
"divergence_factor": 1.0,
"task_type": "engineering",
"effort_level": "medium",
"updated_at": "2026-11-17T08:00:00.000Z"
}
],
"meta": {
"count": 1,
"updatedSince": null,
"updatedAt": "2026-11-17T08:00:00.000Z"
}
}3. Send a test usage event
curl --request POST "$OTM_API_BASE_URL/v2/usage" \
--header "X-API-Key: $OTM_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"request_id": "req_01J8Z8R9Y0S4KQ2M7T3V",
"tenant_id": "tenant-acme-prod",
"ts_start": "2026-11-16T08:30:00.000Z",
"ts_first_token": "2026-11-16T08:30:00.320Z",
"ts_end": "2026-11-16T08:30:02.100Z",
"model_id": "model-id-from-your-agreement",
"model_version": "1",
"provider": "openai",
"region": "United States",
"effort_level": "medium",
"use_case": "engineering",
"department": "product",
"prompt_tokens": 120,
"cached_tokens": 0,
"completion_tokens": 240,
"reasoning_tokens": 0,
"visible_output_tokens": 240,
"status": "success"
}'A successful ingestion returns HTTP 202:
{
"requestId": "server-generated-reference",
"status": "accepted",
"duplicate": false,
"message": "Usage recorded successfully.",
"timestamp": "2026-11-17T09:00:00.000Z",
"riskAnalysis": null
}Before production use, review the endpoint schemas, idempotency behavior, errors, rate limits, and security requirements below.
Authentication
OTM API V2 authenticates every endpoint with an X-API-Key header:
X-API-Key: <server-side API key>V2 does not use Bearer authentication.
| Setting | Guidance |
|---|---|
| Name | Use a recognizable service name, such as production-usage-ingestion. |
| Server location | Select the location where the integrating server runs. |
| Environment | Use separate keys for dev, qa, preview, and prod. |
| IP allow list | Optionally enter stable public egress IP addresses, comma-separated. |
The secret is generated from 24 random bytes and represented as hexadecimal text. The full key is shown only when created. The dashboard can show a masked preview and usage information, but cannot retrieve the full secret later.
If dashboard creation is unavailable, Antarctica will issue the key through an approved secure channel. Do not create keys from a client application or browser.
Related guides:
Core Tier: GET /v2/
Retrieve model reference data for use in your integration.
curl "$OTM_API_BASE_URL/v2/" \
--header "X-API-Key: $OTM_API_KEY"Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
providers | string list | No | Filter by provider ID, such as openai or anthropic. |
models | string list | No | Filter by model ID. |
task_types | string list | No | Filter by task type. |
effort_levels | string list | No | Filter by effort level. |
updated_since | ISO 8601 UTC timestamp | No | Return model records updated at or after this timestamp. |
List parameters should be supplied as comma-separated, URL-encoded values:
curl "$OTM_API_BASE_URL/v2/?providers=openai,anthropic&effort_levels=low,medium&updated_since=2026-11-16T08%3A30%3A00.000Z" \
--header "X-API-Key: $OTM_API_KEY"Use data as the model reference data. Use model_id when submitting usage and use meta.updatedAt or row updated_at to track freshness.
For incremental refreshes, store the last successful meta.updatedAt, pass it as updated_since, and process every returned row. Confirm with Antarctica which model IDs are enabled for telemetry ingestion in your environment.
Deep Tier: POST /v2/usage
Submit one completed model request per call.
const response = await fetch(`${process.env.OTM_API_BASE_URL}/v2/usage`, {
method: "POST",
headers: {
"X-API-Key": process.env.OTM_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(usageEvent),
});
if (!response.ok) {
const error = await response.json();
throw new Error(`OTM API ${response.status}: ${error.message ?? "request failed"}`);
}
const result = await response.json();
console.log(result.status, result.duplicate);Do not log request headers or API keys. Handle non-2xx responses explicitly and retry transient failures with exponential backoff and jitter.
Request fields
All fields in the current V2 request schema are required.
| Field | Requirements |
|---|---|
request_id | Unique ID for this model request. Reuse it for retries of the same event; use a new ID for a different event. |
tenant_id | Tenant or account identifier. It is data, not an authorization boundary; key ownership determines the organization associated with the event. |
ts_start, ts_first_token, ts_end | ISO 8601 UTC timestamps ending in Z, ordered ts_start <= ts_first_token <= ts_end. |
model_id, model_version | Model identifier and version configured for your integration. Confirm supported model IDs with Antarctica. |
provider | Supported provider ID in lowercase, such as openai or anthropic. |
region, department | Non-empty strings describing the model server region and department. |
effort_level | One of low, medium, high, or xhigh. |
use_case | One of engineering, finance, legal, economics, or strategy. |
prompt_tokens, cached_tokens, completion_tokens, reasoning_tokens, visible_output_tokens | Non-negative integer counts. |
status | One of success, error, or timeout. |
Unknown fields are outside the request contract and should not be sent. Keep telemetry limited to operational metadata: do not include prompts, completions, credentials, or personal data.
Idempotency
The combination of tenant and request_id identifies an accepted usage event.
- Generate a unique
request_idfor each model request. - Reuse the original ID when retrying the same request.
- Reuse the ID until the API confirms acceptance.
- Do not use the ID of a completed event for a new event.
- If the HTTP response is lost, retrying safely returns the existing result or a duplicate indication.
A successful ingestion returns HTTP 202 with status: "accepted". Repeated submissions with the same tenant and request ID are treated as duplicates.
Success response
Use the response as follows:
| Field | Meaning |
|---|---|
status: "accepted" | The API accepted the usage event. HTTP status is 202. |
duplicate: true | The tenant and request ID were already accepted. Do not count this event as a new usage record. |
requestId | Server reference for support and log correlation. |
riskAnalysis | Optional informational risk result. It does not determine whether ingestion succeeded. |
The standard accepted response is:
{
"requestId": "server-generated-reference",
"status": "accepted",
"duplicate": false,
"message": "Usage recorded successfully.",
"timestamp": "2026-11-17T09:00:00.000Z",
"riskAnalysis": null
}For a successful, non-duplicate request where a risk result is available, riskAnalysis is an object:
{
"requestId": "server-generated-reference",
"status": "accepted",
"duplicate": false,
"message": "Usage recorded successfully.",
"timestamp": "2026-11-17T09:00:00.000Z",
"riskAnalysis": {
"normalizedCost": 0.3,
"normalizedEnergy": -0.1,
"divergenceFactor": 1.15,
"flag": "none",
"threshold": 2,
"cohortSize": 18,
"baselinePhase": "operational",
"baselineSource": "tenant_telemetry"
}
}Use flag (energy_ahead, cost_ahead, or none) as an informational monitoring signal. baselinePhase and baselineSource describe the result context.
riskAnalysis is null for duplicate requests, non-success usage, or when a result cannot be produced. A null value is not an ingestion failure.
Errors
OTM API V2 follows standard HTTP status codes.
| Code | Name | Typical meaning | Recommended action |
|---|---|---|---|
400 | Bad Request | JSON or field validation failed. | Correct the payload and do not retry unchanged. |
401 | Unauthorized | API key is missing, invalid, revoked, or malformed. | Verify server-side key configuration. |
403 | Forbidden | IP allow list or key permissions rejected the request. | Verify source IP and environment key permissions. |
429 | Too Many Requests | API-key or IP rate limit reached. | Read Retry-After, wait, then retry with the same request_id. |
500 | Internal Server Error | An unexpected server error occurred. | Retry with backoff and the same request_id; contact support if persistent. |
502, 503, 504 | Temporary service failure | Gateway or service is temporarily unavailable. | Retry with backoff and jitter; preserve the same request_id. |
Error responses include a human-readable message. Example:
{
"error": "Validation failed: \"request_id\" is required"
}Treat 400 as an application or payload error: validate locally before retrying. Treat 429 and transient 5xx responses as retryable. Preserve request_id for every retry and do not expose API keys or response payloads containing credentials in logs.
See Errors for the existing shared error guide.
Production integration security
- Keep keys server-side. Browser and mobile applications cannot protect a shared API key.
- Use the correct environment key. The key environment must match the configured record.
- Restrict source IPs. Permit only stable server egress IP addresses.
- Use HTTPS. Never send keys in query parameters.
- Minimize telemetry. Send usage metadata only.
- Make retries safe. Reuse
request_idonly for the same event. - Rotate and revoke. Replace any exposed key and revoke the compromised key.
- Respect throttling. Handle
429andRetry-Afterbefore retrying. - Do not log sensitive values. Avoid API keys, raw request bodies containing metadata, and error details that expose secrets.
Optional model-data webhooks
Webhooks notify a receiver that model reference data changed. They are not per-request ingestion receipts; the 202 response from POST /v2/usage is the ingestion acknowledgement.
Subscribe
For the current implementation, provide Antarctica with:
- A public HTTPS receiver URL.
- The environment for the subscription.
- A unique webhook signing secret.
There is no customer-facing webhook-subscription endpoint in the current API flow. Use a different signing secret for each subscription.
Delivery headers
| Header | Meaning |
|---|---|
X-Webhook-Id | Event ID. Use it as an idempotency key. |
X-Webhook-Signature | sha256=<hex HMAC-SHA256> of the exact raw request body, signed with the webhook secret. |
Event shape
{
"id": "event-uuid",
"type": "model_data.updated",
"occurredAt": "2026-11-16T08:30:00.000Z",
"version": "2026-11-16",
"resource": "/v2",
"changes": {
"updatedModelsCount": 5,
"fields": ["energy_kwh"]
}
}Verify the signature against the original raw bytes before parsing or acting on an event.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
app.use(
express.json({
verify(req, _res, body) {
req.rawBody = Buffer.from(body);
},
}),
);
app.post("/webhooks/otm-model-data", async (req, res) => {
const signature = req.get("X-Webhook-Signature") || "";
const eventId = req.get("X-Webhook-Id");
const rawBody = req.rawBody;
const secret = process.env.OTM_WEBHOOK_SECRET;
if (!rawBody || !secret || !/^sha256=[a-f0-9]{64}$/i.test(signature)) {
return res.sendStatus(401);
}
const expected = `sha256=${createHmac("sha256", secret)
.update(rawBody)
.digest("hex")}`;
const receivedBytes = Buffer.from(signature);
const expectedBytes = Buffer.from(expected);
if (
receivedBytes.length !== expectedBytes.length ||
!timingSafeEqual(receivedBytes, expectedBytes)
) {
return res.sendStatus(401);
}
if (!eventId || eventId !== req.body.id) {
return res.sendStatus(400);
}
// Persist eventId with a uniqueness constraint, then enqueue processing.
// Repeated event IDs must not repeat the side effect.
return res.sendStatus(204);
});The receiver should:
- Verify the signature before JSON parsing or business logic.
- Compare
X-Webhook-Idwithreq.body.id. - Persist event IDs before performing non-idempotent work.
- Return
2xxafter safely accepting an event. - Tolerate duplicates and out-of-order deliveries.
- Store signing secrets like API credentials and never log them.
Webhook delivery is retried asynchronously, up to 10 attempts with exponential backoff. Rotation and replacement of a signing secret must be coordinated with Antarctica so the receiver remains able to verify deliveries during the transition.
API versioning
The V2 route namespace is /v2. Antarctica may deprecate fields or behavior before removal. Integrations should:
- Validate response status and response fields rather than relying on extra fields.
- Ignore unknown JSON fields for forward compatibility.
- Pin model IDs and versions for production workflows.
- Refresh model reference data periodically or in response to model-data webhooks.
- Review this page and the API changelog before each integration upgrade.