Meter Events
1 operation under /v1/meter-events (POST): parameters, status codes, refusal bodies, and the same request in curl, HTTP, Python and TypeScript.
Base URL: https://api.codespar.dev
Every operation below requires a Bearer token. See Authentication.
POST /v1/meter-events
https://api.codespar.dev/v1/meter-eventsRecord a usage event
event names the meter (its event_name) in the caller's project; the meter must exist. customer is the tenant's customer id. value is required for sum, max and last meters (non-negative, up to six decimals) and must be omitted (or 1) for a count meter. timestamp is the event's own time, default now; it must fall in the previous or the current cycle and at most 5 minutes ahead.
IDEMPOTENT ON event_id: an id already recorded with the same meter, customer and value (and the same timestamp, when one is given) answers 200 with duplicate: true and is counted once. A different payload under a known id is refused with 409.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
customer | string | yes | — |
event | string | yes | — |
event_id | string | yes | — |
timestamp | string (date-time) | no | — |
value | number | string | no | — |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
201 | object | OK |
400 | object | Bad Request. |
404 | object | No meter in this project for that event name. |
409 | object | The event_id was recorded with a different payload. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
customer | string | yes | — |
customer_name | string,null | yes | The consumer's display name when customer is a consumer id of the organization. |
duplicate | true | yes | — |
event | string | yes | — |
event_id | string | yes | — |
meter_id | string | yes | — |
object | "meter_event" | yes | — |
occurred_at | string | yes | The event's own time; decides its cycle. |
received_at | string | yes | — |
value | string | yes | 1 for a count meter; the event's value otherwise. |
curl -X POST https://api.codespar.dev/v1/meter-events \
-H "Authorization: Bearer $CODESPAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"event": "string",
"customer": "string",
"value": 1000,
"event_id": "event_0000000000000000",
"timestamp": "2026-01-15T12:00:00.000Z"
}'POST /v1/meter-events HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json
{
"event": "string",
"customer": "string",
"value": 1000,
"event_id": "event_0000000000000000",
"timestamp": "2026-01-15T12:00:00.000Z"
}import os
import requests
res = requests.post(
"https://api.codespar.dev/v1/meter-events",
headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
json={
"event": "string",
"customer": "string",
"value": 1000,
"event_id": "event_0000000000000000",
"timestamp": "2026-01-15T12:00:00.000Z"
},
)
res.raise_for_status()
data = res.json()const res = await fetch("https://api.codespar.dev/v1/meter-events", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"event": "string",
"customer": "string",
"value": 1000,
"event_id": "event_0000000000000000",
"timestamp": "2026-01-15T12:00:00.000Z"
}),
});
const data = await res.json();const result = await cs.api.post("/v1/meter-events", {
body: {
event: "string",
customer: "string",
value: 1000,
event_id: "event_0000000000000000",
timestamp: "2026-01-15T12:00:00.000Z"
}
});{
"object": "meter_event",
"event_id": "event_0000000000000000",
"meter_id": "meter_0000000000000000",
"customer": "string",
"customer_name": "Example",
"value": "string",
"occurred_at": "string",
"received_at": "string",
"event": "string",
"duplicate": true
}