Retrieve Subscription
GET/api/v1/subscription
Retrieve the caller's subscription with plan details, member groups, and aggregated usage across all groups.
Permissions
| Caller | Result |
|---|---|
Subscription owner (current_user.id == subscription.owner_user_id) | 200, full payload |
User with ADMIN role (role_id = 1) in any user_group under the subscription | 200, full payload |
| Sysadmin / syssupport | 200, full payload (typically used via /sysadmin/subscriptions/{id}) |
| Any other authenticated user | 403 |
| Unauthenticated | 401 |
Response
Plan-level fields (plan, details, status) are filtered through the public-plan whitelist and never expose internal-only fields like queue_class, enforcement_mode, or AI velocity caps. Aggregated usage is summed live across all user_usage rows in groups under this subscription; quota fields come from the plan catalog (0 = unlimited).
What's not here
Plan changes (owner, plan_code, status), and attach / detach of groups are sysadmin-only — see /sysadmin/subscriptions/* in the System Admin API. A self-serve plan-change endpoint will land alongside the payment provider integration.
Responses
- 200
- 401
- 403
- 404
- 500
Successful operation
Unauthorized - Invalid or missing authentication
Forbidden - Caller is not the owner, a group admin, or a sysadmin
Not Found - Caller has no resolvable subscription
Internal server error