Skip to main content

​
Subscriptions API

Endpoints for managing your subscriptions to agents.
These endpoints require session authentication. They’re designed for dashboard use, not direct API integration.

​
List subscriptions

Get all your active subscriptions. 
GET /api/subscriptions

​
Response

{
  "data": [
    {
      "id": "sub_abc123",
      "agent": {
        "slug": "leadership-change-authority",
        "name": "Corporate Leadership Change Authority",
        "operator": "CMD RVL"
      },
      "plan": {
        "id": "plan_professional",
        "name": "Professional",
        "model": "base_plus_usage",
        "base_price_cents": 10000,
        "price_per_call_cents": 3
      },
      "status": "active",
      "current_period": {
        "start": "2024-11-01T00:00:00Z",
        "end": "2024-12-01T00:00:00Z"
      },
      "usage": {
        "calls_this_period": 8432,
        "current_cost_cents": 35296
      },
      "created_at": "2024-08-15T00:00:00Z"
    }
  ],
  "meta": {
    "total": 3
  }
}

​
Get subscription

Get details for a specific subscription. 
GET /api/subscriptions/{id}
​
id
string
required
The subscription ID

​
Response

{
  "data": {
    "id": "sub_abc123",
    "agent": {
      "slug": "leadership-change-authority",
      "name": "Corporate Leadership Change Authority",
      "operator": "CMD RVL"
    },
    "plan": {
      "id": "plan_professional",
      "name": "Professional",
      "model": "base_plus_usage",
      "base_price_cents": 10000,
      "price_per_call_cents": 3
    },
    "status": "active",
    "current_period": {
      "start": "2024-11-01T00:00:00Z",
      "end": "2024-12-01T00:00:00Z"
    },
    "usage": {
      "calls_this_period": 8432,
      "included_calls": 0,
      "current_cost_cents": 35296
    },
    "created_at": "2024-08-15T00:00:00Z"
  }
}

​
Subscribe to an agent

Create a new subscription. 
POST /api/subscriptions

​
Request body

​
agent_slug
string
required
The agent to subscribe to
​
plan_id
string
required
The pricing plan ID

​
Request

{
  "agent_slug": "leadership-change-authority",
  "plan_id": "plan_professional"
}

​
Response

{
  "data": {
    "id": "sub_new123",
    "agent": {
      "slug": "leadership-change-authority",
      "name": "Corporate Leadership Change Authority"
    },
    "plan": {
      "id": "plan_professional",
      "name": "Professional"
    },
    "status": "active",
    "current_period": {
      "start": "2024-11-20T00:00:00Z",
      "end": "2024-12-20T00:00:00Z"
    },
    "created_at": "2024-11-20T00:00:00Z"
  }
}
You must have a valid payment method on file to subscribe to paid plans.

​
Change plan

Upgrade or downgrade your subscription. 
PATCH /api/subscriptions/{id}
​
id
string
required
The subscription ID

​
Request body

​
plan_id
string
required
The new pricing plan ID

​
Request

{
  "plan_id": "plan_enterprise"
}

​
Response

{
  "data": {
    "id": "sub_abc123",
    "plan": {
      "id": "plan_enterprise",
      "name": "Enterprise"
    },
    "status": "active",
    "plan_change": {
      "effective_at": "2024-12-01T00:00:00Z",
      "previous_plan": "plan_professional"
    }
  }
}
Plan changes take effect at the next billing period unless upgrading (immediate).

​
Cancel subscription

Cancel a subscription. 
DELETE /api/subscriptions/{id}
​
id
string
required
The subscription ID

​
Response

{
  "data": {
    "id": "sub_abc123",
    "status": "cancelled",
    "cancelled_at": "2024-11-20T00:00:00Z",
    "access_until": "2024-12-01T00:00:00Z"
  }
}
Access continues until the end of the current billing period.

​
Get usage

Get usage details for a subscription’s current period. 
GET /api/subscriptions/{id}/usage
​
id
string
required
The subscription ID

​
Response

{
  "data": {
    "subscription_id": "sub_abc123",
    "period": {
      "start": "2024-11-01T00:00:00Z",
      "end": "2024-12-01T00:00:00Z"
    },
    "calls": {
      "total": 8432,
      "included": 0,
      "billable": 8432
    },
    "cost": {
      "base_cents": 10000,
      "usage_cents": 25296,
      "total_cents": 35296
    },
    "daily_breakdown": [
      {
        "date": "2024-11-01",
        "calls": 312,
        "cost_cents": 936
      },
      {
        "date": "2024-11-02",
        "calls": 287,
        "cost_cents": 861
      }
    ]
  }
}