POST
/
api
/
v1
/
messages
curl -X POST https://api.costmcp.com/api/v1/messages \
  -H "Authorization: Bearer $COSTMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "slideshow-studio",
    "source": "api",
    "idempotency_key": "run-abc-1",
    "message": {
      "type": "usage",
      "provider": "openai",
      "model": "gpt-image-2",
      "unit_type": "image",
      "quantity": 1,
      "estimated_cost": 0.04,
      "feature": "slide_generation"
    }
  }'

curl -X POST https://api.costmcp.com/api/v1/messages \
  -H "Authorization: Bearer $COSTMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "experiments",
    "message": {
      "type": "expense",
      "vendor": "midjourney",
      "amount": 30,
      "category": "image_gen"
    }
  }'

curl -X POST https://api.costmcp.com/api/v1/messages \
  -H "Authorization: Bearer $COSTMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "project": "progressgoat",
      "message": {
        "type": "usage",
        "provider": "openai",
        "model": "gpt-4o-mini",
        "unit_type": "total_tokens",
        "quantity": 12000,
        "estimated_cost": 0.002
      }
    }
  ]'

{
  "id": "61363057-54d3-4dae-9883-7df9f56cc979",
  "amount_usd": 0.04,
  "project_id": "1a161e43-c198-4376-82be-d0b1322c1f1f",
  "created_at": "2026-07-09T21:48:21.437351+00:00"
}
Requires permission log_usage. Auto-upserts the project by slug. Idempotent when idempotency_key is set.
​
project
string
required
Project slug (auto-created if missing)
​
source
string
api | mcp | manual | import (default api)
​
idempotency_key
string
Dedup key within the workspace
​
timestamp
string
ISO datetime for the event
​
message
object
required
Discriminated CostMessage — see CostMessage
You may also send a JSON array of envelopes (1–100).

​
Responses

201 (single)
​
id
string
required
Ledger row UUID
​
amount_usd
number
required
Resolved USD amount
​
project_id
string
required
Project UUID
​
created_at
string
required
ISO timestamp
201 (batch): { "messages": [ ...same objects... ] }
StatusMeaning
400Invalid JSON
401 / 403Auth / permission
500Validation or persist failure
curl -X POST https://api.costmcp.com/api/v1/messages \
  -H "Authorization: Bearer $COSTMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "slideshow-studio",
    "source": "api",
    "idempotency_key": "run-abc-1",
    "message": {
      "type": "usage",
      "provider": "openai",
      "model": "gpt-image-2",
      "unit_type": "image",
      "quantity": 1,
      "estimated_cost": 0.04,
      "feature": "slide_generation"
    }
  }'

curl -X POST https://api.costmcp.com/api/v1/messages \
  -H "Authorization: Bearer $COSTMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "experiments",
    "message": {
      "type": "expense",
      "vendor": "midjourney",
      "amount": 30,
      "category": "image_gen"
    }
  }'

curl -X POST https://api.costmcp.com/api/v1/messages \
  -H "Authorization: Bearer $COSTMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "project": "progressgoat",
      "message": {
        "type": "usage",
        "provider": "openai",
        "model": "gpt-4o-mini",
        "unit_type": "total_tokens",
        "quantity": 12000,
        "estimated_cost": 0.002
      }
    }
  ]'

{
  "id": "61363057-54d3-4dae-9883-7df9f56cc979",
  "amount_usd": 0.04,
  "project_id": "1a161e43-c198-4376-82be-d0b1322c1f1f",
  "created_at": "2026-07-09T21:48:21.437351+00:00"
}