Skip to content

Subscriptions

View your current subscription status and explore available subscription plans. Subscription plans define the available quota limits, rate limits and permission scopes for users.

Base path: /api/v1/subscription

Method Endpoint Description
GET /api/v1/subscription Get My Subscription
GET /api/v1/subscription-plans List Available Plans
GET /api/v1/subscription-plans/{slug} Get Plan by Slug

Looking for admin endpoints?

To manage plans or assign subscriptions to users, see the Admin Subscriptions API.

Get My Subscription

GET /api/v1/subscription

Requires Authentication - Scopes: subscriptions:read

Retrieve the current authenticated user's subscription details, including the plan reference and expiration dates.

curl -X GET "https://koldan.dixilang.com/api/v1/subscription" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/subscription",
    headers={"Authorization": f"Bearer {JWT}"}
)
if resp.status_code == 200:
    print(resp.json())
else:
    print("No active subscription")
UserSubscriptionResponse
Field Type Nullable Description
id string (UUID) No Unique subscription record identifier.
userUuid string (UUID) No The subscribing user's identifier.
plan SubscriptionPlanSummary No Reference to the associated subscription plan.
status SubscriptionStatus No Current subscription status.
currentPeriodStart string (ISO 8601) No Start of the current subscription period.
currentPeriodEnd string (ISO 8601) No End of the current subscription period (expiration).
canceledAt string (ISO 8601) Yes Timestamp when the subscription was canceled.
createdAt string (ISO 8601) No Timestamp when the record was created.
updatedAt string (ISO 8601) No Timestamp of the last update.
SubscriptionPlanSummary
Field Type Nullable Description
id string (UUID) No Unique plan identifier.
slug string No URL-friendly identifier.
name string No Display name of the plan.
UserSubscriptionResponse
{
  "id": "c1d2e3f4-g5h6-7i8j-9k0l-1m2n3o4p5q6r",
  "userUuid": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
  "plan": {
    "id": "a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p",
    "slug": "pro",
    "name": "Professional Plan"
  },
  "status": "ACTIVE",
  "currentPeriodStart": "2024-01-01T00:00:00Z",
  "currentPeriodEnd": "2024-02-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}
Status Description
200 OK User subscription details retrieved.
204 No Content The user does not have an active subscription.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

List Available Plans

GET /api/v1/subscription-plans

Requires Authentication - Scopes: subscriptions:plans:read

Returns all active subscription plans available to the current tenant, ordered by their display order. Use this to discover available tiers for upgrading or changing plans.

curl -X GET "https://koldan.dixilang.com/api/v1/subscription-plans" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/subscription-plans",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())
SubscriptionPlanResponse[]

Returns an array of SubscriptionPlanResponse objects. See Get Plan by Slug for the field definition.

Status Description
200 OK List of active subscription plans retrieved.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Get Plan by Slug

GET /api/v1/subscription-plans/{slug}

Requires Authentication - Scopes: subscriptions:plans:read

Returns details for a single active subscription plan identified by its unique URL-friendly slug (e.g., free, pro). This includes all associated quota limits and rate limits overrides defined by the plan.

Path Parameters
Parameter Type Required Description
slug string Yes The unique URL-friendly identifier for the plan. 
curl -X GET "https://koldan.dixilang.com/api/v1/subscription-plans/pro" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/subscription-plans/pro",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())
SubscriptionPlanResponse
Field Type Nullable Description
id string (UUID) No Unique plan identifier.
slug string No URL-friendly identifier.
name string No Display name of the plan.
active boolean No Whether new users can subscribe to this plan.
displayOrder integer No Ordering index for display purposes.
quotas QuotaLimitsResponse Yes Quota limit overrides. null fields inherit tenant defaults.
rateLimits RateLimitsResponse Yes Rate limit overrides. null fields inherit tenant defaults.
permissions string[] No Permission scopes granted by this plan.
createdAt string (ISO 8601) No Timestamp when the plan was created.
updatedAt string (ISO 8601) No Timestamp of the last update.
SubscriptionPlanResponse
{
  "id": "a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p",
  "slug": "pro",
  "name": "Professional Plan",
  "active": true,
  "displayOrder": 1,
  "quotas": {
    "speech-service": {
      "storageLimit": 10737418240,
      "monthlyTranscriptionMinutes": 6000,
      "monthlySummaries": 500,
      "monthlySummaryTokens": 5000000,
      "monthlyTranslations": 500,
      "monthlyTranslationTokens": 5000000
    },
    "text-service": {
      "monthlyTextTranslations": 10000,
      "monthlyTextTranslationTokens": 10000000
    }
  },
  "rateLimits": {
    "speech-service": {
      "fileUploads": 20,
      "transcriptionJobExecutions": 20,
      "summaryExecutions": 30,
      "translationExecutions": 30
    },
    "text-service": {
      "textTranslationExecutions": 60
    },
    "users": {
      "userLookup": 30
    },
    "globalRequests": 600
  },
  "permissions": [
    "speech:transcriptions:read",
    "speech:transcriptions:write",
    "speech:summaries:read",
    "speech:summaries:write"
  ],
  "createdAt": "2024-01-01T12:00:00Z",
  "updatedAt": "2024-01-01T12:00:00Z"
}
Status Description
200 OK Subscription plan details retrieved.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Plan not found or not active.

Enumerations

Data Models

These models are used in subscription plan definitions.

QuotaLimitsResponse

Used in Subscription Plans to define quota limit overrides.

Field Type Nullable Description
speech-service SpeechServiceQuotaLimits Yes Speech Service quota limits.
text-service TextServiceQuotaLimits Yes Text Service quota limits.

SpeechServiceQuotaLimits

Used to define the maximum values for Speech Service quotas.

Field Type Nullable Description
storageLimit long Yes Maximum storage in bytes.
monthlyTranscriptionMinutes long Yes Maximum transcription minutes per month.
monthlySummaries long Yes Maximum number of summary requests per month.
monthlySummaryTokens long Yes Maximum number of LLM tokens for summaries per month.
monthlyTranslations long Yes Maximum number of translation requests per month.
monthlyTranslationTokens long Yes Maximum number of LLM tokens for translations per month.

TextServiceQuotaLimits

Used to define the maximum values for Text Service quotas.

Field Type Nullable Description
monthlyTextTranslations long Yes Maximum number of on-demand text translation requests per month.
monthlyTextTranslationTokens long Yes Maximum number of LLM tokens for text translations per month.

SubscriptionStatus

Value Description
ACTIVE The subscription is currently active and within its period.
CANCELED The subscription has been canceled and will not renew.