Create a new entitlement

Authorization

bearerAuth write:entitlements

AuthorizationBearer <token>

A JWT verified by the proxy in front of this API, or a Kaiten access token (ksh_...) — send either as Authorization: Bearer <token>. The scopes listed on each operation are the ones the token must carry; write:<module> implies read:<module>, and read:* / write:* are wildcards over every module. x-kaiten-scopes lists every scope such a token can carry, including those enforced by a service in front of this API rather than by one of its operations.

In: header

Scope: write:entitlements

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

aggregationMethod?string

Method used to fold each reported usage value into the stored total (NUMBER only). Defaults to SUM.

Value in"COUNT" | "SUM" | "AVERAGE" | "MIN" | "MAX" | "LATEST"

description*|

Description of the entitlement

displayOrder?integer

Sort order of this entitlement in customer-facing components (ascending). Defaults to 0.

Formatint32

Range0 <= value

groupSlugs?array<>|

Groups associated with this entitlement, identified by slug

icon?string

Optional icon, stored as a provider-namespaced token (provider:name). Decoupled from any specific icon library.

Match^[a-z0-9]+:[a-z0-9]+(-[a-z0-9]+)*$

Lengthlength <= 64

name*string

Name of the entitlement

Length1 <= length

resetAnchor?string

Phase of the periodic usage window: CALENDAR (UTC calendar-aligned) or LICENSE_START (phased off the instance's license start date). Required exactly when resetPeriod is set; defaults to CALENDAR when omitted. Immutable once set.

Value in"CALENDAR" | "LICENSE_START"

resetPeriod?string

Cadence at which usage automatically resets for this NUMBER entitlement. NULL means a lifetime counter (default). Immutable once set -- a full-replace PUT must echo back the stored value.

Value in"HOUR" | "DAY" | "WEEK" | "MONTH" | "YEAR"

saleUnitFactor?number

Number of base units one sale unit represents (1 sale unit = N base units).

Formatdouble

Range0 < value

saleUnitPlural?string

Plural label of the unit this entitlement is sold in, when it differs from the base unit.

Length1 <= length <= 100

saleUnitSingular?string

Singular label of the unit this entitlement is sold in, when it differs from the base unit. Requires the base unit labels and the full sale unit trio (saleUnitSingular, saleUnitPlural, saleUnitFactor).

Length1 <= length <= 100

slug?string

Optional URL-friendly identifier, unique per organization. Auto-generated if not provided.

Match^[a-z0-9][a-z0-9-]*[a-z0-9]$

Length2 <= length <= 100

type?string

Type of the entitlement

Value in"BOOLEAN" | "NUMBER" | "CONFIG" | "NUMBER_AI_CREDIT"

unitPlural?string

Plural label of the base unit this entitlement is measured in (NUMBER type only). Must be provided together with unitSingular.

Length1 <= length <= 100

unitSingular?string

Singular label of the base unit this entitlement is measured in (NUMBER type only). Must be provided together with unitPlural.

Length1 <= length <= 100

userFacing?boolean

Whether this entitlement is displayed in customer-facing components (e.g. plan and pricing pages). Defaults to false.

warningThresholdPercent?integer

Percentage of the cap at which an early-warning event fires before the cap is reached. 0 disables the warning (default).

Formatint32

Range0 <= value <= 100

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://app.kaiten.sh/api/entitlements" \  -H "Content-Type: application/json" \  -d '{    "description": "Basic subscription plan with limited features",    "name": "Basic Plan"  }'

{
  "aggregationMethod": "SUM",
  "createdAt": "2023-10-01T12:00:00Z",
  "description": "Basic subscription plan with limited features",
  "displayOrder": 10,
  "entitlementGroups": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "AI Quotas",
      "slug": "ai-quotas"
    }
  ],
  "groupSlugs": [
    "string"
  ],
  "icon": "lucide:rocket",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Basic Plan",
  "resetAnchor": "CALENDAR",
  "resetPeriod": "MONTH",
  "saleUnitFactor": 3,
  "saleUnitPlural": "packs",
  "saleUnitSingular": "pack",
  "slug": "basic-plan",
  "type": "NUMBER",
  "unitPlural": "seats",
  "unitSingular": "seat",
  "updatedAt": "2023-10-02T12:00:00Z",
  "userFacing": true,
  "warningThresholdPercent": 80
}

{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

Create a new entitlement

Authorization

Request Body

Response Body

201application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/problem+json

500application/problem+json

503application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`