@celigo/api-specs 0.2.1

package/dist/subscription.yml

@@ -0,0 +1,1405 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Subscription & Entitlements
+  description: API for reading the current account’s subscription, license entitlements, and usage metrics.
+  x-celigo-ai-guidance:
+    - APIs for subscription (license) information and entitlement usage.
+    - |-
+      Notes:
+      - These endpoints exist under `/v1/*` for API usage. The UI also exposes equivalents under `/api/*`.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Subscription & Entitlements
+    description: |-
+      Subscription (license) information and entitlement usage for the current account, including plan details, feature limits, and consumption metrics.
+
+      ## License schema
+
+      {% openapi-schemas spec="subscription" schemas="License" grouped="true" %}
+paths:
+  /v1/licenses:
+    get:
+      x-internal: false
+      summary: Get licenses (subscription)
+      operationId: getLicenses
+      tags:
+        - Subscription & Entitlements
+      description: |-
+        Returns one account-level license (`type` is `platform`, `integrator`, or
+        `endpoint`) plus zero or more `connector`, `integrationApp`, or
+        `integrationAppChild` licenses.
+      x-celigo-ai-guidance:
+        - |-
+          AI guidance:
+          - Use this to determine the subscription type (`platform`, `integrator`, `endpoint`, `connector`, etc.) and high-level flags (e.g., sandbox access).
+      responses:
+        '200':
+          description: List of licenses
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/License'
+              examples:
+                platform:
+                  summary: Platform license (enterprise tier)
+                  value:
+                    - _id: 624cb0356309dc3a543733a4
+                      created: '2024-04-05T21:10:13.226Z'
+                      lastModified: '2025-08-10T14:22:33.000Z'
+                      expires: '2099-12-31T00:00:00.000Z'
+                      type: platform
+                      tier: enterprise (2024)
+                      supportTier: premier
+                      resumable: false
+                      disableOverage: false
+                      requestUserToMigrateSandbox: false
+                      sso: true
+                      van: true
+                      lookupCache: true
+                      abstractFlows: true
+                      apiManagement: true
+                      concurrency: 25
+                      maxAllowedDataRetention: 180
+                      auditLogRetentionYears: 3
+                      aiConversationsPrepaidBalance: 47.96
+                      aiAgentsPrepaidBalance: 19.62
+                      aiAgentsActions: 10000
+                      platform:
+                        production:
+                          numEndpoints: 600
+                          numAddOnEndpoints: 0
+                          numFlows: 80
+                          numAddOnFlows: 5000
+                          numAgents: 0
+                          numAddOnAgents: 100
+                        apiManagement: true
+                        numEnvironments: 5
+                      edi:
+                        enabled: true
+                        onboarded: true
+                        disableOverage: false
+                        tier: basic
+                        numTradingPartners: 3
+                        numAddOnTradingPartners: 0
+                        numDocumentTypes: 5
+                        numAddOnDocumentTypes: 0
+                        labelPrinting:
+                          enabled: true
+                          onboarded: true
+                          numLabels: 10000
+                          numAddOnLabels: 0
+                      api:
+                        builder: true
+                        enablePricing: false
+                        disableOverages: false
+                        numInvocations: 0
+                        apimNumInvocations: 0
+                        numAddOnInvocations: 0
+                      mcp:
+                        numInvocations: 50000
+                      di:
+                        enabled: false
+                        volume: 0
+                        volumeAddOn: 0
+                        disableOverage: false
+                      logging:
+                        enabled: true
+                        maxLogMode: detailed
+                        maxDebugDuration: 4320
+                        maxRetentionPeriod: 180
+                      storage:
+                        maxAllowedUsage: 200
+                        disableOverage: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/licenseEntitlementUsage:
+    get:
+      x-internal: false
+      summary: Get license entitlement usage
+      operationId: getLicenseEntitlementUsage
+      tags:
+        - Subscription & Entitlements
+      description: |-
+        Returns entitlement usage for the current account/license -- how many resources the account
+        is consuming vs. what is entitled. Pair with `GET /v1/licenses` for the entitlement limits.
+      x-celigo-ai-guidance:
+        - Returns entitlement usage for the current account/license (consumption vs. entitlement, by usage category).
+        - |-
+          The response includes counts such as:
+          - endpoints consumed
+          - flows enabled
+          - agents active
+          - trading partners consumed
+          - environments enabled (for multi-environment licensing)
+      responses:
+        '200':
+          description: Entitlement usage
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LicenseEntitlementUsage'
+              examples:
+                default:
+                  value:
+                    flowUsage:
+                      numEnabled: 12
+                      flows:
+                        - _id: 69d097584e0c505cda036df9
+                          name: HubSpot Contacts → Snowflake (Nightly)
+                          integration:
+                            _id: 69d0973d4e0c505cda0368d1
+                            name: POC – HubSpot → Snowflake
+                    endpointUsage:
+                      numConsumed: 8
+                      endpoints:
+                        - type: http
+                          assistant: hubspot
+                          connections:
+                            - _id: 62ac9ab6cd606e428737008e
+                              name: HubSpot (Production)
+                        - type: rdbms
+                          connections:
+                            - _id: 69d096cd4e0c505cda036a3a
+                              name: Snowflake DW
+                    agentUsage:
+                      numActive: 0
+                      agents: []
+                    environmentUsage:
+                      numEnabled: 2
+                      environments:
+                        - _id: 60a2c4e6f321d800129a1a3c
+                          name: Production
+                          enabled: true
+                        - _id: 61b3d5f7e432e900130b2b4d
+                          name: Staging
+                          enabled: true
+                    ediTradingPartnerUsage:
+                      numConsumed: 1
+                      tradingPartners:
+                        - tradingPartnerName: Acme Corp
+                          ediProfiles:
+                            - id: 69014f1691348b59ebed05a9
+                              name: Acme EDI Profile
+                    ediDocumentTypeUsage:
+                      numConsumed: 1
+                      documents:
+                        - category: Purchase Order
+                          fileDefinitions:
+                            - _id: 69014f1691348b59ebed059b
+                              name: Generic EDI 850
+                    ediLabelPrintingUsage:
+                      numConsumed: 1542
+                      flows:
+                        - _id: 6a25e22136b14ada888433f4
+                          name: Bartender — UPS labels
+                          integration:
+                            _id: 69d0973d4e0c505cda0368d1
+                            name: NetSuite — Acme
+                          numConsumed: 812
+                        - _id: 6a25e22136b14ada888433f5
+                          name: Bartender — FedEx labels
+                          integration:
+                            _id: 69d0973d4e0c505cda0368e2
+                            name: NetSuite — Globex
+                          numConsumed: 530
+                    apiUsage:
+                      ioInvocationCount: 1250
+                      apimInvocationCount: 0
+                    syncUsage:
+                      entitlement: 0
+                      volume: 0
+                    mcpUsage:
+                      numInvocations: 340
+                    aiAgentsActionsUsage: 87
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/ediLabelPrinting/usage/summary:
+    get:
+      x-internal: false
+      summary: Get historic label-printing usage
+      operationId: getEDILabelPrintingUsageSummary
+      tags:
+        - Subscription & Entitlements
+      description: |-
+        Returns account-wide EDI label-printing (BarTender) consumption bucketed into the trailing
+        12 ISO weeks (Monday–Sunday UTC), most-recent week first. Each week's total sums every flow and
+        environment under the account. Pair with the `ediLabelPrintingUsage` block on
+        `GET /v1/licenseEntitlementUsage` for the current week's per-flow breakdown.
+      x-celigo-ai-guidance:
+        - Read-only historic view; takes no query parameters (the window is fixed at 12 weeks).
+        - Returns an empty `weeks` array when label printing is disabled for the account rather than a 4xx.
+      responses:
+        '200':
+          description: Historic weekly label-printing usage
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EDILabelPrintingUsageSummary'
+              examples:
+                default:
+                  summary: Trailing weeks, most-recent first
+                  value:
+                    weeks:
+                      - weekStart: '2026-03-30T00:00:00.000Z'
+                        weekEnd: '2026-04-05T23:59:59.999Z'
+                        numConsumed: 1820
+                      - weekStart: '2026-03-23T00:00:00.000Z'
+                        weekEnd: '2026-03-29T23:59:59.999Z'
+                        numConsumed: 2410
+                disabled:
+                  summary: Label printing disabled for the account
+                  value:
+                    weeks: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/historicalMonthlyUsage:
+    get:
+      x-internal: false
+      summary: Get historical monthly entitlement usage
+      operationId: getHistoricalMonthlyUsage
+      tags:
+        - Subscription & Entitlements
+      description: |-
+        Returns historical monthly usage for accounts on flow-run pricing models (primarily platform
+        licenses). Useful for month-by-month trend analysis of usage vs. allocation.
+      responses:
+        '200':
+          description: Historical monthly usage
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/MonthlyUsage'
+              examples:
+                default:
+                  value:
+                    - month: 5
+                      year: 2025
+                      allocated:
+                        flows: 5080
+                        endpoints: 600
+                        agents: 100
+                      usage:
+                        flows: 23
+                        endpoints: 8
+                        agents: 0
+                      sandbox:
+                        allocated:
+                          flows: 0
+                          endpoints: 0
+                          agents: 0
+                        usage:
+                          flows: 0
+                          endpoints: 0
+                          agents: 0
+                    - month: 4
+                      year: 2025
+                      allocated:
+                        flows: 5080
+                        endpoints: 600
+                        agents: 100
+                        apiInvocation: 0
+                      usage:
+                        flows: 31
+                        endpoints: 16
+                        agents: 0
+                        apiInvocationCount: 0
+                        diVolume: 0
+                      sandbox:
+                        allocated:
+                          flows: 0
+                          endpoints: 0
+                          agents: 0
+                        usage:
+                          flows: 0
+                          endpoints: 0
+                          agents: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/usage:
+    get:
+      x-internal: false
+      summary: Get usage records (legacy)
+      operationId: getUsage
+      tags:
+        - Subscription & Entitlements
+      description: |-
+        Returns historical usage records for the current account (legacy usage series).
+
+        The response is an array of monthly records with a duration field (`milliseconds`).
+      responses:
+        '200':
+          description: Usage records
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/UsageRecord'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    LicenseEntitlementCounts:
+      type: object
+      description: |-
+        Entitlement counts for a given environment. For each resource type, a
+        `num*` field holds the base plan count and a `numAddOn*` field holds
+        additional capacity purchased as add-ons.
+      x-celigo-ai-guidance:
+        - |-
+          For each resource type there are two fields:
+          - `num*` — the base count included with the plan. A value of 0 means
+            the plan does not include a base allocation (the customer may still
+            have capacity via add-ons), or the limit is contract-based / unlimited.
+          - `numAddOn*` — additional capacity purchased as add-ons on top of
+            the base plan.
+      required:
+        - numEndpoints
+        - numAddOnEndpoints
+        - numFlows
+        - numAddOnFlows
+        - numAgents
+        - numAddOnAgents
+      properties:
+        numEndpoints:
+          type: integer
+          description: Base number of endpoints included with the plan.
+          example: 600
+        numAddOnEndpoints:
+          type: integer
+          description: Additional endpoints the customer purchased as add-ons.
+          example: 0
+        numFlows:
+          type: integer
+          description: Base number of flows included with the plan.
+          example: 80
+        numAddOnFlows:
+          type: integer
+          description: Additional flows the customer purchased as add-ons.
+          example: 5000
+        numTradingPartners:
+          type: integer
+          description: Base number of trading partners included with the plan.
+          example: 3
+        numAddOnTradingPartners:
+          type: integer
+          description: Additional trading partners the customer purchased as add-ons.
+          example: 0
+        numAgents:
+          type: integer
+          description: Base number of on-premise agents included with the plan.
+          example: 0
+        numAddOnAgents:
+          type: integer
+          description: Additional on-premise agents the customer purchased as add-ons.
+          example: 100
+    License:
+      type: object
+      required:
+        - _id
+        - type
+        - created
+        - lastModified
+      description: |-
+        Subscription plan or connector/Integration App license. Fields describe
+        what the plan **entitles**, not what is configured on the account.
+      x-celigo-ai-guidance:
+        - |-
+          IMPORTANT:
+          Every field on this object describes what the **plan entitles** (allows),
+          NOT what is actually configured or in use on the account.
+          For example, `sso:
+          true` means the plan includes SSO capability — it does not mean SSO is configured.
+          To know what is actually configured, use the appropriate domain tools (e.g.,
+          `get_account_settings` for SSO/MFA status).
+        - |-
+          Licenses may represent:
+          - an account-level subscription (`type` is `integrator`, `platform`, or `endpoint`)
+          - a connector-specific license (`type` is `connector`, includes `_connectorId` / `_integrationId`)
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: licenses
+          description: License identifier.
+          example: 624cb0356309dc3a543733a4
+        created:
+          type: string
+          format: date-time
+          readOnly: true
+          description: License creation timestamp.
+          example: '2022-04-05T21:10:13.226Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Last modification timestamp.
+          example: '2026-05-18T06:14:25.052Z'
+        expires:
+          type: string
+          format: date-time
+          description: License expiration timestamp.
+          example: '2099-12-31T00:00:00.000Z'
+        type:
+          type: string
+          description: License type (subscription category). Only the account-level license describes the full subscription plan.
+          example: platform
+          enum:
+            - integrator
+            - platform
+            - endpoint
+            - connector
+            - integrationApp
+            - integrationAppChild
+          x-enumDescriptions:
+            integrator: Account-level subscription (integrator pricing model).
+            platform: Account-level subscription (platform pricing model).
+            endpoint: Account-level subscription (endpoint pricing model).
+            connector: Connector-specific license for an Integration App.
+            integrationApp: Integration App license (parent).
+            integrationAppChild: Integration App child license (inherits from a parent via `_parentId`).
+        cdc:
+          type: boolean
+          description: When true, the account is licensed for CDC (change data capture) features.
+        tier:
+          type: string
+          description: Subscription tier name — the plan level the account is on.
+          x-celigo-ai-guidance:
+            - 'Examples: `free`, `standard`, `professional`, `enterprise`, `enterprise (2024)`.'
+          example: enterprise (2024)
+        supportTier:
+          type: string
+          description: Support plan level.
+          example: premier
+          enum:
+            - essential
+            - preferred
+            - premier
+          x-enumDescriptions:
+            essential: Standard support included with all plans.
+            preferred: Enhanced support with faster response times.
+            premier: Highest support tier with dedicated resources.
+        trialEndDate:
+          type: string
+          format: date-time
+          description: Trial end timestamp. Remains populated after the trial ends with the original expiration date.
+          x-celigo-ai-guidance:
+            - Trial end timestamp (present only for trial accounts).
+          example: '2024-05-06T00:00:00.000Z'
+        _connectorId:
+          type: string
+          format: objectId
+          x-celigo-refModel: connectors
+          description: Connector id. Present on `connector`, `integrationApp`, and `integrationAppChild` licenses.
+          x-celigo-ai-guidance:
+            - Connector id — present only on connector-specific licenses.
+          example: 5f8489ca15e4c824e38a769f
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: Integration id. Present on `connector`, `integrationApp`, and `integrationAppChild` licenses.
+          x-celigo-ai-guidance:
+            - Integration id — present only on connector-specific licenses.
+          example: 5f7e39a76bb8d813180a9549
+        _editionId:
+          type: string
+          format: objectId
+          description: Edition id — present on `integrationApp` and `integrationAppChild` licenses.
+          example: 60a2c4e6f321d800129a1a3c
+        _parentId:
+          type: string
+          format: objectId
+          x-celigo-refModel: licenses
+          description: Parent license id — present only on `integrationAppChild` licenses. References the parent `integrationApp` license.
+          example: 61b3d5f7e432e900130b2b4d
+        opts:
+          type: object
+          description: Connector/license options (connector edition, add-on licenses, etc.). Present only on connector-specific licenses.
+          example:
+            connectorEdition: premium
+            addonLicenses:
+              - type: store
+                licenses:
+                  - addOnEdition: premium
+        resumable:
+          type: boolean
+          readOnly: true
+          description: When true, the license/account is eligible for self-service resume after suspension.
+          example: false
+        disableOverage:
+          type: boolean
+          description: When true, overage charges are disabled for this account.
+          example: false
+        requestUserToMigrateSandbox:
+          type: boolean
+          description: When true, the user should be prompted to migrate legacy sandbox data to environments.
+          example: false
+        endpoint:
+          type: object
+          description: Entitlements for endpoint-style licenses. Present only when `type` is `endpoint`.
+          properties:
+            production:
+              $ref: '#/components/schemas/LicenseEntitlementCounts'
+            numEnvironments:
+              type: integer
+              description: Maximum number of environments the plan allows.
+              example: 5
+        integrator:
+          type: object
+          description: Entitlements for integrator-style licenses. Present only when `type` is `integrator`.
+          properties:
+            production:
+              $ref: '#/components/schemas/LicenseEntitlementCounts'
+            numEnvironments:
+              type: integer
+              description: Maximum number of environments the plan allows.
+              example: 5
+        platform:
+          type: object
+          description: Entitlements for platform-style licenses. Present only when `type` is `platform`.
+          properties:
+            production:
+              $ref: '#/components/schemas/LicenseEntitlementCounts'
+            numEnvironments:
+              type: integer
+              description: Maximum number of environments the plan allows.
+              example: 5
+            apiManagement:
+              type: boolean
+              description: When true, the platform plan includes API Management.
+              example: true
+        sso:
+          type: boolean
+          description: When true, the plan entitles the account to use SSO (Single Sign-On).
+          example: true
+        van:
+          type: boolean
+          description: When true, the plan entitles the account to use VAN (Value Added Network) for EDI.
+          example: true
+        lookupCache:
+          type: boolean
+          description: When true, the plan entitles the account to use Lookup Caches (in-memory lookups).
+          example: true
+        abstractFlows:
+          type: boolean
+          description: When true, the plan entitles the account to use Abstract Flows (multi-instance templates).
+          example: true
+        apiManagement:
+          type: boolean
+          description: When true, the plan entitles the account to use API Management (APIM).
+          example: true
+        concurrency:
+          type: integer
+          description: Maximum number of concurrent flow executions the plan allows.
+          example: 25
+        maxAllowedDataRetention:
+          type: integer
+          description: Maximum data retention period (in days) the plan allows.
+          example: 180
+        auditLogRetentionYears:
+          type: integer
+          description: Maximum audit log retention (in years) the plan allows.
+          example: 3
+        aiConversationsPrepaidBalance:
+          type: number
+          description: |-
+            Remaining prepaid credit balance for Ora (Celigo's AI assistant).
+            Customers purchase credits up front and usage costs are deducted
+            as they interact with Ora.
+          example: 47.96
+        aiAgentsPrepaidBalance:
+          type: number
+          description: |-
+            Remaining prepaid credit balance for AI Agents — LLM/AI capabilities
+            used within flows, APIs, and automations (e.g., AI-powered transforms,
+            hooks). Customers purchase credits up front and usage costs are
+            deducted as AI agents run. This balance is separate from Ora credits.
+          example: 19.62
+        aiAgentsActions:
+          type: integer
+          description: Total AI agent action entitlement for the current billing period.
+          example: 10000
+        mcp:
+          type: object
+          description: MCP (Model Context Protocol) server entitlements.
+          required:
+            - numInvocations
+          properties:
+            numInvocations:
+              type: integer
+              description: Base number of MCP server invocations per month included with the plan.
+              example: 50000
+        di:
+          type: object
+          description: Data Interchange (DI) entitlements.
+          required:
+            - enabled
+            - volume
+            - volumeAddOn
+            - disableOverage
+          properties:
+            enabled:
+              type: boolean
+              description: When true, the plan entitles the account to use Data Interchange.
+              example: false
+            volume:
+              type: integer
+              description: Base DI volume included with the plan.
+              example: 0
+            volumeAddOn:
+              type: integer
+              description: Additional DI volume the customer purchased as add-ons.
+              example: 0
+            disableOverage:
+              type: boolean
+              description: When true, Data Interchange overage charges are disabled.
+              example: false
+        api:
+          type: object
+          description: API Builder plan entitlements and invocation limits.
+          required:
+            - builder
+            - enablePricing
+            - disableOverages
+            - numInvocations
+            - apimNumInvocations
+            - numAddOnInvocations
+          properties:
+            builder:
+              type: boolean
+              description: When true, the plan entitles the account to use API Builder (building custom HTTP APIs on the Celigo platform).
+              example: true
+            enablePricing:
+              type: boolean
+              description: When true, API pricing and billing features are enabled.
+              example: false
+            disableOverages:
+              type: boolean
+              description: When true, API overage charges are disabled.
+              example: false
+            numInvocations:
+              type: integer
+              description: Base number of API calls per month included with the plan.
+              example: 0
+            apimNumInvocations:
+              type: integer
+              description: Base number of APIM API calls per month included with the plan.
+              example: 0
+            numAddOnInvocations:
+              type: integer
+              description: Additional API calls per month the customer purchased as add-ons.
+              example: 0
+        edi:
+          type: object
+          description: EDI (Electronic Data Interchange) plan entitlements.
+          required:
+            - enabled
+            - tier
+            - numTradingPartners
+            - numAddOnTradingPartners
+            - numDocumentTypes
+            - numAddOnDocumentTypes
+          properties:
+            enabled:
+              type: boolean
+              description: When true, the plan entitles the account to use EDI (B2B Manager).
+              example: true
+            onboarded:
+              type: boolean
+              description: When true, the account has completed EDI onboarding.
+              example: true
+            tier:
+              type: string
+              description: B2B Manager subscription tier.
+              x-celigo-ai-guidance:
+                - |-
+                  B2B Manager subscription tier.
+                  Determines base limits for trading partners, document types, and VAN service.
+                - |-
+                  Trading partner count is based on unique EDI Profile IDs in active flows.
+                  Document types are counted by normalized category (e.g.,
+                  all "Purchase Order" variations count as one;
+                  EDI 997 Functional Acknowledgements are excluded).
+                  Customers can purchase add-on packs for additional trading partners and document
+                  types beyond the base tier.
+              example: basic
+              enum:
+                - free
+                - basic
+                - advanced
+                - expert
+              x-enumDescriptions:
+                free: 1 trading partner, 5 document types, no VAN service.
+                basic: 3 trading partners, 5 document types, up to 1000 VDU/mo VAN.
+                advanced: 10 trading partners, 5 document types, up to 1000 VDU/mo VAN.
+                expert: 25 trading partners, 5 document types, up to 1000 VDU/mo VAN.
+            disableOverage:
+              type: boolean
+              description: When true, EDI overage charges are disabled.
+              example: false
+            numTradingPartners:
+              type: integer
+              description: Base number of EDI trading partners included with the plan.
+              example: 3
+            numAddOnTradingPartners:
+              type: integer
+              description: Additional EDI trading partners the customer purchased as add-ons.
+              example: 0
+            numDocumentTypes:
+              type: integer
+              description: Base number of EDI document types included with the plan.
+              example: 5
+            numAddOnDocumentTypes:
+              type: integer
+              description: Additional EDI document types the customer purchased as add-ons.
+              example: 0
+            labelPrinting:
+              type: object
+              description: |-
+                EDI label-printing (BarTender) entitlements. Absent when the
+                label-printing capability is unavailable platform-wide.
+              required:
+                - enabled
+                - onboarded
+                - numLabels
+                - numAddOnLabels
+              properties:
+                enabled:
+                  type: boolean
+                  description: When true, the plan entitles the account to use EDI label printing.
+                  example: true
+                onboarded:
+                  type: boolean
+                  description: When true, the account has completed label-printing onboarding.
+                  example: true
+                numLabels:
+                  type: integer
+                  description: |-
+                    Base weekly label allowance included with the plan. The effective
+                    weekly cap is `numLabels` plus `numAddOnLabels`.
+                  example: 2000
+                numAddOnLabels:
+                  type: integer
+                  description: Additional weekly label allowance the customer purchased as add-ons.
+                  example: 4000
+        logging:
+          type: object
+          description: Execution logging plan entitlements.
+          required:
+            - enabled
+            - maxLogMode
+            - maxDebugDuration
+            - maxRetentionPeriod
+          properties:
+            enabled:
+              type: boolean
+              description: When true, the plan entitles the account to use execution logging.
+              example: true
+            maxLogMode:
+              type: string
+              description: Maximum logging detail level the plan allows.
+              example: detailed
+              enum:
+                - brief
+                - detailed
+              x-enumDescriptions:
+                brief: Summary-level execution logs only.
+                detailed: Full execution logs with request/response data.
+            maxDebugDuration:
+              type: integer
+              description: Maximum time (in minutes) the plan allows a user to enable debug logging for.
+              example: 4320
+            maxRetentionPeriod:
+              type: integer
+              description: Maximum execution log retention period (in days) the plan allows.
+              example: 180
+        storage:
+          type: object
+          description: |-
+            File-storage entitlements. Always present on account-level licenses
+            (`type` is `integrator`, `endpoint`, or `platform`); absent on
+            connector and Integration App licenses.
+          required:
+            - maxAllowedUsage
+            - disableOverage
+          properties:
+            maxAllowedUsage:
+              type: number
+              minimum: 0
+              description: |-
+                Maximum file-storage usage the plan allows, in GB — the same
+                quota `GET /v1/storage/usage` reports in bytes as
+                `maxAllowedUsage`. Reported as 1 for accounts without an
+                explicit storage entitlement.
+              example: 200
+            disableOverage:
+              type: boolean
+              description: When true, file-storage overage charges are disabled.
+              example: false
+      if:
+        properties:
+          type:
+            const: platform
+      then:
+        required:
+          - platform
+      else:
+        if:
+          properties:
+            type:
+              const: integrator
+        then:
+          required:
+            - integrator
+        else:
+          if:
+            properties:
+              type:
+                const: endpoint
+          then:
+            required:
+              - endpoint
+          else:
+            if:
+              properties:
+                type:
+                  enum:
+                    - connector
+                    - integrationApp
+                    - integrationAppChild
+            then:
+              required:
+                - _connectorId
+    FlowUsage:
+      type: object
+      description: Flow entitlement usage.
+      properties:
+        numEnabled:
+          type: integer
+          description: Number of enabled flows.
+          example: 12
+        flows:
+          type: array
+          description: Flows contributing to usage.
+          x-celigo-ai-guidance:
+            - List of flows contributing to usage (if provided).
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: flows
+                description: Flow id.
+                example: 69d097584e0c505cda036df9
+              name:
+                type: string
+                description: Flow name.
+                example: HubSpot Contacts → Snowflake (Nightly)
+              isDeleted:
+                type: boolean
+                description: When true, the flow has been soft-deleted. Deleted flows may still count toward entitlement until fully purged.
+                example: false
+              integration:
+                type: object
+                description: Parent integration summary.
+                properties:
+                  _id:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: integrations
+                    description: Integration id.
+                    example: 69d0973d4e0c505cda0368d1
+                  name:
+                    type: string
+                    description: Integration name.
+                    example: POC – HubSpot → Snowflake
+    EndpointUsage:
+      type: object
+      description: Endpoint entitlement usage.
+      properties:
+        numConsumed:
+          type: integer
+          description: Number of endpoints currently consumed.
+          example: 8
+        endpoints:
+          type: array
+          description: Detailed breakdown of endpoints by type.
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                description: Endpoint adaptor type (e.g., `http`, `rdbms`, `ftp`).
+                x-celigo-ai-guidance:
+                  - Endpoint type/category.
+                example: http
+              assistant:
+                type: string
+                description: Application assistant identifier, if the connection uses a Celigo-managed application profile (e.g., `hubspot`, `netsuite`).
+                example: hubspot
+              baseURI:
+                type: string
+                description: Base URI of the connection, if applicable.
+                example: https://api.hubspot.com
+              rdbms:
+                type: object
+                description: Database connection details. Present when `type` is `rdbms`.
+                properties:
+                  type:
+                    type: string
+                    description: Database engine (e.g., `snowflake`, `mysql`, `postgresql`).
+                    example: snowflake
+                  host:
+                    type: string
+                    description: Database host or account identifier.
+                    example: celigo_partner
+              connections:
+                type: array
+                description: Connections contributing to this endpoint's usage.
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: connections
+                      description: Connection id.
+                      example: 62ac9ab6cd606e428737008e
+                    name:
+                      type: string
+                      description: Connection name.
+                      example: HubSpot (Production)
+                    isDeleted:
+                      type: boolean
+                      description: When true, the connection has been soft-deleted. Deleted connections may still count toward entitlement until fully purged.
+                      example: false
+    AgentUsage:
+      type: object
+      description: Agent entitlement usage.
+      properties:
+        numActive:
+          type: integer
+          description: Number of active agents.
+          example: 0
+        agents:
+          type: array
+          description: Agents contributing to usage.
+          x-celigo-ai-guidance:
+            - List of agents contributing to usage (if provided).
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: agents
+                description: Agent id.
+                example: 60a2c4e6f321d800129a1a3c
+              name:
+                type: string
+                description: Agent name.
+                example: On-Premise Agent 1
+    EnvironmentUsage:
+      type: object
+      description: Environment entitlement usage.
+      x-celigo-ai-guidance:
+        - Environment entitlement usage (multi-environment licensing).
+      properties:
+        numEnabled:
+          type: integer
+          description: Number of enabled environments.
+          example: 2
+        environments:
+          type: array
+          description: Environments contributing to usage.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: environments
+                description: Environment id.
+                example: 69150a05578417f9fa40dbe4
+              name:
+                type: string
+                description: Environment name.
+                example: Sandbox
+              _userId:
+                type: string
+                format: objectId
+                x-celigo-refModel: users
+                description: Owner user id.
+                example: 624cb0346309dc3a543733a2
+              _envUserId:
+                type: string
+                format: objectId
+                x-celigo-refModel: users
+                description: Environment user id.
+                example: 69150a05578417f9fa40dbe6
+              description:
+                type: string
+                description: Environment description.
+                example: ''
+              enabled:
+                type: boolean
+                description: When true, the environment is enabled and active.
+                example: true
+              createdAt:
+                type: string
+                format: date-time
+                readOnly: true
+                description: Environment creation timestamp.
+                example: '2025-11-12T22:28:22.433Z'
+              lastModified:
+                type: string
+                format: date-time
+                readOnly: true
+                description: Last modification timestamp.
+                example: '2026-05-15T23:45:40.725Z'
+    EDITradingPartnerUsage:
+      type: object
+      description: EDI trading partner entitlement usage (EDI add-on/licensing).
+      properties:
+        numConsumed:
+          type: integer
+          description: Number of EDI trading partners consumed.
+          example: 1
+        tradingPartners:
+          type: array
+          description: Trading partners contributing to usage.
+          items:
+            type: object
+            properties:
+              tradingPartnerName:
+                type: string
+                description: Trading partner display name.
+                example: Acme Corp
+              ediProfiles:
+                type: array
+                description: EDI profiles associated with this trading partner.
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: ediprofiles
+                      description: EDI profile id.
+                      example: 69014f1691348b59ebed05a9
+                    name:
+                      type: string
+                      description: EDI profile name.
+                      example: Acme EDI Profile
+    EDIDocumentTypeUsage:
+      type: object
+      description: EDI document type entitlement usage (EDI add-on/licensing).
+      properties:
+        numConsumed:
+          type: integer
+          description: Number of EDI document types consumed.
+          example: 1
+        documents:
+          type: array
+          description: Document types contributing to usage.
+          items:
+            type: object
+            properties:
+              category:
+                type: string
+                description: Normalized document type category (e.g., "Warehouse Stock Shipping Order").
+                example: Purchase Order
+              fileDefinitions:
+                type: array
+                description: File definitions in this category.
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: filedefinitions
+                      description: File definition id.
+                      example: 69014f1691348b59ebed059b
+                    name:
+                      type: string
+                      description: File definition name.
+                      example: Generic EDI 850
+    EDILabelPrintingUsage:
+      type: object
+      description: |-
+        EDI label-printing (BarTender) entitlement usage for the current billing week (Monday–Sunday UTC).
+        Present only when the account's license enables label printing; omitted entirely when label
+        printing is disabled platform-wide.
+      properties:
+        numConsumed:
+          type: integer
+          description: |-
+            Labels consumed account-wide this week, summed across every environment — this is the value
+            measured against the weekly cap. It is not necessarily the sum of `flows[].numConsumed`, since
+            `flows[]` covers only the caller's active environment.
+          example: 1542
+        flows:
+          type: array
+          description: |-
+            Per-flow label consumption for the caller's active environment only. A flow is listed here
+            only when it consumed labels this week in the environment the request is scoped to.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: flows
+                description: Flow id.
+                example: 6a25e22136b14ada888433f4
+              name:
+                type: string
+                description: Flow name. May be an empty string when the flow has been deleted.
+                example: Bartender — UPS labels
+              integration:
+                type: object
+                description: Parent integration of the flow. Every flow belongs to an integration.
+                properties:
+                  _id:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: integrations
+                    description: Integration id.
+                    example: 69d0973d4e0c505cda0368d1
+                  name:
+                    type: string
+                    description: Integration name.
+                    example: NetSuite — Acme
+              numConsumed:
+                type: integer
+                description: Labels this flow consumed this week in the caller's active environment.
+                example: 812
+    LicenseEntitlementUsage:
+      type: object
+      description: Entitlement usage information for the account/license, keyed by usage category.
+      properties:
+        flowUsage:
+          $ref: '#/components/schemas/FlowUsage'
+        endpointUsage:
+          $ref: '#/components/schemas/EndpointUsage'
+        agentUsage:
+          $ref: '#/components/schemas/AgentUsage'
+        environmentUsage:
+          $ref: '#/components/schemas/EnvironmentUsage'
+        ediTradingPartnerUsage:
+          $ref: '#/components/schemas/EDITradingPartnerUsage'
+        ediDocumentTypeUsage:
+          $ref: '#/components/schemas/EDIDocumentTypeUsage'
+        ediLabelPrintingUsage:
+          $ref: '#/components/schemas/EDILabelPrintingUsage'
+        apiUsage:
+          type: object
+          description: API invocation counts for the current billing period.
+          properties:
+            ioInvocationCount:
+              type: integer
+              description: Number of integrator.io API invocations.
+              example: 1250
+            apimInvocationCount:
+              type: integer
+              description: Number of APIM (API Management add-on) invocations.
+              example: 0
+        syncUsage:
+          type: object
+          description: Sync-volume entitlement usage.
+          properties:
+            entitlement:
+              type: integer
+              description: Provisioned sync entitlement.
+              example: 0
+            volume:
+              type: integer
+              description: Sync volume consumed against the entitlement.
+              example: 0
+        mcpUsage:
+          type: object
+          description: MCP server invocation counts.
+          properties:
+            numInvocations:
+              type: integer
+              description: Number of MCP invocations for the current period.
+              example: 340
+        aiAgentsActionsUsage:
+          type: integer
+          description: Number of AI agent actions consumed for the current period.
+          example: 87
+    EDILabelPrintingUsageSummary:
+      type: object
+      description: |-
+        Historic weekly EDI label-printing (BarTender) consumption, account-wide across all flows and
+        environments. Covers the trailing 12 ISO weeks (Monday–Sunday UTC).
+      required:
+        - weeks
+      properties:
+        weeks:
+          type: array
+          description: |-
+            Weekly totals, most-recent week first. Always dense over the 12-week window — a week with no
+            consumption is returned with `numConsumed: 0`. Empty when label printing is disabled for the
+            account.
+          items:
+            type: object
+            required:
+              - weekStart
+              - weekEnd
+              - numConsumed
+            properties:
+              weekStart:
+                type: string
+                format: date-time
+                description: Start of the ISO week, Monday 00:00:00.000 UTC.
+                example: '2026-03-30T00:00:00.000Z'
+              weekEnd:
+                type: string
+                format: date-time
+                description: End of the ISO week, Sunday 23:59:59.999 UTC.
+                example: '2026-04-05T23:59:59.999Z'
+              numConsumed:
+                type: integer
+                description: Labels consumed account-wide during the week.
+                example: 1820
+    MonthlyUsage:
+      type: object
+      description: Month-by-month usage vs allocation for a billing period.
+      properties:
+        year:
+          type: integer
+          description: Calendar year.
+          x-celigo-ai-guidance:
+            - The year of the usage data.
+          example: 2025
+        month:
+          type: integer
+          minimum: 1
+          maximum: 12
+          description: Calendar month (1-indexed — 1 = January, 12 = December).
+          x-celigo-ai-guidance:
+            - The month of the usage data (1-12).
+          example: 5
+        usage:
+          type: object
+          description: Actual usage numbers for the month.
+          properties:
+            flows:
+              type: integer
+              description: Flows in use during the month.
+              example: 23
+            endpoints:
+              type: integer
+              description: Endpoints in use during the month.
+              example: 8
+            agents:
+              type: integer
+              description: On-premise agents in use during the month.
+              example: 0
+            apiInvocationCount:
+              type: integer
+              description: API invocations consumed during the month.
+              example: 0
+            diVolume:
+              type: integer
+              description: Data Interchange volume consumed during the month.
+              example: 0
+        allocated:
+          type: object
+          description: Allocated/entitled numbers for the month.
+          properties:
+            flows:
+              type: integer
+              description: Flow allocation for the month (base plan plus add-ons).
+              example: 5080
+            endpoints:
+              type: integer
+              description: Endpoint allocation for the month (base plan plus add-ons).
+              example: 600
+            agents:
+              type: integer
+              description: On-premise agent allocation for the month (base plan plus add-ons).
+              example: 100
+            apiInvocation:
+              type: integer
+              description: API invocation allocation for the month.
+              example: 0
+    UsageRecord:
+      type: object
+      description: A monthly usage record returned by `GET /v1/usage`.
+      properties:
+        year:
+          type: integer
+          description: Calendar year.
+          example: 2025
+        month:
+          type: integer
+          minimum: 0
+          maximum: 11
+          description: Calendar month (0-indexed — 0 = January, 11 = December). Differs from `historicalMonthlyUsage` which uses 1-indexed months.
+          example: 4
+        milliseconds:
+          type: integer
+          description: Usage duration value in milliseconds (legacy metric).
+          example: 1660454
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+x-enable-proxy: true
+x-internal: false