ModulesAI ModuleOTM API V2

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

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

SettingGuidance
NameUse a recognizable service name, such as production-usage-ingestion.
Server locationSelect the location where the integrating server runs.
EnvironmentUse separate keys for dev, qa, preview, and prod.
IP allow listOptionally 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

ParameterTypeRequiredDescription
providersstring listNoFilter by provider ID, such as openai or anthropic.
modelsstring listNoFilter by model ID.
task_typesstring listNoFilter by task type.
effort_levelsstring listNoFilter by effort level.
updated_sinceISO 8601 UTC timestampNoReturn 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.

FieldRequirements
request_idUnique ID for this model request. Reuse it for retries of the same event; use a new ID for a different event.
tenant_idTenant 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_endISO 8601 UTC timestamps ending in Z, ordered ts_start <= ts_first_token <= ts_end.
model_id, model_versionModel identifier and version configured for your integration. Confirm supported model IDs with Antarctica.
providerSupported provider ID in lowercase, such as openai or anthropic.
region, departmentNon-empty strings describing the model server region and department.
effort_levelOne of low, medium, high, or xhigh.
use_caseOne of engineering, finance, legal, economics, or strategy.
prompt_tokens, cached_tokens, completion_tokens, reasoning_tokens, visible_output_tokensNon-negative integer counts.
statusOne 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_id for 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:

FieldMeaning
status: "accepted"The API accepted the usage event. HTTP status is 202.
duplicate: trueThe tenant and request ID were already accepted. Do not count this event as a new usage record.
requestIdServer reference for support and log correlation.
riskAnalysisOptional 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.

CodeNameTypical meaningRecommended action
400Bad RequestJSON or field validation failed.Correct the payload and do not retry unchanged.
401UnauthorizedAPI key is missing, invalid, revoked, or malformed.Verify server-side key configuration.
403ForbiddenIP allow list or key permissions rejected the request.Verify source IP and environment key permissions.
429Too Many RequestsAPI-key or IP rate limit reached.Read Retry-After, wait, then retry with the same request_id.
500Internal Server ErrorAn unexpected server error occurred.Retry with backoff and the same request_id; contact support if persistent.
502, 503, 504Temporary service failureGateway 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_id only for the same event.
  • Rotate and revoke. Replace any exposed key and revoke the compromised key.
  • Respect throttling. Handle 429 and Retry-After before 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

HeaderMeaning
X-Webhook-IdEvent ID. Use it as an idempotency key.
X-Webhook-Signaturesha256=<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-Id with req.body.id.
  • Persist event IDs before performing non-idempotent work.
  • Return 2xx after 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.