Developers / Open API v1

An open API foryour cost data.

Import cost and usage from external collectors. Export your ledger, summaries, connections, alerts, anomalies and forecasts to internal systems.

An Open API clay gateway connecting servers and billing records

October 25, 2026 · Open API v1

API base URL

https://dash.onecloud.im/api/v1

Start in the console OpenAPI specification ↗Console API guide

API keys scoped to projects and permissions

In the console, open Project → Open API → API keys. Choose a name, scopes and expiry. The key is shown once and only its hash is stored. Every call rechecks current account permissions and project access. Revoke a key when needed.

Grant only the scopes you need

Separate permissions cover cost and usage reads, source writes, cost imports, connections, import history, alerts, anomalies and forecasts. Issuing keys requires project settings write permission and the current permissions behind each selected scope.

Request and import limits

120 requests per minute per key (also 300 per IP); 1–200 records and 100 KB per import. Dates use UTC with at most 366 days per read. Follow Retry-After for 429 responses.

Connect an external workflow

01
Issue an API key with the required permissions in your project.
02
Register an external source and retain its sourceId.
03
Transform source IDs, dates, services, currencies, costs and usage into JSON.
04
Validate with dryRun, then import with Idempotency-Key. Advance your checkpoint only after status complete.

Read APIs

Read APIs
HTTP / Endpoint	OneCloud Open API	Required scope
GET/me	Key identity	—
GET/projects	Projects	—
GET/providers	Provider directory	—
GET/projects/{projectId}/connections	Connection status	connections:read
GET/projects/{projectId}/sources	Sources	connections:read
GET/projects/{projectId}/costs	Cost ledger	costs:read
GET/projects/{projectId}/costs/summary	Cost summaries	costs:read
GET/projects/{projectId}/usage	Usage	usage:read
GET/projects/{projectId}/imports	Import history	imports:read
GET/projects/{projectId}/imports/{importId}	Import history	imports:read
GET/projects/{projectId}/alerts	Alert rules	alerts:read
GET/projects/{projectId}/anomalies	Anomalies	anomalies:read
GET/projects/{projectId}/forecasts	Forecasts	forecasts:read

Write APIs

Write APIs
HTTP / Endpoint	OneCloud Open API	Required scope
POST/projects/{projectId}/sources	Create or rename a source	sources:write
POST/projects/{projectId}/costs/import	Import cost and usage batches	costs:write
POST/projects/{projectId}/sources/{sourceId}/records/delete	Soft-delete original rows	costs:write

Bring data into your own tools

ERP, ETL, n8n and scheduled jobs can read cost and usage with cursor pagination. Incremental exports use updatedSince, a fixed updatedBefore and includeDeleted=true. Advance checkpoints after all pages succeed.

Update original records. Retry without duplicates.

sourceId and externalId identify each original row. Retry with the identical body and Idempotency-Key. Failed imports repair partial writes and aggregates; completed requests are not duplicated. Changing a date or currency also repairs old aggregates.

Preserve currencies and units

KRW and USD, requests, tokens and GB remain separate. Use billedCost=0 for usage-only records and negative costs for refunds. Do not import balances, top-ups, sales or payment principal as service costs.

Read and import examples

Set these environment variables to your console-issued key, project ID and source ID. The examples contain no real credentials.

Read APIs

curl "https://dash.onecloud.im/api/v1/projects/$ONECLOUD_PROJECT_ID/costs?from=2026-10-01&to=2026-10-25&limit=100" \
  -H "Authorization: Bearer $ONECLOUD_API_KEY"

Create or rename a source

curl -X POST "https://dash.onecloud.im/api/v1/projects/$ONECLOUD_PROJECT_ID/sources" \
  -H "Authorization: Bearer $ONECLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"externalId":"billing-production","provider":"KakaoCloud","name":"Production collector"}'

costs.json

{
  "sourceId": "SOURCE_ID",
  "records": [
    {
      "externalId": "invoice-202610-row-001",
      "usageDate": "2026-10-24",
      "service": "API requests",
      "currency": "KRW",
      "billedCost": 1200,
      "usageQuantity": 1000,
      "usageUnit": "requests",
      "tags": {
        "environment": "production"
      }
    }
  ]
}

Import cost and usage batches

curl -X POST "https://dash.onecloud.im/api/v1/projects/$ONECLOUD_PROJECT_ID/costs/import" \
  -H "Authorization: Bearer $ONECLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: billing-2026-10-batch-001' \
  --data-binary @costs.json

Use Open API alongside MCP

Open API supports reads and imports for external systems. ChatGPT and Claude can read permitted cost information through OneCloud MCP. MCP tools are read-only; MCP authorization and Open API keys are separate.

Start in the console Browse integrations