openapi.yaml

components:
  schemas:
    AuditTrail:
      additionalProperties: false
      properties:
        eventName:
          description: Event name (e.g. ENTITLEMENT_VALUE_GET)
          type: string
        eventType:
          description: Event type identifier (e.g. com.kaiten.instance.entitlement.v1.value_get)
          type: string
        id:
          description: Unique audit trail entry ID
          type: string
        instanceId:
          description: Instance UUID (present for instance-scoped events)
          type: string
        instanceSlug:
          description: Instance slug
          type: string
        payload:
          description: Event payload (JSON)
        timestamp:
          description: When the event occurred
          format: date-time
          type: string
      required:
        - id
        - instanceSlug
        - eventName
        - eventType
        - timestamp
      type: object
    Basic:
      additionalProperties: false
      properties:
        type:
          enum:
            - basic
          type: string
        value:
          type: string
      required:
        - type
        - value
      type: object
    BasicTargeting:
      additionalProperties: false
      properties:
        name:
          examples:
            - Targeting Rule 1
          type: string
        rule:
          description: CEL expression for basicTargeting evaluation
          examples:
            - user.group == 'beta'
          maxLength: 10000
          type: string
        type:
          enum:
            - basic
          type: string
        variant:
          type: string
      required:
        - type
        - name
        - variant
        - rule
      type: object
    BooleanEntitlementValue:
      additionalProperties: false
      properties:
        type:
          description: Value type discriminator
          enum:
            - boolean
          examples:
            - boolean
          type: string
        value:
          description: Boolean value
          examples:
            - true
          type: boolean
      required:
        - type
        - value
      type: object
    BulkEvaluationFailure:
      additionalProperties: false
      properties:
        errorCode:
          description: Error code specific to the bulk evaluation error
          type: string
        errorDetails:
          description: Optional error details description
          type: string
      required:
        - errorCode
      type: object
    BulkEvaluationRequest:
      additionalProperties: false
      properties:
        context:
          additionalProperties: {}
          type: object
      type: object
    Command:
      additionalProperties: false
      properties:
        entitlementSlug:
          type: string
      required:
        - entitlementSlug
      type: object
    Component:
      additionalProperties: false
      properties:
        createdAt:
          description: Timestamp when the component was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          description: User who created this component
          readOnly: true
        description:
          description: Description of the component
          examples:
            - Main API gateway component
          maxLength: 500
          type: string
        id:
          description: Unique identifier for the component
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        name:
          description: Name of the component
          examples:
            - api-gateway
          maxLength: 100
          minLength: 1
          type: string
        previousComponentId:
          description: Reference to the previous version of this component
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per organization. Auto-generated if not provided.
          examples:
            - api-gateway-v1-2-3
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        version:
          description: Version of the component
          examples:
            - v1.2.3
          maxLength: 100
          minLength: 1
          type: string
      required:
        - id
        - name
        - version
        - createdBy
        - createdAt
      type: object
    ConfigEntitlementValue:
      additionalProperties: false
      properties:
        type:
          description: Value type discriminator
          enum:
            - object
          examples:
            - object
          type: string
        value:
          additionalProperties: {}
          description: Object configuration value
          type: object
      required:
        - type
        - value
      type: object
    Connector:
      additionalProperties: false
      properties:
        created_at:
          description: Timestamp when connector was first registered
          format: date-time
          type: string
        entitlement_slug:
          description: Slug of the BOOLEAN entitlement a license must grant for an organization to activate this connector. Absent means the connector is ungated.
          examples:
            - connector-attio
          type: string
        name:
          description: Stable connector identifier
          examples:
            - kaiten.integration.crm.attio
          type: string
        settings_schema:
          additionalProperties: {}
          description: JSON schema used to validate connector settings payloads
          type: object
        updated_at:
          description: Timestamp when connector registration was last updated
          format: date-time
          type: string
        version:
          description: Registered connector version
          examples:
            - 1.0.0
          type: string
      required:
        - name
        - version
        - settings_schema
        - created_at
        - updated_at
      type: object
    ConnectorActivation:
      additionalProperties: false
      properties:
        activatedAt:
          description: When this organization first activated the connector
          format: date-time
          type: string
        connectorName:
          description: Stable connector identifier
          examples:
            - kaiten.integration.crm.attio
          type: string
      required:
        - connectorName
        - activatedAt
      type: object
    ConnectorSettings:
      additionalProperties: false
      properties:
        connector_name:
          description: Stable connector identifier
          examples:
            - kaiten.integration.crm.attio
          readOnly: true
          type: string
        settings:
          additionalProperties: {}
          description: Connector settings payload
          type: object
      required:
        - connector_name
        - settings
      type: object
    ConnectorSettingsSchema:
      additionalProperties: false
      properties:
        connector_name:
          description: Stable connector identifier
          examples:
            - kaiten.integration.crm.attio
          type: string
        schema:
          additionalProperties: {}
          description: JSON schema describing supported connector settings payload
          type: object
        version:
          description: Registered connector version
          examples:
            - 1.0.0
          type: string
      required:
        - connector_name
        - version
        - schema
      type: object
    ConnectorState:
      additionalProperties: false
      properties:
        activated:
          description: Whether this organization has turned the connector on
          type: boolean
        activatedAt:
          description: When this organization activated the connector. Absent when it has not.
          format: date-time
          type: string
        available:
          description: Whether this deployment has the connector registered
          type: boolean
        connectorName:
          description: Stable connector identifier
          examples:
            - kaiten.integration.crm.attio
          type: string
        entitled:
          description: Whether this organization's licence includes the connector. True for an ungated connector.
          type: boolean
        version:
          description: Registered connector version. Absent when the connector is not available.
          examples:
            - 1.0.0
          type: string
      required:
        - connectorName
        - available
        - entitled
        - activated
      type: object
    Customer:
      additionalProperties: false
      properties:
        createdAt:
          description: Timestamp when the customer was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          description: User who created this customer
          readOnly: true
        domain:
          description: Optional customer domain name
          examples:
            - example.tld
          pattern: ^[a-z0-9_-]+(\.[a-z0-9_-]+)+$
          type: string
        externalCustomerId:
          description: Optional identifier for the customer in an external system
          examples:
            - external-customer-id-12345
          type:
            - string
            - "null"
        id:
          description: Unique identifier for the customer
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        integrations:
          additionalProperties:
            $ref: "#/components/schemas/CustomerIntegration"
          description: Integrations grouped by adapter name
          type: object
        name:
          description: Name of the customer
          examples:
            - Awesome Customer
          minLength: 1
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per organization. Auto-generated if not provided.
          examples:
            - awesome-customer
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        updatedAt:
          description: Timestamp when the customer was last updated
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        updatedBy:
          $ref: "#/components/schemas/User"
          description: User who last updated this customer
          readOnly: true
      required:
        - id
        - name
        - createdBy
        - createdAt
        - updatedBy
        - updatedAt
      type: object
    CustomerBody:
      additionalProperties: false
      properties:
        domain:
          description: Optional customer domain name
          examples:
            - example.tld
          pattern: ^[a-z0-9_-]+(\.[a-z0-9_-]+)+$
          type: string
        error:
          description: Optional integration error message
          type: string
        integrationMetadata:
          additionalProperties: {}
          description: Adapter-specific integration metadata
          type: object
        name:
          description: Customer name
          examples:
            - Awesome Customer
          minLength: 1
          type: string
        slug:
          description: Customer slug
          examples:
            - awesome-customer
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        webUrl:
          description: Absolute http(s) link to the record in the third-party system
          examples:
            - https://app.attio.com/w/acme/record/rec_12345
          type: string
      type: object
    CustomerCreationRejected:
      additionalProperties: false
      properties:
        name:
          type: string
        reason:
          type: string
        slug:
          type: string
      required:
        - name
        - slug
        - reason
      type: object
    CustomerIntegration:
      additionalProperties: false
      properties:
        external_id:
          description: External identifier in the third-party adapter
          examples:
            - rec_12345
          type: string
        last_error:
          description: Last synchronization error message, if any
          type: string
        metadata:
          additionalProperties: {}
          description: Adapter-specific integration metadata
          type: object
        synced_at:
          description: Timestamp of the last synchronization with the adapter
          format: date-time
          readOnly: true
          type: string
        web_url:
          description: Absolute http(s) link to the record in the third-party system
          examples:
            - https://app.attio.com/w/acme/company/rec_12345
          type: string
      required:
        - external_id
        - synced_at
      type: object
    CustomerIntegrationResource:
      additionalProperties: false
      properties:
        domain:
          description: Optional customer domain name
          examples:
            - example.tld
          type: string
        error:
          description: Last synchronization error for this integration, if any
          type: string
        integrationMetadata:
          additionalProperties: {}
          description: Adapter-specific customer integration metadata
          type: object
        name:
          description: Customer name
          examples:
            - Awesome Customer
          type: string
        slug:
          description: Customer slug
          examples:
            - awesome-customer
          type: string
        webUrl:
          description: Absolute http(s) link to the record in the third-party system
          examples:
            - https://app.attio.com/w/acme/company/rec_12345
          type: string
      required:
        - integrationMetadata
        - name
        - slug
      type: object
    DefaultVariant:
      discriminator:
        mapping:
          basic: "#/components/schemas/Basic"
          rollout_date: "#/components/schemas/RolloutDate"
          rollout_percentage: "#/components/schemas/RolloutPercentage"
        propertyName: type
      oneOf:
        - $ref: "#/components/schemas/Basic"
        - $ref: "#/components/schemas/RolloutDate"
        - $ref: "#/components/schemas/RolloutPercentage"
    Deployment:
      additionalProperties: false
      properties:
        createdAt:
          description: Timestamp when the deployment was recorded
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          description: User who recorded this deployment
        deploymentZoneId:
          description: Deployment zone the release was deployed to
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        id:
          description: Unique identifier for this deployment event
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        releaseId:
          description: Release that was deployed
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
      required:
        - id
        - deploymentZoneId
        - releaseId
        - createdBy
        - createdAt
      type: object
    DeploymentZone:
      additionalProperties: false
      properties:
        createdAt:
          description: Timestamp when the deployment zone was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          description: User who created this deployment zone
          readOnly: true
        description:
          description: Description of the deployment zone
          examples:
            - "2023-10-01T12:00:00Z"
          type: string
        id:
          description: Unique identifier for the deployment zone
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        metadata:
          additionalProperties: {}
          description: Typed metadata for the deployment zone, validated against the org-scoped MetadataField schema
          examples:
            - region: eu-west-1
          type: object
        name:
          description: Name of the deployment zone
          examples:
            - AWS us-west-2
          minLength: 1
          type: string
        releaseId:
          description: Currently deployed release ID
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per organization. Auto-generated if not provided.
          examples:
            - aws-us-west-2
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        type:
          description: "Environment class of the deployment zone. Free-form: any value is stored as sent, but production, staging and development are the ones the console labels, and feature-flag targeting rules match on this field as __kaiten.deploymentZone.type."
          examples:
            - production
          type: string
        updatedAt:
          description: Timestamp when the deployment zone was last updated
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        updatedBy:
          $ref: "#/components/schemas/User"
          description: User who last updated the deployment zone
          readOnly: true
      required:
        - id
        - name
        - type
        - description
        - createdBy
        - createdAt
        - updatedBy
        - updatedAt
      type: object
    Entitlement:
      additionalProperties: false
      properties:
        aggregationMethod:
          description: Method used to fold each reported usage value into the stored total (NUMBER only). Defaults to SUM.
          enum:
            - COUNT
            - SUM
            - AVERAGE
            - MIN
            - MAX
            - LATEST
          examples:
            - SUM
          type: string
        createdAt:
          description: Timestamp when this entitlement was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        description:
          description: Description of the entitlement
          examples:
            - Basic subscription plan with limited features
          type:
            - string
            - "null"
        displayOrder:
          description: Sort order of this entitlement in customer-facing components (ascending). Defaults to 0.
          examples:
            - 10
          format: int32
          minimum: 0
          type: integer
        entitlementGroups:
          description: Groups associated with this entitlement
          items:
            $ref: "#/components/schemas/EntitlementGroupSummary"
          readOnly: true
          type:
            - array
            - "null"
        groupSlugs:
          description: Groups associated with this entitlement, identified by slug
          items:
            type: string
          type:
            - array
            - "null"
          writeOnly: true
        icon:
          description: Optional icon, stored as a provider-namespaced token (provider:name). Decoupled from any specific icon library.
          examples:
            - lucide:rocket
          maxLength: 64
          pattern: ^[a-z0-9]+:[a-z0-9]+(-[a-z0-9]+)*$
          type: string
        id:
          description: Unique identifier for the entitlement
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        name:
          description: Name of the entitlement
          examples:
            - Basic Plan
          minLength: 1
          type: string
        resetAnchor:
          description: "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."
          enum:
            - CALENDAR
            - LICENSE_START
          examples:
            - CALENDAR
          type: string
        resetPeriod:
          description: 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.
          enum:
            - HOUR
            - DAY
            - WEEK
            - MONTH
            - YEAR
          examples:
            - MONTH
          type: string
        saleUnitFactor:
          description: Number of base units one sale unit represents (1 sale unit = N base units).
          examples:
            - 3
          exclusiveMinimum: 0
          format: double
          type: number
        saleUnitPlural:
          description: Plural label of the unit this entitlement is sold in, when it differs from the base unit.
          examples:
            - packs
          maxLength: 100
          minLength: 1
          type: string
        saleUnitSingular:
          description: 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).
          examples:
            - pack
          maxLength: 100
          minLength: 1
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per organization. Auto-generated if not provided.
          examples:
            - basic-plan
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        type:
          description: Type of the entitlement
          enum:
            - BOOLEAN
            - NUMBER
            - CONFIG
            - NUMBER_AI_CREDIT
          examples:
            - NUMBER
          type: string
        unitPlural:
          description: Plural label of the base unit this entitlement is measured in (NUMBER type only). Must be provided together with unitSingular.
          examples:
            - seats
          maxLength: 100
          minLength: 1
          type: string
        unitSingular:
          description: Singular label of the base unit this entitlement is measured in (NUMBER type only). Must be provided together with unitPlural.
          examples:
            - seat
          maxLength: 100
          minLength: 1
          type: string
        updatedAt:
          description: Timestamp when this entitlement was last updated
          examples:
            - "2023-10-02T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        userFacing:
          description: Whether this entitlement is displayed in customer-facing components (e.g. plan and pricing pages). Defaults to false.
          examples:
            - true
          type: boolean
        warningThresholdPercent:
          description: Percentage of the cap at which an early-warning event fires before the cap is reached. 0 disables the warning (default).
          examples:
            - 80
          format: int32
          maximum: 100
          minimum: 0
          type: integer
      required:
        - id
        - name
        - description
        - createdAt
        - updatedAt
      type: object
    EntitlementGroup:
      additionalProperties: false
      properties:
        description:
          description: Description of the entitlement group
          examples:
            - All entitlements related to AI usage quotas
          type:
            - string
            - "null"
        id:
          description: Unique identifier for the entitlement group
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        name:
          description: Name of the entitlement group
          examples:
            - AI Quotas
          minLength: 1
          type: string
        slug:
          description: URL-friendly identifier, unique per organization. Auto-generated if not provided.
          examples:
            - ai-quotas
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
      required:
        - id
        - name
        - description
      type: object
    EntitlementGroupSummary:
      additionalProperties: false
      properties:
        id:
          description: Unique identifier for the entitlement group
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        name:
          description: Name of the entitlement group
          examples:
            - AI Quotas
          type: string
        slug:
          description: URL-friendly identifier for the entitlement group
          examples:
            - ai-quotas
          type: string
      required:
        - id
        - name
        - slug
      type: object
    EntitlementGroupUsage:
      additionalProperties: false
      properties:
        currentPeriodEnd:
          description: End of the current usage window (exclusive). Null for a lifetime entitlement.
          format: date-time
          type: string
        currentPeriodStart:
          description: Start of the current usage window (inclusive). Null for a lifetime entitlement.
          format: date-time
          type: string
        entitlementId:
          description: Entitlement ID
          type: string
        entitlementName:
          description: Entitlement name
          type: string
        entitlementSlug:
          description: Entitlement slug
          type: string
        entitlementType:
          description: Entitlement type
          type: string
        licenseValue:
          description: License limit value, discriminated by the 'type' field. Null when the license grants no value.
          discriminator:
            mapping:
              boolean: "#/components/schemas/BooleanEntitlementValue"
              number: "#/components/schemas/NumberEntitlementValue"
              object: "#/components/schemas/ConfigEntitlementValue"
            propertyName: type
          oneOf:
            - $ref: "#/components/schemas/NumberEntitlementValue"
            - $ref: "#/components/schemas/BooleanEntitlementValue"
            - $ref: "#/components/schemas/ConfigEntitlementValue"
        usageValue:
          description: Current usage value, discriminated by the 'type' field. Null when nothing has been reported yet.
          discriminator:
            mapping:
              boolean: "#/components/schemas/BooleanEntitlementValue"
              number: "#/components/schemas/NumberEntitlementValue"
              object: "#/components/schemas/ConfigEntitlementValue"
            propertyName: type
          oneOf:
            - $ref: "#/components/schemas/NumberEntitlementValue"
            - $ref: "#/components/schemas/BooleanEntitlementValue"
            - $ref: "#/components/schemas/ConfigEntitlementValue"
      required:
        - entitlementId
        - entitlementSlug
        - entitlementName
        - entitlementType
      type: object
    EntitlementUsage:
      additionalProperties: false
      properties:
        currentPeriodEnd:
          description: End of the current usage window (exclusive). Null for a lifetime entitlement (no configured reset period).
          examples:
            - "2026-04-01T00:00:00Z"
          format: date-time
          type: string
        currentPeriodStart:
          description: Start of the current usage window (inclusive). Null for a lifetime entitlement (no configured reset period).
          examples:
            - "2026-03-01T00:00:00Z"
          format: date-time
          type: string
        entitlementId:
          description: Unique identifier for the entitlement
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        entitlementSlug:
          description: URL-friendly identifier of the entitlement
          examples:
            - premium-support
          type: string
        licenseId:
          description: Unique identifier for the license to which this entitlement usage belongs
          examples:
            - 123e4567-e89b-12d3-a456-426614174001
          type: string
        licenseSlug:
          description: URL-friendly identifier of the license
          examples:
            - enterprise-license
          type: string
        limit:
          description: License grant this usage is measured against, discriminated by the 'type' field. Null when the license grants no value; -1 means unlimited for a NUMBER entitlement.
          discriminator:
            mapping:
              boolean: "#/components/schemas/BooleanEntitlementValue"
              number: "#/components/schemas/NumberEntitlementValue"
              object: "#/components/schemas/ConfigEntitlementValue"
            propertyName: type
          oneOf:
            - $ref: "#/components/schemas/NumberEntitlementValue"
            - $ref: "#/components/schemas/BooleanEntitlementValue"
            - $ref: "#/components/schemas/ConfigEntitlementValue"
        value:
          description: Resolved entitlement value, discriminated by the 'type' field
          discriminator:
            mapping:
              boolean: "#/components/schemas/BooleanEntitlementValue"
              number: "#/components/schemas/NumberEntitlementValue"
              object: "#/components/schemas/ConfigEntitlementValue"
            propertyName: type
          oneOf:
            - $ref: "#/components/schemas/NumberEntitlementValue"
            - $ref: "#/components/schemas/BooleanEntitlementValue"
            - $ref: "#/components/schemas/ConfigEntitlementValue"
      required:
        - entitlementId
        - entitlementSlug
        - licenseId
        - licenseSlug
        - value
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    EvaluationFailure:
      additionalProperties: false
      properties:
        errorCode:
          description: OpenFeature compatible error code
          type: string
        errorDetails:
          description: Error description
          type: string
        key:
          description: Feature flag key
          type: string
        metadata:
          additionalProperties: {}
          description: Arbitrary metadata for the flag
          type: object
      required:
        - key
        - errorCode
      type: object
    EvaluationRequest:
      additionalProperties: false
      properties:
        context:
          additionalProperties: {}
          type: object
      type: object
    EvaluationSuccess:
      additionalProperties: false
      properties:
        key:
          description: Feature flag key
          type: string
        metadata:
          additionalProperties: {}
          description: Arbitrary metadata for the flag
          type: object
        reason:
          description: OpenFeature reason for the evaluation
          examples:
            - STATIC
          type: string
        value:
          description: Flag evaluation result
        variant:
          description: string of the evaluated flag value
          type: string
      required:
        - key
      type: object
    FeatureFlag:
      additionalProperties: false
      properties:
        default_variant:
          $ref: "#/components/schemas/DefaultVariant"
        description:
          examples:
            - This is a new feature flag
          type:
            - string
            - "null"
        enabled:
          examples:
            - true
          type: boolean
        event_name:
          examples:
            - feature_flag_event
          type: string
        id:
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        metadata:
          additionalProperties: {}
          type: object
        name:
          examples:
            - New Feature
          minLength: 1
          type: string
        slug:
          examples:
            - new-feature
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        targetings:
          $ref: "#/components/schemas/Targetings"
        type:
          enum:
            - boolean
            - string
            - number
            - object
          examples:
            - boolean
          type: string
        variants:
          items:
            $ref: "#/components/schemas/Variant"
          type:
            - array
            - "null"
      required:
        - id
        - type
        - variants
        - targetings
        - name
        - description
        - default_variant
        - metadata
        - enabled
        - event_name
      type: object
    FeatureFlagEvaluated:
      additionalProperties: false
      properties:
        error_code:
          description: Set when the evaluation failed and the default was returned
          type: string
        error_message:
          description: Human-readable detail accompanying error_code
          type: string
        flag_id:
          description: Unique identifier of the evaluated flag
          type: string
        flag_slug:
          description: URL-friendly identifier of the evaluated flag
          type: string
        matched_rule_name:
          description: Name of the targeting rule that matched, when the reason is TARGETING_MATCH
          type: string
        reason:
          description: Why the value resolved as it did
          type: string
        variant:
          description: Name of the resolved variant, when the flag has one
          type: string
      required:
        - flag_slug
        - flag_id
        - reason
      type: object
    Impact:
      additionalProperties: false
      properties:
        count:
          description: Number of resources whose stored value for this field would no longer satisfy the candidate schema
          format: int64
          type: integer
        samples:
          description: Up to 5 impacted resources, for display
          items:
            $ref: "#/components/schemas/ImpactSample"
          type:
            - array
            - "null"
      required:
        - count
        - samples
      type: object
    ImpactSample:
      additionalProperties: false
      properties:
        name:
          description: Resource display name
          type: string
        slug:
          description: Resource slug
          type: string
      required:
        - name
        - slug
      type: object
    Instance:
      additionalProperties: false
      properties:
        createdAt:
          description: Timestamp when the instance was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          description: User who created this instance
          readOnly: true
        customerId:
          description: ID of the customer associated with this instance
          examples:
            - 123e4567-e89b-12d3-a456-426614174003
          type: string
        customerSlug:
          description: Slug of the customer associated with this instance
          examples:
            - acme-corp
          readOnly: true
          type: string
        deploymentZoneId:
          description: ID of the deployment zone associated with this instance (optional)
          examples:
            - 123e4567-e89b-12d3-a456-426614174005
          type: string
        deploymentZoneSlug:
          description: Slug of the deployment zone associated with this instance (optional)
          examples:
            - aws-us-west-2
          readOnly: true
          type: string
        description:
          description: Brief description of the instance
          examples:
            - This is a sample instance description
          type: string
        endLicenseDate:
          description: End date of the license for this instance
          examples:
            - "2024-10-01T12:00:00Z"
          format: date-time
          type: string
        id:
          description: Unique identifier for the instance
          examples:
            - 123e4567-e89b-12d3-a2456-426614174000
          readOnly: true
          type: string
        integrations:
          additionalProperties:
            $ref: "#/components/schemas/InstanceIntegration"
          description: Integrations grouped by adapter name
          type: object
        licenseId:
          description: ID of the license version this instance is pinned to. An ARCHIVED version cannot be assigned, on create or by changing the license (CreateInstance.LicenseArchived, UpdateInstance.LicenseArchived); an instance already on a version that is archived later keeps it. A DRAFT version can be assigned, to try it before publishing.
          examples:
            - 123e4567-e89b-12d3-a456-426614174004
          type: string
        licenseSlug:
          description: Slug of the license associated with this instance
          examples:
            - my-license
          readOnly: true
          type: string
        lifecycleStage:
          description: "Commercial lifecycle stage of the instance (free-form; suggested: TRIAL, ACTIVE, AT_RISK, CHURNED)"
          examples:
            - ACTIVE
          readOnly: true
          type: string
        metadata:
          additionalProperties: {}
          description: Metadata for the instance
          examples:
            - key: value
          type: object
        name:
          description: Name of the instance
          examples:
            - My Instance
          minLength: 1
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per organization. Auto-generated if not provided.
          examples:
            - my-instance
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        startLicenseDate:
          description: Start date of the license for this instance
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          type: string
        status:
          description: Operational status of the instance
          enum:
            - HEALTHY
            - DEGRADED
            - INCIDENT
            - MAINTENANCE
          examples:
            - HEALTHY
          readOnly: true
          type: string
        updatedAt:
          description: Timestamp when the instance was last updated
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        updatedBy:
          $ref: "#/components/schemas/User"
          description: User who last updated this instance
          readOnly: true
      required:
        - id
        - createdBy
        - createdAt
        - updatedBy
        - updatedAt
        - name
        - description
        - customerId
        - customerSlug
        - licenseId
        - licenseSlug
        - startLicenseDate
        - endLicenseDate
      type: object
    InstanceBody:
      additionalProperties: false
      properties:
        customerExternalId:
          description: External identifier of the related customer in the same adapter
          examples:
            - rec_customer_123
          type: string
        deploymentZoneId:
          description: Deployment zone ID
          examples:
            - 123e4567-e89b-12d3-a456-426614174005
          type: string
        description:
          description: Instance description
          examples:
            - This is a sample instance description
          type: string
        endLicenseDate:
          description: License end date
          examples:
            - "2024-10-01T12:00:00Z"
          format: date-time
          type: string
        error:
          description: Optional integration error message
          type: string
        integrationMetadata:
          additionalProperties: {}
          description: Adapter-specific integration metadata
          type: object
        licenseId:
          description: License ID
          examples:
            - 123e4567-e89b-12d3-a456-426614174004
          type: string
        metadata:
          additionalProperties: {}
          description: Instance metadata
          type: object
        name:
          description: Instance name
          examples:
            - My Instance
          minLength: 1
          type: string
        slug:
          description: Instance slug
          examples:
            - my-instance
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        startLicenseDate:
          description: License start date
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          type: string
        webUrl:
          description: Absolute http(s) link to the record in the third-party system
          examples:
            - https://app.attio.com/w/acme/record/rec_12345
          type: string
      type: object
    InstanceEntitlementCapExceeded:
      additionalProperties: false
      properties:
        entitlement_slug:
          description: URL-friendly identifier of the entitlement
          type: string
        overage:
          description: Amount by which usage exceeds the cap
          format: double
          type: number
        threshold:
          description: The entitlement cap
          format: double
          type: number
        value:
          description: Current usage value, including overage
          format: double
          type: number
      required:
        - entitlement_slug
        - threshold
        - value
        - overage
      type: object
    InstanceEntitlementUsagePeriodRolledOver:
      additionalProperties: false
      properties:
        closed_period_end:
          format: date-time
          type:
            - string
            - "null"
        closed_period_start:
          format: date-time
          type:
            - string
            - "null"
        entitlement_id:
          type: string
        entitlement_slug:
          type: string
        event_count:
          format: int32
          type: integer
        instance_id:
          type: string
        is_synthetic:
          type: boolean
        new_period_start:
          format: date-time
          type: string
        value:
          format: double
          type: number
      required:
        - entitlement_id
        - entitlement_slug
        - instance_id
        - value
        - event_count
        - closed_period_start
        - closed_period_end
        - new_period_start
        - is_synthetic
      type: object
    InstanceEntitlementUsageReportAccepted:
      additionalProperties: false
      properties:
        behavior:
          description: "Report behavior: append folds the value into the stored total, set overwrites it"
          enum:
            - append
            - set
          type: string
        entitlement_slug:
          description: URL-friendly identifier of the entitlement the usage was reported against
          type: string
        event_count:
          description: Number of reports folded into the current usage window, including this one
          format: int32
          type: integer
        status:
          description: Whether the report was persisted
          enum:
            - ACCEPTED
            - REJECTED
          type: string
        value:
          description: Value carried by the report
          format: double
          type: number
      required:
        - entitlement_slug
        - value
        - behavior
        - event_count
        - status
      type: object
    InstanceEntitlementUsageWarningThresholdReached:
      additionalProperties: false
      properties:
        boundary:
          description: Usage value at which the warning fires (cap * warningThresholdPercent / 100)
          format: double
          type: number
        entitlement_slug:
          description: URL-friendly identifier of the entitlement
          type: string
        threshold:
          description: The entitlement cap
          format: double
          type: number
        value:
          description: Current usage value
          format: double
          type: number
      required:
        - entitlement_slug
        - threshold
        - boundary
        - value
      type: object
    InstanceEntitlementValueGet:
      additionalProperties: false
      properties:
        entitlement_id:
          description: Unique identifier for the entitlement
          type: string
        entitlement_slug:
          description: URL-friendly identifier of the entitlement
          type: string
        instance_id:
          description: Unique identifier for the instance the value was read for
          type: string
        license_id:
          description: Unique identifier for the license carrying the entitlement
          type: string
        organization_id:
          description: Unique identifier for the owning organization
          type: string
        timestamp:
          description: When the value was read
          format: date-time
          type: string
        type:
          description: Discriminator of the resolved entitlement value
          examples:
            - number
          type: string
        value:
          description: Resolved entitlement value at read time
          discriminator:
            mapping:
              boolean: "#/components/schemas/BooleanEntitlementValue"
              number: "#/components/schemas/NumberEntitlementValue"
              object: "#/components/schemas/ConfigEntitlementValue"
            propertyName: type
          oneOf:
            - $ref: "#/components/schemas/NumberEntitlementValue"
            - $ref: "#/components/schemas/BooleanEntitlementValue"
            - $ref: "#/components/schemas/ConfigEntitlementValue"
      required:
        - entitlement_id
        - instance_id
        - license_id
        - organization_id
        - type
        - value
        - timestamp
        - entitlement_slug
      type: object
    InstanceIntegration:
      additionalProperties: false
      properties:
        external_id:
          description: External identifier in the third-party adapter
          examples:
            - rec_12345
          type: string
        last_error:
          description: Last synchronization error message, if any
          type: string
        metadata:
          additionalProperties: {}
          description: Adapter-specific integration metadata
          type: object
        synced_at:
          description: Timestamp of the last synchronization with the adapter
          format: date-time
          readOnly: true
          type: string
        web_url:
          description: Absolute http(s) link to the record in the third-party system
          examples:
            - https://app.attio.com/w/acme/workspace/rec_12345
          type: string
      required:
        - external_id
        - synced_at
      type: object
    InstanceIntegrationResource:
      additionalProperties: false
      properties:
        customerExternalId:
          description: External identifier of the related customer in the same adapter
          examples:
            - rec_customer_123
          type: string
        deploymentZoneId:
          description: Deployment zone ID
          examples:
            - 123e4567-e89b-12d3-a456-426614174005
          type: string
        description:
          description: Instance description
          examples:
            - This is a sample instance description
          type: string
        endLicenseDate:
          description: License end date
          examples:
            - "2024-10-01T12:00:00Z"
          format: date-time
          type: string
        error:
          description: Last synchronization error for this integration, if any
          type: string
        integrationMetadata:
          additionalProperties: {}
          description: Adapter-specific instance integration metadata
          type: object
        licenseId:
          description: License ID
          examples:
            - 123e4567-e89b-12d3-a456-426614174004
          type: string
        name:
          description: Instance name
          examples:
            - My Instance
          type: string
        slug:
          description: Instance slug
          examples:
            - my-instance
          type: string
        startLicenseDate:
          description: License start date
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          type: string
        webUrl:
          description: Absolute http(s) link to the record in the third-party system
          examples:
            - https://app.attio.com/w/acme/workspace/rec_12345
          type: string
      required:
        - description
        - endLicenseDate
        - licenseId
        - integrationMetadata
        - name
        - slug
        - startLicenseDate
      type: object
    InstanceLifecycleStageChanged:
      additionalProperties: false
      properties:
        changed_by:
          format: uuid
          type: string
        instance_id:
          format: uuid
          type: string
        new_lifecycle_stage:
          type:
            - string
            - "null"
        previous_lifecycle_stage:
          type:
            - string
            - "null"
      required:
        - instance_id
        - previous_lifecycle_stage
        - new_lifecycle_stage
        - changed_by
      type: object
    InstanceStatusChanged:
      additionalProperties: false
      properties:
        changed_by:
          format: uuid
          type: string
        instance_id:
          format: uuid
          type: string
        new_status:
          enum:
            - HEALTHY
            - DEGRADED
            - INCIDENT
            - MAINTENANCE
          type: string
        previous_status:
          enum:
            - HEALTHY
            - DEGRADED
            - INCIDENT
            - MAINTENANCE
          type: string
      required:
        - instance_id
        - previous_status
        - new_status
        - changed_by
      type: object
    License:
      additionalProperties: false
      properties:
        createdAt:
          description: Timestamp when this license was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        description:
          description: Detailed description of the license capabilities and restrictions
          examples:
            - This license provides access to all enterprise features including advanced analytics, priority support, and unlimited users.
          maxLength: 500
          type: string
        familyId:
          description: "Identifier of the license family this license is a version of. Stable across renames and new versions: two licenses sharing it are the same product. Always present in responses. On create, optional: names the family this license is a new version of, as familySlug does by slug; omit both to create a new family. On update, optional and must be the license's own family: a version cannot move between families (UpdateLicense.FamilyNotReassignable)."
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        familySlug:
          description: "Write-only on create: slug of the family this license is a new version of. familyId names the same family by identifier; sent together they must agree. Omit both to create a new family, of which this license becomes version 1. Never returned -- see familyId. Refused on update: a version cannot move between families."
          examples:
            - enterprise-license
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
          writeOnly: true
        id:
          description: Unique identifier for the license
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        isDefault:
          description: "Whether this version is the one its family puts forward: at most one version per family, and only a PUBLISHED one (CreateLicense.DefaultMustBePublished, UpdateLicense.DefaultMustBePublished). Resolution hands it out ahead of the highest-numbered published version, so it keeps being served when a newer version is published. Setting it takes the flag from the family's previous default, which gets a LICENSE_UPDATED event of its own. On update, sending false unsets it; the default cannot be archived until another version takes its place or the flag is unset (ArchiveLicense.DefaultMustBePublished)."
          examples:
            - false
          type: boolean
        lifecycleState:
          description: Whether this version may be served. Always present in responses. Optional on create, where it is DRAFT or PUBLISHED and PUBLISHED when omitted; ARCHIVED is refused (CreateLicense.LifecycleStateNotSettable), since a version is archived by withdrawing it from sale. After that it changes only through publish-license (DRAFT to PUBLISHED), archive-license (PUBLISHED to ARCHIVED) and unarchive-license (ARCHIVED to PUBLISHED); update accepts the stored state and refuses any other (UpdateLicense.LifecycleStateNotSettable). Only a PUBLISHED version can be the family's default. An ARCHIVED version cannot be assigned to an instance (CreateInstance.LicenseArchived, UpdateInstance.LicenseArchived); instances already on it keep it.
          enum:
            - DRAFT
            - PUBLISHED
            - ARCHIVED
          examples:
            - PUBLISHED
          type: string
        name:
          description: Display name of the license
          examples:
            - Enterprise License
          maxLength: 100
          minLength: 1
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per organization. When omitted, a new version of an existing family takes {familySlug}-v{version}, and any other license gets one generated from its name. A license that opens a new family gives the family its slug.
          examples:
            - enterprise-license
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        type:
          description: Type of the license determining its capabilities and restrictions
          enum:
            - DEVELOPMENT
            - TRIAL
            - PAID
            - COMMUNITY
          examples:
            - paid
          type: string
        updatedAt:
          description: Timestamp when this license was last updated
          examples:
            - "2023-10-02T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        version:
          description: "Version of the license within its family, assigned by the server when the version is created and never changed afterwards: the version's derived slug ({familySlug}-v{version}, see slug) is built from it. A number is never reused within a family, even after its version is deleted. Create refuses any value (CreateLicense.VersionNotSettable); update accepts only the stored one, so a representation can be written back as it was read (UpdateLicense.VersionNotSettable)."
          examples:
            - "1"
          readOnly: true
          type: string
        versionName:
          description: Optional human-readable name for the license version. Defaults to "Version - <version>".
          examples:
            - Winter 2024 Release
          maxLength: 50
          type: string
      required:
        - id
        - name
        - description
        - type
        - version
        - isDefault
        - createdAt
        - updatedAt
      type: object
    LicenseEntitlement:
      additionalProperties: false
      properties:
        createdAt:
          description: Timestamp when this entitlement was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          description: User who created this entitlement
          readOnly: true
        entitlementGroups:
          description: Groups associated with this entitlement
          items:
            $ref: "#/components/schemas/EntitlementGroupSummary"
          readOnly: true
          type:
            - array
            - "null"
        entitlementName:
          description: Name of the entitlement feature or service
          examples:
            - Premium Support
          readOnly: true
          type: string
        entitlementSlug:
          description: URL-friendly identifier for the entitlement
          examples:
            - premium-support
          format: string
          type: string
        entitlementType:
          description: Type of entitlement (BOOLEAN, NUMBER, or CONFIG)
          enum:
            - BOOLEAN
            - NUMBER
            - CONFIG
          examples:
            - NUMBER
          readOnly: true
          type: string
        licenseId:
          description: Unique identifier for the license this entitlement belongs to
          examples:
            - a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6
          readOnly: true
          type: string
        licenseSlug:
          description: URL-friendly identifier for the license this entitlement belongs to
          examples:
            - enterprise-license
          readOnly: true
          type: string
        limitCapExceededOveragePercent:
          description: "Derives this grant's enforcement from its own numeric value: -1 when the value is unlimited (no cap, no overage); otherwise 0 rejects usage above the value (hard limit) and a positive percentage allows usage to exceed it by that much before being rejected (soft limit). Null for non-numeric (BOOLEAN/CONFIG) grants."
          examples:
            - 10
          format: int32
          type: integer
        updatedAt:
          description: Timestamp when this entitlement was last updated
          examples:
            - "2023-10-02T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        updatedBy:
          $ref: "#/components/schemas/User"
          description: User who last updated this entitlement
          readOnly: true
        value:
          description: "Typed entitlement value. Supported shapes: {type:number,value:number}, {type:boolean,value:boolean}, {type:object,value:{...}}"
          discriminator:
            mapping:
              boolean: "#/components/schemas/BooleanEntitlementValue"
              number: "#/components/schemas/NumberEntitlementValue"
              object: "#/components/schemas/ConfigEntitlementValue"
            propertyName: type
          oneOf:
            - $ref: "#/components/schemas/NumberEntitlementValue"
            - $ref: "#/components/schemas/BooleanEntitlementValue"
            - $ref: "#/components/schemas/ConfigEntitlementValue"
      required:
        - entitlementName
        - licenseId
        - licenseSlug
        - createdBy
        - createdAt
        - updatedBy
        - updatedAt
        - value
      type: object
    LicenseFamilyView:
      additionalProperties: false
      properties:
        createdAt:
          description: Timestamp when this family was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        currentVersion:
          $ref: "#/components/schemas/License"
          description: "The version this read is about. By default the version the family resolves to: its default version if it has one, otherwise its highest-numbered PUBLISHED version. Under ?version=N it is the version asked for instead, whatever its lifecycle state. Absent when the family has no PUBLISHED version, which only a list or an include=versions read returns."
        id:
          description: Unique identifier for the license family
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        slug:
          description: URL-friendly identifier of the family, unique per organization and stable across renames and new versions. Deleting the family's last version deletes the family and frees the slug.
          examples:
            - enterprise-license
          type: string
        updatedAt:
          description: Timestamp when a version was last added to this family, or when the family was created. Renames, lifecycle moves and default changes update the versions' own updatedAt, not this one.
          examples:
            - "2023-10-02T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        versionCount:
          description: Number of versions in this family, whatever their lifecycle state
          examples:
            - 3
          format: int32
          type: integer
        versions:
          description: "Every version of the family, oldest first. Only returned when explicitly requested with include=versions, and then never null: a family always has at least one version."
          items:
            $ref: "#/components/schemas/License"
          type: array
      required:
        - id
        - slug
        - versionCount
        - createdAt
        - updatedAt
      type: object
    List:
      additionalProperties: false
      properties:
        data:
          description: The page, newest first
          items:
            $ref: "#/components/schemas/Notification"
          type: array
        nextCursor:
          description: Opaque cursor for the next page; null on the last page
          type:
            - string
            - "null"
        unreadCount:
          description: Unread notifications, capped (see MaxUnreadCount)
          format: int64
          type: integer
      required:
        - data
        - nextCursor
        - unreadCount
      type: object
    ManifestEnvelope:
      additionalProperties: false
      properties:
        flags:
          items:
            $ref: "#/components/schemas/ManifestFlag"
          type:
            - array
            - "null"
      required:
        - flags
      type: object
    ManifestFlag:
      additionalProperties: false
      properties:
        defaultValue: {}
        description:
          type: string
        key:
          type: string
        name:
          type: string
        type:
          type: string
      required:
        - key
        - type
        - defaultValue
      type: object
    MarkReadResult:
      additionalProperties: false
      properties:
        unreadCount:
          description: Unread notifications after the change
          format: int64
          type: integer
        updated:
          description: Notifications newly marked read
          format: int64
          type: integer
      required:
        - updated
        - unreadCount
      type: object
    MetadataField:
      additionalProperties: false
      properties:
        archivedAt:
          description: Timestamp when the field was archived (soft delete). Absent if active.
          format: date-time
          readOnly: true
          type: string
        createdAt:
          description: Timestamp when the field was created
          examples:
            - "2026-05-26T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          description: User who created this field
          readOnly: true
        displayOrder:
          description: Sort order in the admin UI; ties are broken by createdAt ASC. Settable only through POST /metadata-fields/reorder; never echoed back on update.
          examples:
            - 0
          format: int32
          type: integer
        id:
          description: Unique identifier
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        jsonSchema:
          additionalProperties: {}
          description: "JSON Schema 2020-12 document describing the value space. Example: {\"type\":\"string\",\"enum\":[\"a\",\"b\"]}"
          type: object
        key:
          description: Stable identifier, unique per (organization, resource type) on non-archived rows. Immutable after creation; update must echo back the stored value.
          examples:
            - region
          maxLength: 100
          minLength: 1
          type: string
        label:
          description: Human-readable label shown in the admin UI
          examples:
            - Region
          maxLength: 100
          minLength: 1
          type: string
        resourceType:
          description: Resource type this field applies to. Immutable after creation; update must echo back the stored value.
          enum:
            - DEPLOYMENT_ZONE
            - INSTANCE
          type: string
        updatedAt:
          description: Timestamp when the field was last updated
          examples:
            - "2026-05-26T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        updatedBy:
          $ref: "#/components/schemas/User"
          description: User who last updated this field
          readOnly: true
      required:
        - id
        - resourceType
        - key
        - label
        - jsonSchema
        - createdBy
        - createdAt
        - updatedBy
        - updatedAt
      type: object
    MetadataFieldReordered:
      additionalProperties: false
      properties:
        ids:
          description: Metadata field ids in their new display order
          items:
            type: string
          type:
            - array
            - "null"
      required:
        - ids
      type: object
    MetadataFieldSchemaProposal:
      additionalProperties: false
      properties:
        jsonSchema:
          additionalProperties: {}
          description: Candidate JSON Schema 2020-12 document to evaluate existing values against.
          type: object
      required:
        - jsonSchema
      type: object
    Notification:
      additionalProperties: false
      properties:
        actionUrl:
          description: Where clicking the notification goes
          type: string
        body:
          description: Rendered detail line, when the event has one
          type: string
        createdAt:
          description: When the event occurred
          format: date-time
          type: string
        eventName:
          description: Event this notification reports
          examples:
            - INSTANCE_DEPLOYED
          type: string
        eventType:
          description: CloudEvents type of the same event -- the key it is published under in this document's webhooks section, so a client can line a notification up with the payload schema and the description already published there
          examples:
            - com.kaiten.instance.v1.deployed
          type: string
        id:
          description: Identifier of the underlying audit trail entry
          type: string
        objectType:
          description: What the notification is about -- the kind of page actionUrl opens, and what the list's objectType filter matches
          examples:
            - instance
          type: string
        readAt:
          description: When this user read it; absent means unread
          format: date-time
          type: string
        title:
          description: Rendered headline
          type: string
      required:
        - id
        - eventName
        - eventType
        - objectType
        - title
        - createdAt
      type: object
    NumberEntitlementValue:
      additionalProperties: false
      properties:
        event_count:
          description: Number of events accumulated (server-computed)
          examples:
            - 2
          format: int32
          readOnly: true
          type: integer
        type:
          description: Value type discriminator
          enum:
            - number
          examples:
            - number
          type: string
        value:
          description: Numeric value
          examples:
            - 42.5
          format: double
          type: number
      required:
        - type
        - value
      type: object
    PageAuditTrail:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/AuditTrail"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageComponent:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/Component"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageCustomer:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/Customer"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageDeploymentZone:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/DeploymentZone"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageEntitlement:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/Entitlement"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageEntitlementGroup:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/EntitlementGroup"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageFeatureFlag:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/FeatureFlag"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageInstance:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/Instance"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageLicense:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/License"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageLicenseEntitlement:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/LicenseEntitlement"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageLicenseFamilyView:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/LicenseFamilyView"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageMetadataField:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/MetadataField"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageRelease:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/Release"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageServiceAccount:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/ServiceAccount"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PageToken:
      additionalProperties: false
      properties:
        hasMore:
          description: Whether more rows exist beyond this page.
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/Token"
          type: array
        nextCursor:
          description: Opaque cursor for the next page. Absent when hasMore is false.
          type: string
      required:
        - items
        - hasMore
      type: object
    PatchInstanceBody:
      additionalProperties: false
      properties:
        lifecycleStage:
          description: "Commercial lifecycle stage (free-form; suggested: TRIAL, ACTIVE, AT_RISK, CHURNED). When omitted, the current stage is preserved; clearing it back to unset is not supported."
          examples:
            - AT_RISK
          minLength: 1
          type: string
        status:
          description: Operational status of the instance
          enum:
            - HEALTHY
            - DEGRADED
            - INCIDENT
            - MAINTENANCE
          examples:
            - INCIDENT
          type: string
      type: object
    PlainToken:
      additionalProperties: false
      properties:
        createdAt:
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        expiresAt:
          format: date-time
          type: string
        id:
          readOnly: true
          type: string
        name:
          type: string
        revokedAt:
          format: date-time
          readOnly: true
          type: string
        revokedBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        scopes:
          items:
            type: string
          type:
            - array
            - "null"
        serviceAccountId:
          readOnly: true
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per service account. Auto-generated if not provided.
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        token:
          readOnly: true
          type: string
      required:
        - name
        - scopes
        - createdAt
        - createdBy
      type: object
    PreferenceChoices:
      additionalProperties: false
      properties:
        events:
          description: Events to set; events left out keep their current value
          items:
            $ref: "#/components/schemas/PreferenceUpdate"
          type:
            - array
            - "null"
      required:
        - events
      type: object
    PreferenceEvent:
      additionalProperties: false
      properties:
        channels:
          additionalProperties:
            type: boolean
          description: Effective value per channel
          type: object
        eventName:
          examples:
            - INSTANCE_DEPLOYED
          type: string
        eventType:
          description: CloudEvents type of the same event; see Notification.eventType
          examples:
            - com.kaiten.instance.v1.deployed
          type: string
        group:
          description: Catalogue group the client renders this under
          examples:
            - deployments
          type: string
        label:
          description: Human-readable event name
          type: string
      required:
        - eventName
        - eventType
        - label
        - group
        - channels
      type: object
    PreferenceMatrix:
      additionalProperties: false
      properties:
        channels:
          description: Channels this deployment serves, in display order
          items:
            type: string
          type: array
        events:
          description: Every notifiable event
          items:
            $ref: "#/components/schemas/PreferenceEvent"
          type: array
      required:
        - channels
        - events
      type: object
    PreferenceUpdate:
      additionalProperties: false
      properties:
        channels:
          additionalProperties:
            type: boolean
          type: object
        eventName:
          type: string
      required:
        - eventName
        - channels
      type: object
    Problem:
      additionalProperties: false
      properties:
        code:
          description: Stable, machine-readable error code.
          examples:
            - License.NotFound
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
            - license not found
          type: string
        errorId:
          description: Correlation id for the server-side log entry describing the withheld cause.
          examples:
            - 3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: "#/components/schemas/ErrorDetail"
          type:
            - array
            - "null"
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
            - /api/licenses/enterprise
          type: string
        status:
          description: HTTP status code
          examples:
            - 404
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
            - Not Found
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://tools.ietf.org/html/rfc7231#section-6.5.4
          format: uri
          type: string
      type: object
    ReadSelection:
      additionalProperties: false
      properties:
        all:
          description: Mark every notification read, up to now
          type: boolean
        ids:
          description: Notifications to mark read
          items:
            type: string
          maxItems: 200
          type:
            - array
            - "null"
      type: object
    Release:
      additionalProperties: false
      properties:
        componentIds:
          description: List of component IDs to link to this release
          examples:
            - - 123e4567-e89b-12d3-a456-426614174000
          items:
            type: string
          type:
            - array
            - "null"
          writeOnly: true
        components:
          description: List of components included in this release, fixed at creation
          items:
            $ref: "#/components/schemas/Component"
          readOnly: true
          type:
            - array
            - "null"
        createdAt:
          description: Timestamp when the release was created
          examples:
            - "2023-10-01T12:00:00Z"
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          description: User who created this release
          readOnly: true
        description:
          description: Description of the release
          examples:
            - "This release fixes everything. CHANGELOG: stuff was done"
          maxLength: 500
          type: string
        id:
          description: Unique identifier for the release
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          readOnly: true
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per organization. Auto-generated if not provided.
          examples:
            - v1-0-0
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        version:
          description: Version of the release
          examples:
            - v1.0.0
          maxLength: 100
          minLength: 1
          type: string
      required:
        - id
        - version
        - createdBy
        - createdAt
      type: object
    ReorderMetadataFieldsInput:
      additionalProperties: false
      properties:
        ids:
          items:
            type: string
          type:
            - array
            - "null"
      required:
        - ids
      type: object
    ReportEntitlementUsageBody:
      additionalProperties: false
      properties:
        behavior:
          description: "Report behavior: append folds the value into the stored total through the aggregation method; set overwrites it"
          enum:
            - append
            - set
          type: string
        metadata:
          additionalProperties: {}
          description: Optional metadata for the usage report
          type: object
        value:
          description: Reported entitlement value, discriminated by the 'type' field. Usage reporting accepts the number variant only.
          discriminator:
            mapping:
              boolean: "#/components/schemas/BooleanEntitlementValue"
              number: "#/components/schemas/NumberEntitlementValue"
              object: "#/components/schemas/ConfigEntitlementValue"
            propertyName: type
          oneOf:
            - $ref: "#/components/schemas/NumberEntitlementValue"
            - $ref: "#/components/schemas/BooleanEntitlementValue"
            - $ref: "#/components/schemas/ConfigEntitlementValue"
      required:
        - value
      type: object
    RolloutDate:
      additionalProperties: false
      properties:
        end:
          $ref: "#/components/schemas/RolloutStep"
        start:
          $ref: "#/components/schemas/RolloutStep"
        type:
          enum:
            - rollout_date
          type: string
      required:
        - type
        - start
        - end
      type: object
    RolloutDateTargeting:
      additionalProperties: false
      properties:
        end:
          $ref: "#/components/schemas/RolloutStep"
          examples:
            - date: "2024-01-31T23:59:59Z"
              percentage: 100
              variant: variant_a
        name:
          examples:
            - Targeting Rule 1
          type: string
        rule:
          description: CEL expression for basicTargeting evaluation
          examples:
            - user.group == 'beta'
          maxLength: 10000
          type: string
        start:
          $ref: "#/components/schemas/RolloutStep"
          examples:
            - date: "2024-01-01T00:00:00Z"
              percentage: 0
              variant: variant_a
        type:
          enum:
            - rollout_date
          type: string
      required:
        - type
        - name
        - rule
        - start
        - end
      type: object
    RolloutPercentage:
      additionalProperties: false
      properties:
        distribution:
          additionalProperties:
            format: int64
            type: integer
          type: object
        type:
          enum:
            - rollout_percentage
          type: string
      required:
        - type
        - distribution
      type: object
    RolloutPercentageTargeting:
      additionalProperties: false
      properties:
        distribution:
          additionalProperties:
            format: int64
            type: integer
          examples:
            - variant_a: 70
              variant_b: 30
          type: object
        name:
          examples:
            - Targeting Rule 1234
          type: string
        rule:
          description: CEL expression for basicTargeting evaluation
          examples:
            - user.group == 'beta'
          maxLength: 10000
          type: string
        type:
          enum:
            - rollout_percentage
          type: string
      required:
        - type
        - name
        - rule
        - distribution
      type: object
    RolloutStep:
      additionalProperties: false
      properties:
        date:
          examples:
            - "2024-01-15T10:00:00Z"
          format: date-time
          type: string
        percentage:
          examples:
            - 50
          format: int64
          type: integer
        variant:
          examples:
            - variant_b
          type: string
      required:
        - variant
        - percentage
        - date
      type: object
    ServiceAccount:
      additionalProperties: false
      properties:
        createdAt:
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        externalId:
          readOnly: true
          type: string
        id:
          readOnly: true
          type: string
        name:
          minLength: 1
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per organization. Auto-generated if not provided.
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        tokens:
          items:
            $ref: "#/components/schemas/Token"
          readOnly: true
          type:
            - array
            - "null"
      required:
        - name
        - tokens
      type: object
    SystemTokenIssuance:
      additionalProperties: false
      properties:
        credentialKind:
          description: Credential class that performed the mint; "platform" is the system:kaiten identity
          examples:
            - platform
          type: string
        expiresAt:
          description: Absent when the minted credential does not expire
          format: date-time
          type: string
        issuedAt:
          description: When the credential was minted
          format: date-time
          type: string
        issuedTokenId:
          description: The credential that was minted
          type: string
        name:
          description: Human-readable label the caller gave the minted credential
          examples:
            - ci-deploy
          type: string
        platformTokenId:
          description: Platform credential that performed the mint; revoking it revokes everything it issued
          type: string
        scopes:
          description: Scopes granted to the minted credential
          examples:
            - - read:customers
          items:
            type: string
          type:
            - array
            - "null"
        slug:
          description: Server-assigned identifier of the minted credential
          examples:
            - system-kaiten-9f2c1a
          type: string
      required:
        - credentialKind
        - platformTokenId
        - issuedTokenId
        - name
        - slug
        - scopes
        - issuedAt
      type: object
    TargetingContext:
      additionalProperties: false
      properties:
        roots:
          description: "Identifiers the server guarantees, and what is reachable below each. Not a closed set: a host may target on its own attributes too"
          items:
            $ref: "#/components/schemas/TargetingContextNode"
          type: array
      required:
        - roots
      type: object
    TargetingContextNode:
      additionalProperties: false
      properties:
        description:
          description: What this value means, shown by the editor
          type: string
        fields:
          description: Named children, for an object
          items:
            $ref: "#/components/schemas/TargetingContextNode"
          type: array
        knownKeys:
          description: Keys this map currently has, for completion. Not a closed set
          items:
            type: string
          type: array
        name:
          description: Name as it is written in a rule
          type: string
        optional:
          description: Whether this value may be absent, in which case has() is worth using
          type: boolean
        type:
          description: Shape of this node's value
          enum:
            - string
            - number
            - boolean
            - object
            - map
            - dyn
          type: string
        values:
          $ref: "#/components/schemas/TargetingContextNode"
          description: Shape shared by every entry, for a map
      required:
        - name
        - type
      type: object
    TargetingRuleDraft:
      additionalProperties: false
      properties:
        rule:
          description: The CEL targeting rule to check. May be blank, which is itself a mistake this reports
          examples:
            - __kaiten.license.familySlug == 'scale'
          maxLength: 10000
          type: string
      required:
        - rule
      type: object
    TargetingRuleIssue:
      additionalProperties: false
      properties:
        column:
          description: 1-based column the problem starts on, or 0 when it has no position
          format: int64
          type: integer
        endColumn:
          description: 1-based column just past the problem, or 0 when only a point is known
          format: int64
          type: integer
        endLine:
          description: 1-based line the problem ends on, or 0 when only a point is known
          format: int64
          type: integer
        line:
          description: 1-based line the problem starts on, or 0 when it has no position
          format: int64
          type: integer
        message:
          description: What is wrong, in the same words the write path refuses it with
          type: string
      required:
        - message
        - line
        - column
      type: object
    TargetingRuleRehearsal:
      additionalProperties: false
      properties:
        evaluationError:
          description: Why the engine could not answer, when it could not — e.g. the rule reads a host attribute this context does not carry. At a real evaluation the rule would simply not match
          type: string
        facts:
          additionalProperties: {}
          description: The __kaiten namespace as enriched for this context — what a rule actually reads. Empty sub-roots mean the context resolved nothing for them
          type: object
        issues:
          description: Problems the lint found. The rule is only run when there are none
          items:
            $ref: "#/components/schemas/TargetingRuleIssue"
          type: array
        matched:
          description: Whether the rule matched this context. Meaningful only when valid and evaluationError is empty
          type: boolean
        valid:
          description: Whether the rule lints clean
          type: boolean
      required:
        - facts
        - issues
        - valid
        - matched
      type: object
    TargetingRuleTrial:
      additionalProperties: false
      properties:
        context:
          additionalProperties: {}
          description: The evaluation context to rehearse against, as a client would send it. Anything under __kaiten is discarded, exactly as at a real evaluation
          type: object
        rule:
          description: The CEL targeting rule to rehearse
          examples:
            - __kaiten.license.familySlug == 'scale'
          maxLength: 10000
          type: string
        targetingKey:
          description: The key the evaluation would be bucketed on. Resolves license and entitlement facts when it names a customer slug
          type: string
      required:
        - rule
      type: object
    TargetingRuleVerdict:
      additionalProperties: false
      properties:
        issues:
          description: Every problem found, positioned where it is written. Empty when the rule is accepted
          items:
            $ref: "#/components/schemas/TargetingRuleIssue"
          type: array
        valid:
          description: Whether the write path would accept this rule
          type: boolean
      required:
        - issues
        - valid
      type: object
    Targetings:
      description: Polymorphic list of targeting rules (Basic, RolloutDate, RolloutPercentage)
      items:
        anyOf:
          - $ref: "#/components/schemas/BasicTargeting"
          - $ref: "#/components/schemas/RolloutDateTargeting"
          - $ref: "#/components/schemas/RolloutPercentageTargeting"
      type:
        - array
        - "null"
    Token:
      additionalProperties: false
      properties:
        createdAt:
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        expiresAt:
          format: date-time
          type: string
        id:
          readOnly: true
          type: string
        name:
          type: string
        revokedAt:
          format: date-time
          readOnly: true
          type: string
        revokedBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        scopes:
          items:
            type: string
          type:
            - array
            - "null"
        serviceAccountId:
          readOnly: true
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per service account. Auto-generated if not provided.
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
      required:
        - name
        - scopes
        - createdAt
        - createdBy
      type: object
    User:
      additionalProperties: false
      properties:
        id:
          description: ID of the user
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        name:
          description: Name of the user
          examples:
            - John Doe
          type: string
      required:
        - id
      type: object
    Variant:
      additionalProperties: false
      properties:
        description:
          type: string
        name:
          type: string
        value: {}
      required:
        - name
        - description
        - value
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: "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."
      scheme: bearer
      type: http
      x-kaiten-scopes:
        - read:components
        - read:customers
        - read:deployment_zones
        - read:entitlements
        - read:feature_flags
        - read:instances
        - read:licenses
        - read:metadata_fields
        - read:notifications
        - read:organizations
        - read:releases
        - read:tokens
        - read:webhooks
        - write:components
        - write:customers
        - write:deployment_zones
        - write:entitlements
        - write:feature_flags
        - write:instances
        - write:licenses
        - write:metadata_fields
        - write:notifications
        - write:organizations
        - write:releases
        - write:tokens
        - write:webhooks
