Skip to main content

​
Base URL

All API requests should be made to: https://api.omium.ai/api/v1

​
Authentication

All API requests require authentication using an API key. Include it in the X-API-Key header or as a Bearer token. 
# Using X-API-Key header (recommended)
curl -X GET "https://api.omium.ai/api/v1/billing/balance" \
  -H "X-API-Key: omium_xxxxx"

# Using Bearer token
curl -X GET "https://api.omium.ai/api/v1/billing/balance" \
  -H "Authorization: Bearer omium_xxxxx"

​
Endpoints

​
Get Credit Balance

GET /billing/balance Retrieve the current credit balance and its USD equivalent for the authenticated tenant. Response: 
{
  "credits_balance": 10000,
  "balance_usd": 100.00
}

​
Initiate Top-Up

POST /billing/topup Initiate a credit top-up, returning a client secret for Stripe payment. Request Body: 
{
  "amount_cents": 2000 // Amount in cents (e.g., 2000 for $20.00)
}
Response: 
{
  "client_secret": "pi_xxxxx_secret_xxxxx"
}

​
Get Transaction History

GET /billing/transactions Retrieve a list of all billing transactions (top-ups, usage, etc.) for the authenticated tenant. Query Parameters:
  • page: Page number (default: 1)
  • page_size: Items per page (default: 50)
  • type: Filter by transaction type (topup | usage | subscription)
Response: 
{
  "items": [
    {
      "id": "txn_1",
      "type": "topup",
      "amount": 5000,
      "currency": "usd",
      "credits_before": 0,
      "credits_after": 5000,
      "description": "Credit top-up",
      "payment_status": "completed",
      "created_at": "2025-01-01T10:00:00Z"
    },
    {
      "id": "txn_2",
      "type": "usage",
      "amount": -100,
      "currency": "usd",
      "credits_before": 5000,
      "credits_after": 4900,
      "description": "Workflow execution: my-workflow-1",
      "payment_status": null,
      "created_at": "2025-01-01T10:30:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 50
}

​
Create Subscription Checkout

POST /billing/subscriptions/create-checkout Initiate a Stripe Checkout session for a new subscription. Request Body: 
{
  "plan_id": "developer", // 'developer', 'pro', 'enterprise'
  "return_url": "https://app.omium.ai/billing?subscription=success"
}
Response: 
{
  "checkout_url": "https://checkout.stripe.com/pay/cs_xxxxx"
}

​
Get Subscription Status

GET /billing/subscriptions/status Retrieve the current subscription status for the authenticated tenant. Response: 
{
  "subscription_id": "sub_xxxxx",
  "plan_id": "pro",
  "status": "active", // 'active', 'trialing', 'past_due', 'cancelled', 'cancel_at_period_end'
  "current_period_start": "2025-01-01T00:00:00Z",
  "current_period_end": "2025-02-01T00:00:00Z",
  "cancel_at_period_end": false
}

​
Create Customer Portal Session

POST /billing/subscriptions/portal Create a session for the Stripe Customer Portal, allowing users to manage their subscription. Request Body: 
{
  "return_url": "https://app.omium.ai/billing"
}
Response: 
{
  "portal_url": "https://billing.stripe.com/p/xxxxx"
}

​
Cancel Subscription

POST /billing/subscriptions/cancel Cancel the current subscription. By default, it cancels at the end of the current billing period. Query Parameters:
  • immediately: If true, cancels the subscription immediately (default: false).
Response: 
{
  "subscription_id": "sub_xxxxx",
  "status": "cancel_at_period_end",
  "message": "Subscription will be cancelled at the end of the current billing period."
}