@inklok/api-spec 7.9.2 → 7.10.0

package/openapi.yaml

@@ -8,7 +8,7 @@ info:
     Authenticate using an API key or bearer token, then use the resources below to manage
     templates, agreements, documents, and signing. For your first integration, start with
     the Quick Start guide.
-  version: "7.9.2"
+  version: "7.10.0"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -746,13 +746,108 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /v1/platform/feature-flags:
+    get:
+      operationId: listPlatformFeatureFlags
+      summary: List feature flags
+      x-internal: true
+      x-visibility: internal
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags: [Platform]
+      responses:
+        '200':
+          description: Feature flag definitions
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [featureFlags]
+                properties:
+                  featureFlags:
+                    type: array
+                    items: { $ref: '#/components/schemas/FeatureFlag' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+    post:
+      operationId: createPlatformFeatureFlag
+      summary: Create a feature flag
+      x-internal: true
+      x-visibility: internal
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags: [Platform]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/CreateFeatureFlagRequest' }
+      responses:
+        '201':
+          description: Created feature flag
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/FeatureFlag' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '409': { description: A feature flag with the key already exists }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+
+  /v1/platform/feature-flags/{key}:
+    parameters:
+      - in: path
+        name: key
+        required: true
+        schema: { type: string, pattern: '^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$' }
+    get:
+      operationId: getPlatformFeatureFlag
+      summary: Get a feature flag
+      x-internal: true
+      x-visibility: internal
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags: [Platform]
+      responses:
+        '200':
+          description: Feature flag
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/FeatureFlag' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+    patch:
+      operationId: updatePlatformFeatureFlag
+      summary: Update a feature flag
+      x-internal: true
+      x-visibility: internal
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags: [Platform]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/UpdateFeatureFlagRequest' }
+      responses:
+        '200':
+          description: Updated feature flag
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/FeatureFlag' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
+
   /platform/api-usage:
     get:
       operationId: getPlatformApiUsage
       summary: Get Platform API usage health
       x-visibility: internal
       description: |
-        Returns a small operational API usage health view for platform administrators.
+        Returns a small operational published-API usage health view for platform administrators.
+        Cognito-authenticated first-party application traffic is excluded.
         This endpoint uses existing usage counters and does not expose customer-facing analytics.
       x-required-global-roles: [PLATFORM_ADMIN]
       tags:
@@ -778,6 +873,16 @@ paths:
               - usagePercentage
             default: throttleCount
           description: Sort order for returned organizations.
+        - in: query
+          name: filter
+          schema:
+            type: string
+            enum:
+              - all
+              - throttled
+              - approaching
+            default: all
+          description: Optional status subset. Approaching means non-throttled organizations at 60% usage or higher.
         - in: query
           name: limit
           schema:
@@ -3894,6 +3999,7 @@ components:
         - orgs
         - emails
         - profile
+        - featureFlags
       properties:
         orgs:
           type: array
@@ -3912,6 +4018,50 @@ components:
               - PLATFORM_ADMIN
         profile:
           $ref: '#/components/schemas/BootstrapProfile'
+        featureFlags:
+          type: object
+          additionalProperties:
+            type: boolean
+          description: Effective feature availability for this principal; targeting and audit fields are not included.
+
+    FeatureFlag:
+      type: object
+      additionalProperties: false
+      required: [key, name, enabledForTestUsers, enabledForCustomers, enabledForApiKeys, createdAt, createdBy, updatedAt, updatedBy]
+      properties:
+        key: { type: string, pattern: '^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$' }
+        name: { type: string, minLength: 2, maxLength: 120 }
+        description: { type: string, maxLength: 1000 }
+        enabledForTestUsers: { type: boolean }
+        enabledForCustomers: { type: boolean }
+        enabledForApiKeys: { type: boolean }
+        createdAt: { type: string, format: date-time }
+        createdBy: { type: string }
+        updatedAt: { type: string, format: date-time }
+        updatedBy: { type: string }
+
+    CreateFeatureFlagRequest:
+      type: object
+      additionalProperties: false
+      required: [key, name]
+      properties:
+        key: { type: string, minLength: 2, maxLength: 80, pattern: '^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$' }
+        name: { type: string, minLength: 2, maxLength: 120 }
+        description: { type: string, maxLength: 1000 }
+        enabledForTestUsers: { type: boolean, default: false }
+        enabledForCustomers: { type: boolean, default: false }
+        enabledForApiKeys: { type: boolean, default: false }
+
+    UpdateFeatureFlagRequest:
+      type: object
+      additionalProperties: false
+      minProperties: 1
+      properties:
+        name: { type: string, minLength: 2, maxLength: 120 }
+        description: { type: string, nullable: true, maxLength: 1000 }
+        enabledForTestUsers: { type: boolean }
+        enabledForCustomers: { type: boolean }
+        enabledForApiKeys: { type: boolean }
 
     MeBillingSubscription:
       type: object
@@ -5069,10 +5219,13 @@ components:
       required:
         - window
         - sort
+        - filter
         - limit
         - nextCursor
         - organizations
         - totalOrganizations
+        - totalThrottledOrganizations
+        - totalApproachingLimitOrganizations
         - dataSource
         - generatedAt
       properties:
@@ -5088,6 +5241,12 @@ components:
           enum:
             - throttleCount
             - usagePercentage
+        filter:
+          type: string
+          enum:
+            - all
+            - throttled
+            - approaching
         limit:
           type: integer
           minimum: 1
@@ -5101,6 +5260,12 @@ components:
         totalOrganizations:
           type: integer
           minimum: 0
+        totalThrottledOrganizations:
+          type: integer
+          minimum: 0
+        totalApproachingLimitOrganizations:
+          type: integer
+          minimum: 0
         dataSource:
           type: object
           required:
@@ -5125,9 +5290,9 @@ components:
               enum:
                 - peak_minute
                 - daily_capacity
-      generatedAt:
-        type: string
-        format: date-time
+        generatedAt:
+          type: string
+          format: date-time
 
     PlatformBillingActivityType:
       type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklok/api-spec",
-  "version": "7.9.2",
+  "version": "7.10.0",
   "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
   "license": "MIT",