info:
  contact:
    email: support@kaiten.sh
    name: Kaiten Team
  description: A RESTFul API for managing Kaiten features.
  title: Kaiten API
  version: 1.0.0
openapi: 3.1.0
paths:
  /components:
    get:
      description: Returns a cursor-paginated page of components for the current organization.
      operationId: list-components
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageComponent"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:components
      summary: List components
      tags:
        - components
    post:
      description: Create a new standalone component. Optionally derive it from a previous component version.
      operationId: create-component
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Component"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Component"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:components
      summary: Create a new component
      tags:
        - components
  /components/{componentSlug}:
    delete:
      description: Delete a component by slug if it is not linked to any release.
      operationId: delete-component
      parameters:
        - description: Component slug
          in: path
          name: componentSlug
          required: true
          schema:
            description: Component slug
            examples:
              - api-gateway-v1-2-3
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:components
      summary: Delete a component
      tags:
        - components
    get:
      description: Returns a single component by its slug.
      operationId: get-component
      parameters:
        - description: Component slug
          in: path
          name: componentSlug
          required: true
          schema:
            description: Component slug
            examples:
              - api-gateway-v1-2-3
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Component"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:components
      summary: Get a component by slug
      tags:
        - components
    put:
      description: Update a component in place when unlinked, or create a new version when it is already linked to releases.
      operationId: update-component
      parameters:
        - description: Component slug
          in: path
          name: componentSlug
          required: true
          schema:
            description: Component slug
            examples:
              - api-gateway-v1-2-3
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Component"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Component"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:components
      summary: Update a component
      tags:
        - components
  /connectors:
    get:
      description: Returns every registered connector with its version and settings schema, ordered by name. The registry is platform-wide rather than per-organization and holds one row per connector, so the response is not paginated.
      operationId: list-connectors
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/Connector"
                type:
                  - array
                  - "null"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:organizations
      summary: List registered connectors
      tags:
        - connectors
  /connectors/{connectorName}:
    get:
      description: Retrieves a registered connector resource including version and settings schema
      operationId: get-connector
      parameters:
        - description: Stable connector name
          in: path
          name: connectorName
          required: true
          schema:
            description: Stable connector name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connector"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:organizations
      summary: Get connector registration
      tags:
        - connectors
  /connectors/{connectorName}/activation:
    delete:
      description: "Deactivates a connector for the authenticated organization. Idempotent, and never refused for an unregistered or unlicensed connector: an organization must always be able to stop using something."
      operationId: deactivate-connector
      parameters:
        - description: Stable connector name
          in: path
          name: connectorName
          required: true
          schema:
            description: Stable connector name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:organizations
      summary: Deactivate connector
      tags:
        - connectors
    put:
      description: "Activates a registered connector for the authenticated organization. Idempotent: activating an already-active connector succeeds without changing when it was first activated. Refused when the organization's licence does not include the connector."
      operationId: activate-connector
      parameters:
        - description: Stable connector name
          in: path
          name: connectorName
          required: true
          schema:
            description: Stable connector name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectorActivation"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:organizations
      summary: Activate connector
      tags:
        - connectors
  /connectors/{connectorName}/settings:
    delete:
      description: Delete connector settings for the authenticated organization
      operationId: delete-connector-settings
      parameters:
        - description: Stable connector name
          in: path
          name: connectorName
          required: true
          schema:
            description: Stable connector name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:organizations
      summary: Delete connector settings
      tags:
        - connectors
    get:
      description: Get settings for a connector scoped to the authenticated organization. Write-only fields (flagged `writeOnly` in the connector settings schema) are returned redacted as `***`.
      operationId: get-connector-settings
      parameters:
        - description: Stable connector name
          in: path
          name: connectorName
          required: true
          schema:
            description: Stable connector name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectorSettings"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:organizations
      summary: Get connector settings
      tags:
        - connectors
    put:
      description: Create or update connector settings for the authenticated organization. Write-only fields (flagged `writeOnly` in the connector settings schema) may be omitted or sent as `***` to keep the stored value; they are returned redacted.
      operationId: update-connector-settings
      parameters:
        - description: Stable connector name
          in: path
          name: connectorName
          required: true
          schema:
            description: Stable connector name
            examples:
              - kaiten.integration.crm.attio
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConnectorSettings"
              description: Connector settings payload to upsert
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectorSettings"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:organizations
      summary: Upsert connector settings
      tags:
        - connectors
  /connectors/{connectorName}/settings/schema:
    get:
      description: Get the JSON schema used to validate connector settings payloads
      operationId: get-connector-settings-schema
      parameters:
        - description: Stable connector name
          in: path
          name: connectorName
          required: true
          schema:
            description: Stable connector name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectorSettingsSchema"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:organizations
      summary: Get connector settings schema
      tags:
        - connectors
  /connectors/{connectorName}/state:
    get:
      description: "Returns whether the connector is registered in this deployment, whether the authenticated organization's licence includes it, and whether the organization has activated it. Answers 200 with `available: false` for a connector this deployment does not have."
      operationId: get-connector-state
      parameters:
        - description: Stable connector name
          in: path
          name: connectorName
          required: true
          schema:
            description: Stable connector name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectorState"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - read:organizations
      summary: Get connector state for this organization
      tags:
        - connectors
  /customers:
    get:
      description: Returns a cursor-paginated page of customers for the current organization.
      operationId: list-customers
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageCustomer"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:customers
      summary: List customers
      tags:
        - customers
    post:
      description: Create a new customer with the provided details.
      operationId: create-customer
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Customer"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:customers
      summary: Create a new customer
      tags:
        - customers
  /customers/{customerSlug}:
    delete:
      description: Delete a customer by their slug.
      operationId: delete-customer
      parameters:
        - in: path
          name: customerSlug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:customers
      summary: Delete a customer
      tags:
        - customers
    get:
      description: Returns a single customer by their slug.
      operationId: get-customer
      parameters:
        - in: path
          name: customerSlug
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:customers
      summary: Get a customer by slug
      tags:
        - customers
    put:
      description: Update a customer's details. Slug and integrations are not renameable/settable through this endpoint -- omit them, or send the values already on record.
      operationId: update-customer
      parameters:
        - in: path
          name: customerSlug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Customer"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:customers
      summary: Update a customer
      tags:
        - customers
  /customers/{customerSlug}/integrations/{integrationName}:
    delete:
      description: Delete a single integration for a customer
      operationId: delete-customer-integration
      parameters:
        - description: Customer slug
          in: path
          name: customerSlug
          required: true
          schema:
            description: Customer slug
            examples:
              - acme-corp
            type: string
        - description: Integration adapter name
          in: path
          name: integrationName
          required: true
          schema:
            description: Integration adapter name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:customers
      summary: Delete a customer integration
      tags:
        - customers
    get:
      description: Retrieve a single integration for a customer
      operationId: get-customer-integration
      parameters:
        - description: Customer slug
          in: path
          name: customerSlug
          required: true
          schema:
            description: Customer slug
            examples:
              - acme-corp
            type: string
        - description: Integration adapter name
          in: path
          name: integrationName
          required: true
          schema:
            description: Integration adapter name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerIntegration"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:customers
      summary: Get a customer integration
      tags:
        - customers
    post:
      description: Create a single integration for a customer
      operationId: create-customer-integration
      parameters:
        - description: Customer slug
          in: path
          name: customerSlug
          required: true
          schema:
            description: Customer slug
            examples:
              - acme-corp
            type: string
        - description: Integration adapter name
          in: path
          name: integrationName
          required: true
          schema:
            description: Integration adapter name
            examples:
              - kaiten.integration.crm.attio
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerIntegration"
              description: Integration payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerIntegration"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:customers
      summary: Create a customer integration
      tags:
        - customers
    put:
      description: Update a single integration for a customer
      operationId: update-customer-integration
      parameters:
        - description: Customer slug
          in: path
          name: customerSlug
          required: true
          schema:
            description: Customer slug
            examples:
              - acme-corp
            type: string
        - description: Integration adapter name
          in: path
          name: integrationName
          required: true
          schema:
            description: Integration adapter name
            examples:
              - kaiten.integration.crm.attio
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerIntegration"
              description: Integration payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerIntegration"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:customers
      summary: Update a customer integration
      tags:
        - customers
  /deployment-zones:
    get:
      description: Returns a cursor-paginated page of deployment zones for the current organization. A deployment zone is one place a customer runs a release -- a target they name and classify themselves, holding the release currently on it. It is not an installation of Kaiten; that sense of the term belongs to operations and is not reachable through this API.
      operationId: list-deployment-zones
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageDeploymentZone"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:deployment_zones
      summary: List deployment zones
      tags:
        - deploymentZones
    post:
      description: Create a new deployment zone with the provided details. Supplying releaseId records the zone's first deployment. A deployment zone is one place a customer runs a release -- a target they name and classify themselves, holding the release currently on it. It is not an installation of Kaiten; that sense of the term belongs to operations and is not reachable through this API.
      operationId: create-deployment-zone
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeploymentZone"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeploymentZone"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:deployment_zones
      summary: Create a new deployment zone
      tags:
        - deploymentZones
  /deployment-zones/{deploymentZoneSlug}:
    delete:
      description: Delete a deployment zone by their slug.
      operationId: delete-deployment-zone
      parameters:
        - in: path
          name: deploymentZoneSlug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:deployment_zones
      summary: Delete a deployment zone
      tags:
        - deploymentZones
    get:
      description: Returns a single deployment zone by their slug.
      operationId: get-deployment-zone-by-slug
      parameters:
        - in: path
          name: deploymentZoneSlug
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeploymentZone"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:deployment_zones
      summary: Get a deployment zone by slug
      tags:
        - deploymentZones
    put:
      description: "Update a deployment zone's details. Changing releaseId records a deployment: the zone's current release becomes the new one and the change is appended to its deployment history, including when the new release is one the zone already ran (a rollback). Omitting releaseId, or echoing back the current one, leaves the history untouched."
      operationId: update-deploymentZone
      parameters:
        - in: path
          name: deploymentZoneSlug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeploymentZone"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:deployment_zones
      summary: Update a deployment zone
      tags:
        - deploymentZones
  /entitlement-groups:
    get:
      description: Returns a cursor-paginated page of entitlement groups for the current organization.
      operationId: list-entitlement-groups
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageEntitlementGroup"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:entitlements
      summary: List all entitlement groups
      tags:
        - entitlement-groups
    post:
      description: Create a new entitlement group to aggregate entitlements
      operationId: create-entitlement-group
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntitlementGroup"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntitlementGroup"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:entitlements
      summary: Create a new entitlement group
      tags:
        - entitlement-groups
  /entitlement-groups/{entitlementGroupSlug}:
    delete:
      description: Delete an entitlement group by its slug. This does not delete the member entitlements.
      operationId: delete-entitlement-group
      parameters:
        - in: path
          name: entitlementGroupSlug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:entitlements
      summary: Delete an entitlement group
      tags:
        - entitlement-groups
    get:
      description: Retrieve details of a specific entitlement group by its slug
      operationId: get-entitlement-group
      parameters:
        - in: path
          name: entitlementGroupSlug
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntitlementGroup"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:entitlements
      summary: Get entitlement group by slug
      tags:
        - entitlement-groups
    put:
      description: Update an existing entitlement group with the provided details
      operationId: update-entitlement-group
      parameters:
        - in: path
          name: entitlementGroupSlug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntitlementGroup"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:entitlements
      summary: Update an entitlement group
      tags:
        - entitlement-groups
  /entitlement-groups/{entitlementGroupSlug}/entitlements:
    post:
      description: Add an existing entitlement as a member of an entitlement group
      operationId: add-entitlement-to-group
      parameters:
        - in: path
          name: entitlementGroupSlug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Command"
        required: true
      responses:
        "201":
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:entitlements
      summary: Add an entitlement to a group
      tags:
        - entitlement-groups
  /entitlement-groups/{entitlementGroupSlug}/entitlements/{entitlementSlug}:
    delete:
      description: Remove an entitlement from an entitlement group. The entitlement itself is not deleted.
      operationId: remove-entitlement-from-group
      parameters:
        - in: path
          name: entitlementGroupSlug
          required: true
          schema:
            type: string
        - in: path
          name: entitlementSlug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:entitlements
      summary: Remove an entitlement from a group
      tags:
        - entitlement-groups
  /entitlement-groups/{entitlementGroupSlug}/usage:
    get:
      description: Retrieve the aggregated usage metrics of all member entitlements for a given instance
      operationId: get-entitlement-group-usage
      parameters:
        - in: path
          name: entitlementGroupSlug
          required: true
          schema:
            type: string
        - description: Instance slug to get usage for
          explode: false
          in: query
          name: instance
          required: true
          schema:
            description: Instance slug to get usage for
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/EntitlementGroupUsage"
                type:
                  - array
                  - "null"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:entitlements
      summary: Get aggregated usage for an entitlement group
      tags:
        - entitlement-groups
  /entitlements:
    get:
      description: Returns a cursor-paginated page of entitlements for the current organization.
      operationId: list-entitlements
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageEntitlement"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:entitlements
      summary: List all entitlements
      tags:
        - entitlements
    post:
      description: Create a new entitlement with the provided details
      operationId: create-entitlement
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Entitlement"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Entitlement"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:entitlements
      summary: Create a new entitlement
      tags:
        - entitlements
  /entitlements/{entitlementSlug}:
    delete:
      description: Delete an entitlement by its slug
      operationId: delete-entitlement
      parameters:
        - in: path
          name: entitlementSlug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:entitlements
      summary: Delete an entitlement
      tags:
        - entitlements
    get:
      description: Retrieve details of a specific entitlement by its slug
      operationId: get-entitlement
      parameters:
        - in: path
          name: entitlementSlug
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Entitlement"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:entitlements
      summary: Get entitlement by slug
      tags:
        - entitlements
    put:
      description: Update an existing entitlement with the provided details
      operationId: update-entitlement
      parameters:
        - in: path
          name: entitlementSlug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Entitlement"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:entitlements
      summary: Update an entitlement
      tags:
        - entitlements
  /feature-flags:
    get:
      description: Returns a cursor-paginated page of feature flags for the given organization.
      operationId: get-feature-flags
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageFeatureFlag"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:feature_flags
      summary: Get a list of feature flags
      tags:
        - featureflags
    post:
      description: Create a new featureflag with the provided details
      operationId: create-feature-flag
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeatureFlag"
              description: Feature flag details
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureFlag"
                description: Created feature flag
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:feature_flags
      summary: Create a new featureflag
      tags:
        - featureflags
  /feature-flags/targeting/context:
    get:
      description: "Returns the identifiers a targeting rule may read, with their types and descriptions, including the organization's own entitlement slugs. Intended for an editor: it is what autocomplete and hover documentation are built from. The set is not closed — a rule may also target on attributes the caller supplies in its own evaluation context."
      operationId: get-targeting-context
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TargetingContext"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:feature_flags
      summary: Get the targeting context schema
      tags:
        - featureflags
  /feature-flags/targeting/lint:
    post:
      description: "Runs the same check create and update run before accepting a targeting rule, and reports what it found without writing anything. A rule that references a fact or an entitlement that does not exist does not fail loudly at evaluation — it simply never matches — so this is what lets an editor say so while the rule is being written. A rejected rule is a 200 carrying `valid: false`, not a client error."
      operationId: lint-targeting-rule
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TargetingRuleDraft"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TargetingRuleVerdict"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:feature_flags
      summary: Check a targeting rule
      tags:
        - featureflags
  /feature-flags/targeting/test:
    post:
      description: "Runs a rule the way an evaluation would, without a flag and without writing anything: the context is enriched from the same sources (license, entitlements, instance, customer, deployment zone), anything the caller forged under __kaiten is discarded the same way, and the same engine answers. The response carries the enriched facts so an author can see exactly what the rule read — which is usually the answer to why it did or did not match. Nothing is metered or audited: this is authoring, not serving."
      operationId: test-targeting-rule
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TargetingRuleTrial"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TargetingRuleRehearsal"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:feature_flags
      summary: Rehearse a targeting rule against a context
      tags:
        - featureflags
  /feature-flags/{featureFlagSlug}:
    delete:
      description: Delete a featureflag with the provided details
      operationId: delete-feature-flag
      parameters:
        - in: path
          name: featureFlagSlug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:feature_flags
      summary: Delete a featureflag
      tags:
        - featureflags
    get:
      description: Get a feature flag with the provided slug
      operationId: get-feature-flag
      parameters:
        - in: path
          name: featureFlagSlug
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureFlag"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:feature_flags
      summary: Get a feature flag by slug
      tags:
        - featureflags
    put:
      description: Update a featureflag with the provided details
      operationId: update-feature-flag
      parameters:
        - in: path
          name: featureFlagSlug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeatureFlag"
              description: Feature flag details
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:feature_flags
      summary: Update a featureflag
      tags:
        - featureflags
  /instances:
    get:
      description: Returns a cursor-paginated page of instances for the current organization.
      operationId: getInstances
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageInstance"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:instances
      summary: List all instances
      tags:
        - instances
    post:
      description: Create a new instance with the provided details
      operationId: createInstance
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Instance"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:instances
      summary: Create a new instance
      tags:
        - instances
  /instances/{instanceSlug}:
    delete:
      description: Delete an instance with the provided slug
      operationId: deleteInstance
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:instances
      summary: Delete an instance
      tags:
        - instances
    get:
      description: Retrieve an instance by their unique slug
      operationId: getInstance
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:instances
      summary: Get an instance by slug
      tags:
        - instances
    patch:
      description: Partially update an instance. Currently supports the operational status and the commercial lifecycle stage.
      operationId: patchInstance
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchInstanceBody"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:instances
      summary: Patch an instance
      tags:
        - instances
    put:
      description: Update an instance with the provided details
      operationId: updateInstance
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Instance"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:instances
      summary: Update an instance
      tags:
        - instances
  /instances/{instanceSlug}/audit-trails:
    get:
      description: "Returns audit trail events for a given instance, optionally filtered by event name and time range. Results are cursor-paginated (default limit: 50, max: 200) — pass the previous response's nextCursor as the cursor parameter to fetch the next page."
      operationId: getAuditTrails
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
        - description: Filter by exact event name (e.g. ENTITLEMENT_VALUE_GET)
          explode: false
          in: query
          name: event_name
          schema:
            description: Filter by exact event name (e.g. ENTITLEMENT_VALUE_GET)
            type: string
        - description: RFC3339 timestamp — include entries with timestamp ≥ this value
          explode: false
          in: query
          name: after
          schema:
            description: RFC3339 timestamp — include entries with timestamp ≥ this value
            type: string
        - description: RFC3339 timestamp — include entries with timestamp ≤ this value
          explode: false
          in: query
          name: before
          schema:
            description: RFC3339 timestamp — include entries with timestamp ≤ this value
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageAuditTrail"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:instances
      summary: List audit trail entries for an instance
      tags:
        - instances
  /instances/{instanceSlug}/entitlements/usage:
    get:
      description: Retrieve a list of all entitlements usage metrics for a specific instance
      operationId: getEntitlementsUsageMetrics
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/EntitlementUsage"
                type:
                  - array
                  - "null"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:instances
      summary: List all entitlements usage metrics
      tags:
        - instances
  /instances/{instanceSlug}/entitlements/{entitlementSlug}/usage:
    get:
      description: Retrieve the usage metrics for a specific entitlement in a given instance
      operationId: getEntitlementUsageMetrics
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
        - description: Entitlement slug
          in: path
          name: entitlementSlug
          required: true
          schema:
            description: Entitlement slug
            examples:
              - entitlement-slug
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntitlementUsage"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:instances
      summary: Get entitlement usage metrics for an instance
      tags:
        - instances
    post:
      description: Report a usage metric for a specific entitlement in a given instance. This endpoint allows you to report the usage of an entitlement, including optional metadata and a timestamp.
      operationId: reportEntitlementUsageMetric
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
        - description: Entitlement slug
          in: path
          name: entitlementSlug
          required: true
          schema:
            description: Entitlement slug
            examples:
              - entitlement-slug
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReportEntitlementUsageBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntitlementUsage"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:instances
      summary: Report entitlement usage metric for an instance
      tags:
        - instances
  /instances/{instanceSlug}/integrations/{integrationName}:
    delete:
      description: Delete a single integration for an instance
      operationId: delete-instance-integration
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
        - description: Integration adapter name
          in: path
          name: integrationName
          required: true
          schema:
            description: Integration adapter name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:instances
      summary: Delete an instance integration
      tags:
        - instances
    get:
      description: Retrieve a single integration for an instance
      operationId: get-instance-integration
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
        - description: Integration adapter name
          in: path
          name: integrationName
          required: true
          schema:
            description: Integration adapter name
            examples:
              - kaiten.integration.crm.attio
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstanceIntegration"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:instances
      summary: Get an instance integration
      tags:
        - instances
    post:
      description: Create a single integration for an instance
      operationId: create-instance-integration
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
        - description: Integration adapter name
          in: path
          name: integrationName
          required: true
          schema:
            description: Integration adapter name
            examples:
              - kaiten.integration.crm.attio
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstanceIntegration"
              description: Integration payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstanceIntegration"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:instances
      summary: Create an instance integration
      tags:
        - instances
    put:
      description: Update a single integration for an instance
      operationId: update-instance-integration
      parameters:
        - description: Instance slug
          in: path
          name: instanceSlug
          required: true
          schema:
            description: Instance slug
            examples:
              - instance-slug
            type: string
        - description: Integration adapter name
          in: path
          name: integrationName
          required: true
          schema:
            description: Integration adapter name
            examples:
              - kaiten.integration.crm.attio
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstanceIntegration"
              description: Integration payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstanceIntegration"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:instances
      summary: Update an instance integration
      tags:
        - instances
  /integration/{adapter}/customer/{externalId}:
    get:
      description: Resolve a customer through one of its integrations using adapter + external ID.
      operationId: get-customer-integration-by-external-id
      parameters:
        - description: Integration adapter without the kaiten.integration. prefix
          in: path
          name: adapter
          required: true
          schema:
            description: Integration adapter without the kaiten.integration. prefix
            examples:
              - crm.attio
            type: string
        - description: External identifier in the third-party system
          in: path
          name: externalId
          required: true
          schema:
            description: External identifier in the third-party system
            examples:
              - rec_12345
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerIntegrationResource"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:customers
      summary: Get a customer by integration external ID
      tags:
        - integrations
        - customers
    patch:
      description: Create or partially update a customer resolved through adapter + external ID. Missing fields are left unchanged.
      operationId: upsert-customer-integration-by-external-id
      parameters:
        - description: Integration adapter without the kaiten.integration. prefix
          in: path
          name: adapter
          required: true
          schema:
            description: Integration adapter without the kaiten.integration. prefix
            examples:
              - crm.attio
            type: string
        - description: External identifier in the third-party system
          in: path
          name: externalId
          required: true
          schema:
            description: External identifier in the third-party system
            examples:
              - rec_12345
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerIntegrationResource"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:customers
      summary: Upsert a customer by integration external ID
      tags:
        - integrations
        - customers
  /integration/{adapter}/instance/{externalId}:
    get:
      description: Resolve an instance through one of its integrations using adapter + external ID.
      operationId: get-instance-integration-by-external-id
      parameters:
        - description: Integration adapter without the kaiten.integration. prefix
          in: path
          name: adapter
          required: true
          schema:
            description: Integration adapter without the kaiten.integration. prefix
            examples:
              - crm.attio
            type: string
        - description: External identifier in the third-party system
          in: path
          name: externalId
          required: true
          schema:
            description: External identifier in the third-party system
            examples:
              - rec_12345
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstanceIntegrationResource"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:instances
      summary: Get an instance by integration external ID
      tags:
        - integrations
        - instances
    patch:
      description: Create or partially update an instance resolved through adapter + external ID. Missing fields are left unchanged.
      operationId: upsert-instance-integration-by-external-id
      parameters:
        - description: Integration adapter without the kaiten.integration. prefix
          in: path
          name: adapter
          required: true
          schema:
            description: Integration adapter without the kaiten.integration. prefix
            examples:
              - crm.attio
            type: string
        - description: External identifier in the third-party system
          in: path
          name: externalId
          required: true
          schema:
            description: External identifier in the third-party system
            examples:
              - rec_12345
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstanceBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstanceIntegrationResource"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:instances
      summary: Upsert an instance by integration external ID
      tags:
        - integrations
        - instances
  /license-families:
    get:
      description: "Returns a cursor-paginated page of license families for the current organization, each with the version it currently resolves to: the family's default version, or its highest-numbered published version. A family whose versions are all drafts or all archived is still listed, with no current version."
      operationId: list-license-families
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageLicenseFamilyView"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:licenses
      summary: List license families
      tags:
        - license-families
  /license-families/{familySlug}:
    get:
      description: |-
        Resolves a license family to the version it currently serves, returned as currentVersion: the family's default version if it has one, otherwise its highest-numbered PUBLISHED version. This is the stable address for "the current version of this product", so a caller never has to name a version slug.

        A family with a default keeps serving it when a newer version is published -- the default is what the vendor puts forward, and superseding it is an explicit act (make another version the default, or unset it). A family without a default follows publication: the newest PUBLISHED version wins.

        Returns 404 GetLicenseFamily.NoPublishedVersion when the family exists but has no PUBLISHED version, since there is nothing to resolve to. Use ?include=versions to read such a family anyway: with the history requested, the family is returned with its versions and no currentVersion. Use ?version=N for explicit access to one version, including draft and archived ones.
      operationId: get-license-family
      parameters:
        - description: License family slug
          in: path
          name: familySlug
          required: true
          schema:
            description: License family slug
            examples:
              - enterprise-license
            type: string
        - description: "Address this version number instead of resolving the current one. Explicit historical access: the version is returned in currentVersion whatever its lifecycle state, draft and archived included, and the resolution rule does not apply."
          explode: false
          in: query
          name: version
          schema:
            description: "Address this version number instead of resolving the current one. Explicit historical access: the version is returned in currentVersion whatever its lifecycle state, draft and archived included, and the resolution rule does not apply."
            format: int32
            minimum: 1
            type: integer
        - description: "Extra representations to add, comma-separated. Only 'versions' exists today: it adds every version of the family, oldest first, and makes a family with no PUBLISHED version readable instead of a 404. A list, so that another representation can be added later without changing the parameter's type."
          explode: false
          in: query
          name: include
          schema:
            description: "Extra representations to add, comma-separated. Only 'versions' exists today: it adds every version of the family, oldest first, and makes a family with no PUBLISHED version readable instead of a 404. A list, so that another representation can be added later without changing the parameter's type."
            items:
              enum:
                - versions
              type: string
            type: array
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseFamilyView"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:licenses
      summary: Get a license family by slug
      tags:
        - license-families
  /licenses:
    get:
      description: Returns a cursor-paginated page of licenses for the current organization.
      operationId: get-licenses
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageLicense"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:licenses
      summary: GetUser all licenses
      tags:
        - licenses
    post:
      description: |-
        Create a new license with the provided details. Without familySlug or familyId this creates a new license family and the license becomes its version 1. With one of them it adds the next version to that family (familySlug names it by slug, familyId by identifier; sent together they must agree), and the version number is assigned by the server as the next one in the family's sequence. The version starts PUBLISHED, or DRAFT when lifecycleState says so; ARCHIVED is refused (422 CreateLicense.LifecycleStateNotSettable), because a version is archived with archive-license once it has been on sale.

        Where the deployment limits how many licenses an organization may have, only a new family counts against that limit (409 CreateLicense.EntitlementLimitReached once it is reached): a new version of an existing family never does.
      operationId: create-license
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/License"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/License"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:licenses
      summary: Create a new license
      tags:
        - licenses
  /licenses/{licenseSlug}:
    delete:
      description: Delete a license with the provided details. Deleting the last version of a license family also deletes the family, and frees its slug for a new product to take. A deleted version's number is not reused by the next version of its family.
      operationId: delete-license
      parameters:
        - description: License slug
          in: path
          name: licenseSlug
          required: true
          schema:
            description: License slug
            examples:
              - license-slug
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:licenses
      summary: Delete a license
      tags:
        - licenses
    get:
      description: Retrieve a license by their unique slug
      operationId: get-license
      parameters:
        - description: License slug
          in: path
          name: licenseSlug
          required: true
          schema:
            description: License slug
            examples:
              - license-slug
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/License"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:licenses
      summary: Get a license by slug
      tags:
        - licenses
    put:
      description: Update a license with the provided details
      operationId: update-license
      parameters:
        - description: License slug
          in: path
          name: licenseSlug
          required: true
          schema:
            description: License slug
            examples:
              - license-slug
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/License"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:licenses
      summary: Update a license
      tags:
        - licenses
  /licenses/{licenseSlug}/archive:
    post:
      description: "Withdraws a PUBLISHED license version from sale: its family stops resolving to it and no instance can be assigned to it any more, while instances already on it keep it. Only a published version can be archived (409 ArchiveLicense.NotPublished) -- a draft that was never on sale is deleted instead -- and not while it is its family's default (409 ArchiveLicense.DefaultMustBePublished): make another version the default, or unset it, first. Emits LICENSE_ARCHIVED."
      operationId: archive-license
      parameters:
        - description: License version slug
          in: path
          name: licenseSlug
          required: true
          schema:
            description: License version slug
            examples:
              - enterprise-license-v2
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/License"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:licenses
      summary: Archive a license version
      tags:
        - licenses
  /licenses/{licenseSlug}/entitlements:
    get:
      description: Returns a cursor-paginated page of entitlements granted by a license, identified by its unique slug.
      operationId: get-license-entitlements
      parameters:
        - description: License slug
          in: path
          name: licenseSlug
          required: true
          schema:
            description: License slug
            examples:
              - license-slug
            type: string
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageLicenseEntitlement"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:licenses
      summary: Get all entitlements for a license
      tags:
        - licenses
    post:
      description: Associate an entitlement with a license by providing the license slug and entitlement details
      operationId: associate-entitlement-with-license
      parameters:
        - description: License slug
          in: path
          name: licenseSlug
          required: true
          schema:
            description: License slug
            examples:
              - license-slug
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LicenseEntitlement"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:licenses
      summary: Associate an entitlement with a license
      tags:
        - licenses
  /licenses/{licenseSlug}/entitlements/{entitlementSlug}:
    delete:
      description: Delete a license entitlement with the provided details
      operationId: delete-license-entitlement
      parameters:
        - in: path
          name: licenseSlug
          required: true
          schema:
            type: string
        - in: path
          name: entitlementSlug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:licenses
      summary: Delete a license entitlement
      tags:
        - licenses
    get:
      description: Retrieve a entitlement for a license by their unique slugs
      operationId: get-license-entitlement
      parameters:
        - in: path
          name: licenseSlug
          required: true
          schema:
            type: string
        - in: path
          name: entitlementSlug
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseEntitlement"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:licenses
      summary: Get a license entitlement
      tags:
        - licenses
    put:
      description: Update an license entitlement with the provided details
      operationId: update-license-entitlement
      parameters:
        - in: path
          name: licenseSlug
          required: true
          schema:
            type: string
        - in: path
          name: entitlementSlug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LicenseEntitlement"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:licenses
      summary: Update an license entitlement
      tags:
        - licenses
  /licenses/{licenseSlug}/publish:
    post:
      description: "Puts a DRAFT license version on sale: it becomes PUBLISHED, so it can be made its family's default, and its family resolves to it when the family has no default and this is its highest published version. Only a draft can be published (409 PublishLicense.NotADraft); an archived version goes back on sale with unarchive-license. Emits LICENSE_PUBLISHED."
      operationId: publish-license
      parameters:
        - description: License version slug
          in: path
          name: licenseSlug
          required: true
          schema:
            description: License version slug
            examples:
              - enterprise-license-v2
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/License"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:licenses
      summary: Publish a license version
      tags:
        - licenses
  /licenses/{licenseSlug}/unarchive:
    post:
      description: "Puts an ARCHIVED license version back on sale: it is PUBLISHED again, can be assigned to instances, and can be what its family resolves to. Only an archived version can be unarchived (409 UnarchiveLicense.NotArchived). Emits LICENSE_UNARCHIVED."
      operationId: unarchive-license
      parameters:
        - description: License version slug
          in: path
          name: licenseSlug
          required: true
          schema:
            description: License version slug
            examples:
              - enterprise-license-v2
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/License"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:licenses
      summary: Unarchive a license version
      tags:
        - licenses
  /metadata-fields:
    get:
      description: Returns a cursor-paginated page of the active (non-archived) metadata fields declared for the org and the given resource type, ordered by displayOrder then createdAt.
      operationId: list-metadata-fields
      parameters:
        - explode: false
          in: query
          name: resourceType
          required: true
          schema:
            enum:
              - DEPLOYMENT_ZONE
              - INSTANCE
            type: string
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageMetadataField"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:metadata_fields
      summary: List active metadata fields for a resource type
      tags:
        - metadataFields
    post:
      description: Declares a typed metadata field for a given resource type (DEPLOYMENT_ZONE, INSTANCE). The json_schema is validated against JSON Schema 2020-12 before insertion. Restricted to write:metadata_fields scope (admin-only policy).
      operationId: create-metadata-field
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MetadataField"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetadataField"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:metadata_fields
      summary: Create a metadata field
      tags:
        - metadataFields
  /metadata-fields/reorder:
    post:
      description: Sets the displayOrder of the listed fields to their position in the array (0-indexed). All ids must belong to the same organization, resource type, and be non-archived; the entire reorder is applied in a single transaction.
      operationId: reorder-metadata-fields
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReorderMetadataFieldsInput"
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:metadata_fields
      summary: Reorder metadata fields
      tags:
        - metadataFields
  /metadata-fields/{id}:
    patch:
      description: "Updates label and json_schema. `key` and `resourceType` are immutable, and `displayOrder` belongs to POST /metadata-fields/reorder. The new json_schema is validated against JSON Schema 2020-12 and the transition rules: type changes, cardinality changes, and free-string ↔ enum toggles are rejected with 422."
      operationId: update-metadata-field
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MetadataField"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetadataField"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:metadata_fields
      summary: Update a metadata field
      tags:
        - metadataFields
  /metadata-fields/{id}/archive:
    post:
      description: Soft-deletes a metadata field. The row stays in the DB (its archived_at is set) so historic metadata is still interpretable; the field stops appearing in the active schema composition.
      operationId: archive-metadata-field
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetadataField"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:metadata_fields
      summary: Archive a metadata field
      tags:
        - metadataFields
  /metadata-fields/{id}/dry-run:
    post:
      description: Computes, server-side, how many existing resources of this field's resource type carry a value under this field's key that would NOT satisfy the supplied candidate JSON Schema, plus a small sample. Read-only — does not mutate the field. Replaces the former client-side dry-run that pulled every resource's metadata.
      operationId: dry-run-metadata-field
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MetadataFieldSchemaProposal"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Impact"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:metadata_fields
      summary: Preview the impact of a metadata field schema change
      tags:
        - metadataFields
  /metadata-fields/{id}/unarchive:
    post:
      description: Restores a previously archived metadata field (clears its archived_at). The field re-enters the active schema composition. Returns 409 if an active field already uses the same key for this resource type, or 404 if the field does not exist or is not archived.
      operationId: unarchive-metadata-field
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetadataField"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:metadata_fields
      summary: Unarchive a metadata field
      tags:
        - metadataFields
  /ofrep/v1/evaluate/flags:
    post:
      description: |-
        OFREP bulk evaluation request.
        The endpoint is called by the client providers to evaluate all flags at once.
      operationId: evaluateFlagsBulk
      parameters:
        - description: The request will be processed only if ETag doesn't match any of the values listed.
          in: header
          name: If-None-Match
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkEvaluationRequest"
        description: EvaluateVariant multiple flags in one request
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                  - properties:
                      flags:
                        description: Array of evaluation results
                        items:
                          oneOf:
                            - $ref: "#/components/schemas/EvaluationSuccess"
                            - $ref: "#/components/schemas/EvaluationFailure"
                        type: array
                  - $ref: "#/components/schemas/BulkEvaluationFailure"
          description: OFREP successful evaluation response
          headers:
            ETag:
              description: Entity tag used for cache validation
              schema:
                type: string
        "304":
          description: Bulk evaluation is not modified
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkEvaluationFailure"
          description: Bad evaluation request
        "401":
          description: Unauthorized - You need credentials to access the API
        "403":
          description: Forbidden - You are not authorized to access the API
        "429":
          description: Rate limit reached on the Flag Management System
          headers:
            Retry-After:
              description: Indicates when to retry the request again
              schema:
                type: string
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkEvaluationFailure"
          description: Internal server error
      security:
        - bearerAuth:
            - read:feature_flags
      summary: OFREP bulk flag evaluation contract
      tags:
        - OFREP Core
  /ofrep/v1/evaluate/flags/{key}:
    post:
      description: EvaluateVariant a single feature flag for a given key
      operationId: evaluateFlag
      parameters:
        - in: path
          name: key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EvaluationRequest"
        description: Evaluation context
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvaluationSuccess"
          description: Flag evaluated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvaluationFailure"
          description: Evaluation failed
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvaluationFailure"
          description: Internal error
      security:
        - bearerAuth:
            - read:feature_flags
      summary: OFREP single flag evaluation contract
      tags:
        - OFREP Core
  /openfeature/v0/manifest:
    get:
      description: Returns a manifest of all feature flags that have a fallback_value set in their metadata
      operationId: get-openfeature-manifest
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManifestEnvelope"
          description: OK
          headers:
            X-Manifest-Capabilities:
              schema:
                type: string
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:feature_flags
      summary: Get OpenFeature manifest
      tags:
        - OpenFeature
  /releases:
    get:
      description: Returns a cursor-paginated page of releases for the current organization.
      operationId: list-releases
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageRelease"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:releases
      summary: List releases
      tags:
        - releases
    post:
      description: "Create a new release with the provided details and link the requested components. A release is immutable: there is no update endpoint, and the component list cannot change afterwards. Correcting one means deleting it and creating a new one, which starts a new deployment history."
      operationId: create-release
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Release"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Release"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:releases
      summary: Create a new release
      tags:
        - releases
  /releases/{releaseSlug}:
    delete:
      description: Delete a release by their slug. Since a release is immutable, this plus a fresh create is the only way to change one -- and it discards the deployment history recorded against the old release. A release still deployed to a zone cannot be deleted (409).
      operationId: delete-release
      parameters:
        - description: Release slug
          in: path
          name: releaseSlug
          required: true
          schema:
            description: Release slug
            examples:
              - release-slug
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:releases
      summary: Delete a release
      tags:
        - releases
    get:
      description: Returns a single release by their slug.
      operationId: get-release-by-slug
      parameters:
        - description: Release slug
          in: path
          name: releaseSlug
          required: true
          schema:
            description: Release slug
            examples:
              - release-slug
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Release"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:releases
      summary: Get a release by slug
      tags:
        - deploymentZones
  /service-accounts:
    get:
      description: Returns a cursor-paginated page of service accounts (machine users) for the current organization.
      operationId: get-service-accounts
      parameters:
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageServiceAccount"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:tokens
      summary: List all service accounts
      tags:
        - service-accounts
    post:
      description: Create a new service account (machine user) with the provided name. Service accounts can be used to generate API tokens for programmatic access.
      operationId: create-service-account
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServiceAccount"
              description: Service account details
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceAccount"
                description: Created service account
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:tokens
      summary: Create a new service account
      tags:
        - service-accounts
  /service-accounts/{serviceAccountSlug}:
    get:
      description: Retrieve details of a specific service account (machine user) by its slug.
      operationId: get-service-account
      parameters:
        - description: Service account slug
          in: path
          name: serviceAccountSlug
          required: true
          schema:
            description: Service account slug
            examples:
              - service-account-slug
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceAccount"
                description: Service account details
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:tokens
      summary: Get a service account by slug
      tags:
        - service-accounts
    put:
      description: Update the name of a service account (machine user) by its slug.
      operationId: update-service-account
      parameters:
        - description: Service account slug
          in: path
          name: serviceAccountSlug
          required: true
          schema:
            description: Service account slug
            examples:
              - service-account-slug
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServiceAccount"
              description: Service account update details
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:tokens
      summary: Update a service account
      tags:
        - service-accounts
  /service-accounts/{serviceAccountSlug}/tokens:
    get:
      description: Returns a cursor-paginated page of API tokens associated with a service account. The organization context is derived from the authenticated user's JWT token. Token secret values are never returned, only metadata.
      operationId: get-service-account-tokens
      parameters:
        - description: Service account slug
          in: path
          name: serviceAccountSlug
          required: true
          schema:
            description: Service account slug
            examples:
              - service-account-slug
            type: string
        - description: Opaque pagination cursor from a previous response's nextCursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's nextCursor
            type: string
        - description: Maximum number of entries to return (default 50, max 200)
          explode: false
          in: query
          name: limit
          schema:
            description: Maximum number of entries to return (default 50, max 200)
            format: int32
            maximum: 200
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageToken"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:tokens
      summary: List all tokens for a service account
      tags:
        - service-accounts
    post:
      description: Create a new API token for a service account. The token value is only returned once upon creation and cannot be retrieved again. The organization context is derived from the authenticated user's JWT token.
      operationId: create-service-account-token
      parameters:
        - description: Service account slug
          in: path
          name: serviceAccountSlug
          required: true
          schema:
            description: Service account slug
            examples:
              - service-account-slug
            format: text
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlainToken"
              description: Token creation details
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlainToken"
                description: Created token with secret value (only shown once)
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Service Unavailable
      security:
        - bearerAuth:
            - write:tokens
      summary: Create a new token for a service account
      tags:
        - service-accounts
  /service-accounts/{serviceAccountSlug}/tokens/{tokenSlug}:
    delete:
      description: Revoke an API token for a service account. Once revoked, the token can no longer be used for authentication. The organization context is derived from the authenticated user's JWT token.
      operationId: delete-service-account-token
      parameters:
        - description: Service account slug
          in: path
          name: serviceAccountSlug
          required: true
          schema:
            description: Service account slug
            examples:
              - service-account-slug
            format: text
            type: string
        - description: Token slug to revoke
          in: path
          name: tokenSlug
          required: true
          schema:
            description: Token slug to revoke
            examples:
              - my-token-slug
            format: text
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:tokens
      summary: Revoke a token for a service account
      tags:
        - service-accounts
  /v1/notification-preferences:
    get:
      description: "Every notifiable event, with this user's effective value per channel: their own choice where they made one, the catalogue default otherwise. Events absent from the catalogue of a deployment never appear, which is what keeps high-volume system events out of the feed."
      operationId: getNotificationPreferences
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreferenceMatrix"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:notifications
      summary: Read the caller's notification preferences
      tags:
        - notifications
    put:
      description: Stores the signed-in user's choices and answers with the whole matrix. A value that equals the catalogue default is stored as no row at all, so a later change to that default still reaches this user.
      operationId: putNotificationPreferences
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreferenceChoices"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreferenceMatrix"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:notifications
      summary: Set the caller's notification preferences
      tags:
        - notifications
  /v1/notifications:
    get:
      description: Returns the signed-in user's notification feed, newest first, with the unread count. Notifications are a view over this organization's audit trail, narrowed to the events the user subscribes to; the id of a notification is the id of the audit trail entry it reports.
      operationId: listNotifications
      parameters:
        - description: Which notifications to return (default all)
          explode: false
          in: query
          name: status
          schema:
            description: Which notifications to return (default all)
            enum:
              - all
              - unread
            type: string
        - description: "Only notifications about these kinds of object; repeat the parameter for several (default: all)"
          explode: true
          in: query
          name: objectType
          schema:
            description: "Only notifications about these kinds of object; repeat the parameter for several (default: all)"
            items:
              enum:
                - instance
                - customer
                - release
                - deployment_zone
                - component
                - license
                - token
              type: string
            type:
              - array
              - "null"
        - description: Opaque cursor from a previous response's next_cursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque cursor from a previous response's next_cursor
            type: string
        - description: Page size (default 20, max 50)
          explode: false
          in: query
          name: limit
          schema:
            description: Page size (default 20, max 50)
            format: int32
            maximum: 50
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/List"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - read:notifications
      summary: List the caller's notifications
      tags:
        - notifications
  /v1/notifications/mark-read:
    post:
      description: "Marks the given notifications read for the signed-in user, or all of them with all: true. Ids belonging to another organization are ignored rather than rejected, so a retry of a partially applied call is safe."
      operationId: markNotificationsRead
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReadSelection"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarkReadResult"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - bearerAuth:
            - write:notifications
      summary: Mark notifications read
      tags:
        - notifications
