Mock API reference used by the interactive docs explorer.
| OpenAPI version | Contract version | REST base path |
|---|---|---|
| 3.1.0 | 2026-03-15 | /api/v1 |
Servers
| URL | Environment |
|---|---|
https://app.monetizekit.app/api/v1 | Development environment |
https://app.monetizekit.app/api/v1 | Staging environment |
https://app.monetizekit.app/api/v1 | Production environment |
usage operations
Submit usage event
POST /usage/events — Ingests a metered usage event.
Operation ID: usage.submit.
Required scopes: usage:write.
Parameters
| Name | In | Required | Description | Schema | Example |
|---|---|---|---|---|---|
Idempotency-Key | header | yes | Client-generated idempotency key | { "type": "string" } | "idem_2f5fd2b7a1" |
Request schema
{
"type": "object",
"required": [
"customerId",
"meterId",
"value"
],
"properties": {
"customerId": {
"type": "string"
},
"meterId": {
"type": "string"
},
"value": {
"type": "number"
}
}
}Request example
{
"customerId": "cust_dev_1001",
"meterId": "api_requests",
"value": 15,
"occurredAt": "2026-03-15T12:00:00.000Z"
}Responses
201 — Recorded
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"customerId": {
"type": "string"
},
"meterId": {
"type": "string"
},
"eventName": {
"type": "string"
},
"value": {
"type": "number"
},
"status": {
"type": "string"
},
"occurredAt": {
"type": "string"
},
"createdAt": {
"type": "string"
}
}
}{
"id": "evt_9012",
"customerId": "cust_dev_1001",
"meterId": "api_requests",
"eventName": "usage.recorded",
"value": 15,
"status": "success",
"occurredAt": "2026-03-15T12:00:00.000Z",
"createdAt": "2026-03-15T12:00:00.000Z"
}Submit a batch of usage events
POST /usage/events/batch — Ingests up to 500 usage events in one request. Each item carries its own idempotency key, so replaying a window missed during an outage converges without duplicates while preserving each event's original occurredAt. Item-level failures do not fail the batch. Each accepted item names its stored event by eventId; pass ?include=events to receive the full event object per item.
Operation ID: usage.submitBatch.
Required scopes: usage:write.
Parameters
| Name | In | Required | Description | Schema | Example |
|---|---|---|---|---|---|
include | query | no | Comma-separated extras to include per result. `events` adds the stored event object (the shape POST /usage/events returns) to every created or duplicate item; omitted by default because a 500-item batch would return roughly 200 KB of copies of the request. | { "type": "string", "enum": [ "events" ] } | "events" |
Request schema
{
"type": "object",
"required": [
"events"
],
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"required": [
"customerId",
"meterId",
"value",
"idempotencyKey"
],
"properties": {
"customerId": {
"type": "string"
},
"meterId": {
"type": "string"
},
"value": {
"type": "number"
},
"idempotencyKey": {
"type": "string"
},
"occurredAt": {
"type": "string"
}
}
}
}
}
}Request example
{
"events": [
{
"customerId": "cust_dev_1001",
"meterId": "api_requests",
"value": 15,
"idempotencyKey": "idem_replay_0001",
"occurredAt": "2026-03-15T11:00:00.000Z"
},
{
"customerId": "cust_dev_1001",
"meterId": "api_requests",
"value": 8,
"idempotencyKey": "idem_replay_0002",
"occurredAt": "2026-03-15T11:30:00.000Z"
}
]
}Responses
200 — Batch processed
{
"type": "object",
"required": [
"summary",
"results"
],
"properties": {
"summary": {
"type": "object",
"required": [
"total",
"created",
"duplicate",
"errors"
],
"properties": {
"total": {
"type": "number"
},
"created": {
"type": "number"
},
"duplicate": {
"type": "number"
},
"errors": {
"type": "number"
}
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"idempotencyKey",
"status"
],
"properties": {
"index": {
"type": "number"
},
"idempotencyKey": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"created",
"duplicate",
"error"
]
},
"eventId": {
"type": "string",
"description": "Id of the stored event, on created and duplicate items."
},
"event": {
"type": "object",
"description": "The stored event, only when the request asked for ?include=events."
},
"error": {
"type": "object",
"description": "On error items: the same code and message a single-event request would return.",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}{
"summary": {
"total": 2,
"created": 1,
"duplicate": 1,
"errors": 0
},
"results": [
{
"index": 0,
"idempotencyKey": "idem_replay_0001",
"status": "created",
"eventId": "evt_9013"
},
{
"index": 1,
"idempotencyKey": "idem_replay_0002",
"status": "duplicate",
"eventId": "evt_9014"
}
]
}Get usage counter
GET /usage/{customerId}/{meterId} — Returns current counter for a customer and meter.
Operation ID: usage.retrieve.
Required scopes: usage:read.
Parameters
| Name | In | Required | Description | Schema | Example |
|---|---|---|---|---|---|
customerId | path | yes | Customer ID | { "type": "string" } | "cust_dev_1001" |
meterId | path | yes | Meter key | { "type": "string" } | "api_requests" |
Responses
200 — Success
{
"type": "object",
"properties": {
"customerId": {
"type": "string"
},
"meterId": {
"type": "string"
},
"current": {
"type": "number"
},
"limit": {
"type": "number"
}
}
}{
"customerId": "cust_dev_1001",
"meterId": "api_requests",
"current": 120,
"limit": 1000
}Get usage breakdown
GET /usage/{customerId}/{meterId}/breakdown — Returns usage grouped by a required dimension.
Operation ID: usage.breakdown.
Required scopes: usage:read.
Parameters
| Name | In | Required | Description | Schema | Example |
|---|---|---|---|---|---|
customerId | path | yes | Customer ID | { "type": "string" } | "cust_dev_1001" |
meterId | path | yes | Meter key | { "type": "string" } | "api_requests" |
dimension | query | yes | Dimension to group usage by | { "type": "string" } | "model" |
Responses
200 — Success
{
"type": "object",
"properties": {
"meterId": {
"type": "string"
},
"dimension": {
"type": "string"
},
"window": {
"type": "string"
},
"total": {
"type": "number"
},
"totalCreditCost": {
"type": "number"
},
"breakdown": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"total": {
"type": "number"
},
"count": {
"type": "number"
},
"creditCost": {
"type": "number"
}
}
}
}
}
}{
"meterId": "api_requests",
"dimension": "model",
"window": "all",
"total": 120,
"totalCreditCost": 42,
"breakdown": [
{
"value": "gpt-4.1",
"total": 120,
"count": 4,
"creditCost": 42
}
]
}