Documentation

REST API

Use the REST API to send events from any language. The TypeScript and Python SDKs wrap this endpoint with automatic batching and retries — use the REST API directly for Go, Rust, Java, or any other language.

Authentication

Pass your API key as a Bearer token in the Authorization header. You can find your API key on the Settings page.

Example Request

Send a single event with one vendor response:

curl -X POST https://margindash.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customer_id": "12345",
        "event_type": "summarize",
        "vendor_responses": [
          {
            "model": "openai/gpt-4o",
            "input_tokens": 1200,
            "output_tokens": 340
          }
        ]
      }
    ]
  }'

{
  "budget_state_version": 12,
  "results": [
    {
      "id": 42,
      "status": "created"
    }
  ]
}

Budget Blocklist Endpoint

Used by SDK budget-guard flows. Poll this endpoint with since_version to avoid downloading unchanged state.

{
  "version": 13,
  "ttl_seconds": 30,
  "changed": true,
  "recompute_in_progress": false,
  "blocked": {
    "organization": false,
    "event_types": ["summarize"],
    "customer_ids": ["cust_123"]
  }
}

{
  "version": 13,
  "ttl_seconds": 30,
  "changed": false,
  "recompute_in_progress": false
}

Field Reference

The request body is a JSON object with an events array. Each event accepts these fields:

Event fields

vendor_responses[] fields

Supported Models

Click a vendor to see valid slugs for the model field. You can also fetch this list programmatically via GET /api/v1/models.

Linking Stripe to Usage Tracking

Store your customer_id in the Stripe customer's metadata, and our invoice sync will automatically match Stripe payments to the correct customer in your dashboard. This ensures that invoice revenue is attributed to the same customer as your events, enabling accurate margin calculations.

Stripe Customer Creation

Store your customer ID in the Stripe customer's metadata:

curl https://api.stripe.com/v1/customers \
  -u "sk_live_YOUR_KEY:" \
  -d "name=Acme Corp" \
  -d "email=billing@acme.com" \
  -d "metadata[customer_id]=12345"

Backfilling Existing Customers

If you already have Stripe customers, you can backfill the metadata[customer_id] with a one-time script. Loop through your customers and update each one with your internal ID.
Existing invoices are automatically re-linked when you update the metadata — no manual re-sync needed.

import Stripe from "stripe";

const stripe = new Stripe("sk_live_YOUR_KEY");

// Your mapping of Stripe customer IDs to internal IDs
const customerMap: Record<string, string> = {
  "cus_ABC123": "12345",
  "cus_DEF456": "67890",
};

for (const [stripeId, internalId] of Object.entries(customerMap)) {
  await stripe.customers.update(stripeId, {
    metadata: { customer_id: internalId },
  });
}

import stripe

stripe.api_key = "sk_live_YOUR_KEY"

# Your mapping of Stripe customer IDs to internal IDs
customer_map = {
    "cus_ABC123": "12345",
    "cus_DEF456": "67890",
}

for stripe_id, internal_id in customer_map.items():
    stripe.Customer.modify(
        stripe_id,
        metadata={"customer_id": internal_id},
    )