security:
  - bearerAuth: []
servers:
  - url: /api
webhooks:
  com.kaiten.component.v1.created:
    post:
      description: Triggered when a new component is created.
      operationId: onComponentCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Component"
                name:
                  description: Event name
                  enum:
                    - COMPONENT_CREATED
                  examples:
                    - COMPONENT_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.component.v1.created
                  examples:
                    - com.kaiten.component.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Component Created Webhook
      tags:
        - webhooks
        - components
  com.kaiten.component.v1.deleted:
    post:
      description: Triggered when a component is deleted.
      operationId: onComponentDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Component"
                name:
                  description: Event name
                  enum:
                    - COMPONENT_DELETED
                  examples:
                    - COMPONENT_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.component.v1.deleted
                  examples:
                    - com.kaiten.component.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Component Deleted Webhook
      tags:
        - webhooks
        - components
  com.kaiten.component.v1.updated:
    post:
      description: Triggered when a component is updated or auto-versioned.
      operationId: onComponentUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Component"
                name:
                  description: Event name
                  enum:
                    - COMPONENT_UPDATED
                  examples:
                    - COMPONENT_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.component.v1.updated
                  examples:
                    - com.kaiten.component.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Component Updated Webhook
      tags:
        - webhooks
        - components
  com.kaiten.customer.v1.created:
    post:
      description: Triggered when a new customer is created.
      operationId: onCustomerCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Customer"
                name:
                  description: Event name
                  enum:
                    - CUSTOMER_CREATED
                  examples:
                    - CUSTOMER_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.customer.v1.created
                  examples:
                    - com.kaiten.customer.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Customer Created Webhook
      tags:
        - webhooks
        - customers
  com.kaiten.customer.v1.creation_rejected:
    post:
      description: Triggered when a customer creation is refused because the organization has reached its customer entitlement cap. No customer is created.
      operationId: onCustomerCreationRejected
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/CustomerCreationRejected"
                name:
                  description: Event name
                  enum:
                    - CUSTOMER_CREATION_REJECTED
                  examples:
                    - CUSTOMER_CREATION_REJECTED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.customer.v1.creation_rejected
                  examples:
                    - com.kaiten.customer.v1.creation_rejected
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Customer Creation Rejected Webhook
      tags:
        - webhooks
        - customers
  com.kaiten.customer.v1.deleted:
    post:
      description: Triggered when a customer is deleted.
      operationId: onCustomerDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Customer"
                name:
                  description: Event name
                  enum:
                    - CUSTOMER_DELETED
                  examples:
                    - CUSTOMER_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.customer.v1.deleted
                  examples:
                    - com.kaiten.customer.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Customer Deleted Webhook
      tags:
        - webhooks
        - customers
  com.kaiten.customer.v1.updated:
    post:
      description: Triggered when a customer is updated.
      operationId: onCustomerUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Customer"
                name:
                  description: Event name
                  enum:
                    - CUSTOMER_UPDATED
                  examples:
                    - CUSTOMER_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.customer.v1.updated
                  examples:
                    - com.kaiten.customer.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Customer Updated Webhook
      tags:
        - webhooks
        - customers
  com.kaiten.deployment_zone.v1.created:
    post:
      description: Triggered when a new deployment zone is created.
      operationId: onDeploymentZoneCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/DeploymentZone"
                name:
                  description: Event name
                  enum:
                    - DEPLOYMENT_ZONE_CREATED
                  examples:
                    - DEPLOYMENT_ZONE_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.deployment_zone.v1.created
                  examples:
                    - com.kaiten.deployment_zone.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Deployment Zone Created Webhook
      tags:
        - webhooks
        - deploymentZones
  com.kaiten.deployment_zone.v1.deleted:
    post:
      description: Triggered when a deployment zone is deleted.
      operationId: onDeploymentZoneDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/DeploymentZone"
                name:
                  description: Event name
                  enum:
                    - DEPLOYMENT_ZONE_DELETED
                  examples:
                    - DEPLOYMENT_ZONE_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.deployment_zone.v1.deleted
                  examples:
                    - com.kaiten.deployment_zone.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Deployment Zone Deleted Webhook
      tags:
        - webhooks
        - deploymentZones
  com.kaiten.deployment_zone.v1.release_deployed:
    post:
      description: Triggered when a release is deployed to a deployment zone, either at zone creation or when an existing zone's release changes.
      operationId: onReleaseDeployed
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Deployment"
                name:
                  description: Event name
                  enum:
                    - RELEASE_DEPLOYED
                  examples:
                    - RELEASE_DEPLOYED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.deployment_zone.v1.release_deployed
                  examples:
                    - com.kaiten.deployment_zone.v1.release_deployed
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Release Deployed Webhook
      tags:
        - webhooks
        - deploymentZones
  com.kaiten.deployment_zone.v1.updated:
    post:
      description: Triggered when a deployment zone is updated.
      operationId: onDeploymentZoneUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/DeploymentZone"
                name:
                  description: Event name
                  enum:
                    - DEPLOYMENT_ZONE_UPDATED
                  examples:
                    - DEPLOYMENT_ZONE_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.deployment_zone.v1.updated
                  examples:
                    - com.kaiten.deployment_zone.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Deployment Zone Updated Webhook
      tags:
        - webhooks
        - deploymentZones
  com.kaiten.entitlement.v1.created:
    post:
      description: Triggered when a new entitlement is created.
      operationId: onEntitlementCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Entitlement"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_CREATED
                  examples:
                    - ENTITLEMENT_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.entitlement.v1.created
                  examples:
                    - com.kaiten.entitlement.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Created Webhook
      tags:
        - webhooks
        - entitlements
  com.kaiten.entitlement.v1.deleted:
    post:
      description: Triggered when an entitlement is deleted.
      operationId: onEntitlementDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Entitlement"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_DELETED
                  examples:
                    - ENTITLEMENT_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.entitlement.v1.deleted
                  examples:
                    - com.kaiten.entitlement.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Deleted Webhook
      tags:
        - webhooks
        - entitlements
  com.kaiten.entitlement.v1.updated:
    post:
      description: Triggered when an entitlement is updated.
      operationId: onEntitlementUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Entitlement"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_UPDATED
                  examples:
                    - ENTITLEMENT_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.entitlement.v1.updated
                  examples:
                    - com.kaiten.entitlement.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Updated Webhook
      tags:
        - webhooks
        - entitlements
  com.kaiten.entitlement_group.v1.created:
    post:
      description: Triggered when a new entitlement group is created.
      operationId: onEntitlementGroupCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/EntitlementGroup"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_GROUP_CREATED
                  examples:
                    - ENTITLEMENT_GROUP_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.entitlement_group.v1.created
                  examples:
                    - com.kaiten.entitlement_group.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Group Created Webhook
      tags:
        - webhooks
        - entitlement-groups
  com.kaiten.entitlement_group.v1.deleted:
    post:
      description: Triggered when an entitlement group is deleted.
      operationId: onEntitlementGroupDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/EntitlementGroup"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_GROUP_DELETED
                  examples:
                    - ENTITLEMENT_GROUP_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.entitlement_group.v1.deleted
                  examples:
                    - com.kaiten.entitlement_group.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Group Deleted Webhook
      tags:
        - webhooks
        - entitlement-groups
  com.kaiten.entitlement_group.v1.updated:
    post:
      description: Triggered when an entitlement group is updated.
      operationId: onEntitlementGroupUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/EntitlementGroup"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_GROUP_UPDATED
                  examples:
                    - ENTITLEMENT_GROUP_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.entitlement_group.v1.updated
                  examples:
                    - com.kaiten.entitlement_group.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Group Updated Webhook
      tags:
        - webhooks
        - entitlement-groups
  com.kaiten.feature_flag.v1.created:
    post:
      description: Triggered when a new feature flag is created.
      operationId: onFeatureFlagCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/FeatureFlag"
                name:
                  description: Event name
                  enum:
                    - FEATURE_FLAG_CREATED
                  examples:
                    - FEATURE_FLAG_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.feature_flag.v1.created
                  examples:
                    - com.kaiten.feature_flag.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Feature Flag Created Webhook
      tags:
        - webhooks
        - featureflags
  com.kaiten.feature_flag.v1.deleted:
    post:
      description: Triggered when a feature flag is deleted.
      operationId: onFeatureFlagDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/FeatureFlag"
                name:
                  description: Event name
                  enum:
                    - FEATURE_FLAG_DELETED
                  examples:
                    - FEATURE_FLAG_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.feature_flag.v1.deleted
                  examples:
                    - com.kaiten.feature_flag.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Feature Flag Deleted Webhook
      tags:
        - webhooks
        - featureflags
  com.kaiten.feature_flag.v1.evaluated:
    post:
      description: Triggered on every flag evaluation. The payload carries no evaluation context, so no targeting key or user attribute is exposed.
      operationId: onFeatureFlagEvaluated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/FeatureFlagEvaluated"
                name:
                  description: Event name
                  enum:
                    - FEATURE_FLAG_EVALUATED
                  examples:
                    - FEATURE_FLAG_EVALUATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.feature_flag.v1.evaluated
                  examples:
                    - com.kaiten.feature_flag.v1.evaluated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Feature Flag Evaluated Webhook
      tags:
        - webhooks
        - featureflags
  com.kaiten.feature_flag.v1.updated:
    post:
      description: Triggered when a feature flag is updated.
      operationId: onFeatureFlagUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/FeatureFlag"
                name:
                  description: Event name
                  enum:
                    - FEATURE_FLAG_UPDATED
                  examples:
                    - FEATURE_FLAG_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.feature_flag.v1.updated
                  examples:
                    - com.kaiten.feature_flag.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Feature Flag Updated Webhook
      tags:
        - webhooks
        - featureflags
  com.kaiten.identity.v1.system_token_issued:
    post:
      description: "Triggered when a platform credential mints an organization-scoped credential for the `system:kaiten` platform identity inside this organization. Carries the platform credential that performed the mint and the scopes granted, never the credential value. Expect this at the rate an integration refreshes: roughly 120 per day per process at a 15-minute lifetime."
      operationId: onSystemOrganizationTokenIssued
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/SystemTokenIssuance"
                name:
                  description: Event name
                  enum:
                    - SYSTEM_ORGANIZATION_TOKEN_ISSUED
                  examples:
                    - SYSTEM_ORGANIZATION_TOKEN_ISSUED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.identity.v1.system_token_issued
                  examples:
                    - com.kaiten.identity.v1.system_token_issued
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: System Organization Token Issued Webhook
      tags:
        - webhooks
        - identity
  com.kaiten.instance.entitlement.v1.cap_exceeded:
    post:
      description: Triggered when a SOFT-enforcement entitlement's usage crosses from below the cap to above it. Fires once per crossing.
      operationId: onInstanceEntitlementCapExceeded
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/InstanceEntitlementCapExceeded"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_ENTITLEMENT_CAP_EXCEEDED
                  examples:
                    - INSTANCE_ENTITLEMENT_CAP_EXCEEDED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.entitlement.v1.cap_exceeded
                  examples:
                    - com.kaiten.instance.entitlement.v1.cap_exceeded
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Entitlement Cap Exceeded Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.entitlement.v1.usage_period_rolled_over:
    post:
      description: "Triggered once per usage window closed by a report: the entitlement's own stored bucket, and one synthetic event per window skipped entirely since the last report."
      operationId: onInstanceEntitlementUsagePeriodRolledOver
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/InstanceEntitlementUsagePeriodRolledOver"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_ENTITLEMENT_USAGE_PERIOD_ROLLED_OVER
                  examples:
                    - INSTANCE_ENTITLEMENT_USAGE_PERIOD_ROLLED_OVER
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.entitlement.v1.usage_period_rolled_over
                  examples:
                    - com.kaiten.instance.entitlement.v1.usage_period_rolled_over
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Usage Period Rolled Over Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.entitlement.v1.usage_reached:
    post:
      description: Triggered when an instance's entitlement usage reaches its threshold.
      operationId: onInstanceEntitlementUsageReached
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/EntitlementUsage"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_ENTITLEMENT_USAGE_REACHED
                  examples:
                    - INSTANCE_ENTITLEMENT_USAGE_REACHED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.entitlement.v1.usage_reached
                  examples:
                    - com.kaiten.instance.entitlement.v1.usage_reached
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Entitlement Usage Reached Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.entitlement.v1.usage_report_accepted:
    post:
      description: Triggered when a usage report is persisted, including a SOFT-enforcement overage.
      operationId: onInstanceEntitlementUsageReportAccepted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/InstanceEntitlementUsageReportAccepted"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_USAGE_REPORT_ACCEPTED
                  examples:
                    - ENTITLEMENT_USAGE_REPORT_ACCEPTED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.entitlement.v1.usage_report_accepted
                  examples:
                    - com.kaiten.instance.entitlement.v1.usage_report_accepted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Usage Report Accepted Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.entitlement.v1.usage_report_rejected:
    post:
      description: Triggered when a usage report is refused because it would take a HARD-enforcement entitlement past its cap. The usage is not persisted.
      operationId: onInstanceEntitlementUsageReportRejected
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/InstanceEntitlementUsageReportAccepted"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_USAGE_REPORT_REJECTED
                  examples:
                    - ENTITLEMENT_USAGE_REPORT_REJECTED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.entitlement.v1.usage_report_rejected
                  examples:
                    - com.kaiten.instance.entitlement.v1.usage_report_rejected
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Entitlement Usage Report Rejected Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.entitlement.v1.usage_warning_threshold_reached:
    post:
      description: Triggered when an instance's entitlement usage crosses its configured early-warning percentage boundary, before the cap is reached. Fires once per crossing.
      operationId: onInstanceEntitlementUsageWarningThresholdReached
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/InstanceEntitlementUsageWarningThresholdReached"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_ENTITLEMENT_USAGE_WARNING_THRESHOLD_REACHED
                  examples:
                    - INSTANCE_ENTITLEMENT_USAGE_WARNING_THRESHOLD_REACHED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.entitlement.v1.usage_warning_threshold_reached
                  examples:
                    - com.kaiten.instance.entitlement.v1.usage_warning_threshold_reached
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Entitlement Usage Warning Threshold Reached Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.entitlement.v1.value_get:
    post:
      description: Triggered on every read of an instance entitlement's usage value. This is a read audit signal, not a state change.
      operationId: onInstanceEntitlementValueGet
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/InstanceEntitlementValueGet"
                name:
                  description: Event name
                  enum:
                    - ENTITLEMENT_VALUE_GET
                  examples:
                    - ENTITLEMENT_VALUE_GET
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.entitlement.v1.value_get
                  examples:
                    - com.kaiten.instance.entitlement.v1.value_get
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Entitlement Value Read Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.v1.created:
    post:
      description: Triggered when a new instance is created.
      operationId: onInstanceCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Instance"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_CREATED
                  examples:
                    - INSTANCE_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.v1.created
                  examples:
                    - com.kaiten.instance.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Created Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.v1.deleted:
    post:
      description: Triggered when an instance is deleted.
      operationId: onInstanceDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Instance"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_DELETED
                  examples:
                    - INSTANCE_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.v1.deleted
                  examples:
                    - com.kaiten.instance.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Deleted Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.v1.deployed:
    post:
      description: Triggered when an instance is deployed to a deployment zone.
      operationId: onInstanceDeployed
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Instance"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_DEPLOYED
                  examples:
                    - INSTANCE_DEPLOYED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.v1.deployed
                  examples:
                    - com.kaiten.instance.v1.deployed
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Deployed Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.v1.lifecycle_stage_changed:
    post:
      description: Triggered when an instance commercial lifecycle stage changes.
      operationId: onInstanceLifecycleStageChanged
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/InstanceLifecycleStageChanged"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_LIFECYCLE_STAGE_CHANGED
                  examples:
                    - INSTANCE_LIFECYCLE_STAGE_CHANGED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.v1.lifecycle_stage_changed
                  examples:
                    - com.kaiten.instance.v1.lifecycle_stage_changed
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Lifecycle Stage Changed Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.v1.migrated:
    post:
      description: Triggered when an instance is migrated from one deployment zone to another.
      operationId: onInstanceMigrated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Instance"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_MIGRATED
                  examples:
                    - INSTANCE_MIGRATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.v1.migrated
                  examples:
                    - com.kaiten.instance.v1.migrated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Migrated Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.v1.status_changed:
    post:
      description: Triggered when an instance operational status changes.
      operationId: onInstanceStatusChanged
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/InstanceStatusChanged"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_STATUS_CHANGED
                  examples:
                    - INSTANCE_STATUS_CHANGED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.v1.status_changed
                  examples:
                    - com.kaiten.instance.v1.status_changed
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Status Changed Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.instance.v1.updated:
    post:
      description: Triggered when an instance is updated.
      operationId: onInstanceUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Instance"
                name:
                  description: Event name
                  enum:
                    - INSTANCE_UPDATED
                  examples:
                    - INSTANCE_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.instance.v1.updated
                  examples:
                    - com.kaiten.instance.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Instance Updated Webhook
      tags:
        - webhooks
        - instances
  com.kaiten.license.entitlement.v1.assigned:
    post:
      description: Triggered when an entitlement is assigned to a license.
      operationId: onLicenseEntitlementAssigned
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/LicenseEntitlement"
                name:
                  description: Event name
                  enum:
                    - LICENSE_ENTITLEMENT_ASSIGNED
                  examples:
                    - LICENSE_ENTITLEMENT_ASSIGNED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.entitlement.v1.assigned
                  examples:
                    - com.kaiten.license.entitlement.v1.assigned
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Entitlement Assigned Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license.entitlement.v1.unassigned:
    post:
      description: Triggered when an entitlement is unassigned from a license.
      operationId: onLicenseEntitlementUnassigned
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/LicenseEntitlement"
                name:
                  description: Event name
                  enum:
                    - LICENSE_ENTITLEMENT_UNASSIGNED
                  examples:
                    - LICENSE_ENTITLEMENT_UNASSIGNED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.entitlement.v1.unassigned
                  examples:
                    - com.kaiten.license.entitlement.v1.unassigned
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Entitlement Unassigned Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license.entitlement.v1.updated:
    post:
      description: Triggered when a license entitlement is updated.
      operationId: onLicenseEntitlementUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/LicenseEntitlement"
                name:
                  description: Event name
                  enum:
                    - LICENSE_ENTITLEMENT_UPDATED
                  examples:
                    - LICENSE_ENTITLEMENT_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.entitlement.v1.updated
                  examples:
                    - com.kaiten.license.entitlement.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Entitlement Updated Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license.v1.archived:
    post:
      description: Triggered when a published license version is archived and withdrawn from sale.
      operationId: onLicenseArchived
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/License"
                name:
                  description: Event name
                  enum:
                    - LICENSE_ARCHIVED
                  examples:
                    - LICENSE_ARCHIVED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.v1.archived
                  examples:
                    - com.kaiten.license.v1.archived
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Archived Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license.v1.created:
    post:
      description: Triggered when a new license is created.
      operationId: onLicenseCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/License"
                name:
                  description: Event name
                  enum:
                    - LICENSE_CREATED
                  examples:
                    - LICENSE_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.v1.created
                  examples:
                    - com.kaiten.license.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Created Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license.v1.deleted:
    post:
      description: Triggered when a license is deleted.
      operationId: onLicenseDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/License"
                name:
                  description: Event name
                  enum:
                    - LICENSE_DELETED
                  examples:
                    - LICENSE_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.v1.deleted
                  examples:
                    - com.kaiten.license.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Deleted Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license.v1.published:
    post:
      description: Triggered when a draft license version is published and goes on sale.
      operationId: onLicensePublished
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/License"
                name:
                  description: Event name
                  enum:
                    - LICENSE_PUBLISHED
                  examples:
                    - LICENSE_PUBLISHED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.v1.published
                  examples:
                    - com.kaiten.license.v1.published
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Published Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license.v1.unarchived:
    post:
      description: Triggered when an archived license version is put back on sale.
      operationId: onLicenseUnarchived
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/License"
                name:
                  description: Event name
                  enum:
                    - LICENSE_UNARCHIVED
                  examples:
                    - LICENSE_UNARCHIVED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.v1.unarchived
                  examples:
                    - com.kaiten.license.v1.unarchived
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Unarchived Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license.v1.updated:
    post:
      description: Triggered when a license is updated.
      operationId: onLicenseUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/License"
                name:
                  description: Event name
                  enum:
                    - LICENSE_UPDATED
                  examples:
                    - LICENSE_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license.v1.updated
                  examples:
                    - com.kaiten.license.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Updated Webhook
      tags:
        - webhooks
        - licenses
  com.kaiten.license_family.v1.created:
    post:
      description: "Triggered when a license is created without naming a family: its version 1 opens a new family, which this event carries, with the version it serves -- none if that version is a draft. It is recorded in the same transaction as that version's LICENSE_CREATED."
      operationId: onLicenseFamilyCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/LicenseFamilyView"
                name:
                  description: Event name
                  enum:
                    - LICENSE_FAMILY_CREATED
                  examples:
                    - LICENSE_FAMILY_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license_family.v1.created
                  examples:
                    - com.kaiten.license_family.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Family Created Webhook
      tags:
        - webhooks
        - license-families
  com.kaiten.license_family.v1.deleted:
    post:
      description: Triggered when a license family's last version is deleted, which deletes the family and frees its slug. It carries the family as it stood before that version went, and is recorded in the same transaction as that version's LICENSE_DELETED.
      operationId: onLicenseFamilyDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/LicenseFamilyView"
                name:
                  description: Event name
                  enum:
                    - LICENSE_FAMILY_DELETED
                  examples:
                    - LICENSE_FAMILY_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license_family.v1.deleted
                  examples:
                    - com.kaiten.license_family.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Family Deleted Webhook
      tags:
        - webhooks
        - license-families
  com.kaiten.license_family.v1.updated:
    post:
      description: "Triggered when a license family starts serving another version, or none: a newer version published, a version published, archived or unarchived, the family's default taken or given up, or the served version deleted. It carries the family with the version it serves now, and is recorded in the same transaction as the version event that caused the change. A change that leaves the served version where it was -- a draft added, a version renamed, a default restated -- triggers none."
      operationId: onLicenseFamilyUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/LicenseFamilyView"
                name:
                  description: Event name
                  enum:
                    - LICENSE_FAMILY_UPDATED
                  examples:
                    - LICENSE_FAMILY_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.license_family.v1.updated
                  examples:
                    - com.kaiten.license_family.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: License Family Updated Webhook
      tags:
        - webhooks
        - license-families
  com.kaiten.metadata_field.v1.archived:
    post:
      description: Triggered when a metadata field is archived and leaves the active schema composition.
      operationId: onMetadataFieldArchived
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/MetadataField"
                name:
                  description: Event name
                  enum:
                    - METADATA_FIELD_ARCHIVED
                  examples:
                    - METADATA_FIELD_ARCHIVED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.metadata_field.v1.archived
                  examples:
                    - com.kaiten.metadata_field.v1.archived
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Metadata Field Archived Webhook
      tags:
        - webhooks
        - metadataFields
  com.kaiten.metadata_field.v1.created:
    post:
      description: Triggered when a metadata field is declared for a resource type.
      operationId: onMetadataFieldCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/MetadataField"
                name:
                  description: Event name
                  enum:
                    - METADATA_FIELD_CREATED
                  examples:
                    - METADATA_FIELD_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.metadata_field.v1.created
                  examples:
                    - com.kaiten.metadata_field.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Metadata Field Created Webhook
      tags:
        - webhooks
        - metadataFields
  com.kaiten.metadata_field.v1.reordered:
    post:
      description: Triggered when the display order of a resource type's metadata fields is rewritten.
      operationId: onMetadataFieldReordered
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/MetadataFieldReordered"
                name:
                  description: Event name
                  enum:
                    - METADATA_FIELD_REORDERED
                  examples:
                    - METADATA_FIELD_REORDERED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.metadata_field.v1.reordered
                  examples:
                    - com.kaiten.metadata_field.v1.reordered
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Metadata Fields Reordered Webhook
      tags:
        - webhooks
        - metadataFields
  com.kaiten.metadata_field.v1.unarchived:
    post:
      description: Triggered when an archived metadata field is restored to the active schema composition.
      operationId: onMetadataFieldUnarchived
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/MetadataField"
                name:
                  description: Event name
                  enum:
                    - METADATA_FIELD_UNARCHIVED
                  examples:
                    - METADATA_FIELD_UNARCHIVED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.metadata_field.v1.unarchived
                  examples:
                    - com.kaiten.metadata_field.v1.unarchived
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Metadata Field Unarchived Webhook
      tags:
        - webhooks
        - metadataFields
  com.kaiten.metadata_field.v1.updated:
    post:
      description: Triggered when a metadata field's label or JSON schema changes. A reordering emits METADATA_FIELD_REORDERED instead.
      operationId: onMetadataFieldUpdated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/MetadataField"
                name:
                  description: Event name
                  enum:
                    - METADATA_FIELD_UPDATED
                  examples:
                    - METADATA_FIELD_UPDATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.metadata_field.v1.updated
                  examples:
                    - com.kaiten.metadata_field.v1.updated
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Metadata Field Updated Webhook
      tags:
        - webhooks
        - metadataFields
  com.kaiten.release.v1.created:
    post:
      description: Triggered when a new release is created.
      operationId: onReleaseCreated
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Release"
                name:
                  description: Event name
                  enum:
                    - RELEASE_CREATED
                  examples:
                    - RELEASE_CREATED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.release.v1.created
                  examples:
                    - com.kaiten.release.v1.created
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Release Created Webhook
      tags:
        - webhooks
        - releases
  com.kaiten.release.v1.deleted:
    post:
      description: Triggered when a release is deleted.
      operationId: onReleaseDeleted
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  $ref: "#/components/schemas/Release"
                name:
                  description: Event name
                  enum:
                    - RELEASE_DELETED
                  examples:
                    - RELEASE_DELETED
                  type: string
                type:
                  description: Event type
                  enum:
                    - com.kaiten.release.v1.deleted
                  examples:
                    - com.kaiten.release.v1.deleted
                  type: string
              required:
                - name
                - type
                - data
              type: object
        required: true
      responses:
        "200":
          description: Webhook processed successfully
      summary: Release Deleted Webhook
      tags:
        - webhooks
        - releases