@inklok/api-spec 7.6.0 → 7.6.2

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.6.0"
+  version: "7.6.2"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -435,6 +435,19 @@ paths:
           schema:
             type: string
           description: Organization name or identifier search.
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+          description: Maximum number of organizations to return for browse/search results.
+        - in: query
+          name: cursor
+          schema:
+            type: string
+          description: Opaque pagination cursor returned by the previous response.
       responses:
         '200':
           description: Successfully retrieved Platform entitlement information
@@ -491,6 +504,65 @@ paths:
         '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.
+        This endpoint uses existing usage counters and does not expose customer-facing analytics.
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags:
+        - Platform
+      parameters:
+        - in: query
+          name: window
+          schema:
+            type: string
+            enum:
+              - 1h
+              - 24h
+              - 7d
+              - 30d
+            default: 24h
+          description: Usage window to inspect.
+        - in: query
+          name: sort
+          schema:
+            type: string
+            enum:
+              - throttleCount
+              - usagePercentage
+            default: throttleCount
+          description: Sort order for returned organizations.
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+          description: Maximum number of organizations to return.
+        - in: query
+          name: cursor
+          schema:
+            type: string
+          description: Opaque pagination cursor returned by the previous response.
+      responses:
+        '200':
+          description: Successfully retrieved Platform API usage health
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformApiUsageResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
   /platform/ses:
     get:
       operationId: getPlatformSes
@@ -4074,6 +4146,8 @@ components:
         - accountId
         - isPersonal
         - createdAt
+        - sandboxForOrgId
+        - entitlement
       properties:
         orgId:
           type: string
@@ -4093,6 +4167,55 @@ components:
         createdAt:
           type: string
           format: date-time
+        sandboxForOrgId:
+          type: string
+          nullable: true
+        entitlement:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/PlatformEntitlementOrganizationSummary'
+
+    PlatformEntitlementOrganizationSummary:
+      type: object
+      required:
+        - plan
+        - subscriptionStatus
+        - source
+        - includedSeats
+        - additionalSeats
+        - effectiveSeatLimit
+        - maxApiRequestsPerMinute
+        - hasCustomSeatOverride
+        - hasCustomApiLimit
+      properties:
+        plan:
+          $ref: '#/components/schemas/PlatformPlan'
+        subscriptionStatus:
+          type: string
+        source:
+          type: string
+          enum:
+            - stored
+            - plan-default
+        includedSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        additionalSeats:
+          type: integer
+          minimum: 0
+        effectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        maxApiRequestsPerMinute:
+          type: integer
+          nullable: true
+          minimum: 0
+        hasCustomSeatOverride:
+          type: boolean
+        hasCustomApiLimit:
+          type: boolean
 
     PlatformEntitlementSeats:
       type: object
@@ -4225,6 +4348,7 @@ components:
       required:
         - organizations
         - selected
+        - nextCursor
         - generatedAt
       properties:
         organizations:
@@ -4235,6 +4359,9 @@ components:
           nullable: true
           allOf:
             - $ref: '#/components/schemas/PlatformEntitlementDetail'
+        nextCursor:
+          type: string
+          nullable: true
         generatedAt:
           type: string
           format: date-time
@@ -4252,6 +4379,191 @@ components:
           minimum: 0
           description: Enterprise custom included seat value. Ignored for non-Enterprise plans.
 
+    PlatformApiUsagePolicySummary:
+      type: object
+      required:
+        - totalApiRequests
+        - throttleCount
+        - configuredLimit
+        - peakUsage
+        - usagePercentage
+      properties:
+        totalApiRequests:
+          type: integer
+          minimum: 0
+        throttleCount:
+          type: integer
+          minimum: 0
+        configuredLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        peakUsage:
+          type: integer
+          minimum: 0
+        usagePercentage:
+          type: number
+          nullable: true
+          minimum: 0
+
+    PlatformApiUsageCategorySummary:
+      type: object
+      required:
+        - totalApiRequests
+        - throttleCount
+        - peakUsage
+      properties:
+        totalApiRequests:
+          type: integer
+          minimum: 0
+        throttleCount:
+          type: integer
+          minimum: 0
+        peakUsage:
+          type: integer
+          minimum: 0
+
+    PlatformApiUsageOrganization:
+      type: object
+      required:
+        - orgId
+        - organizationName
+        - accountId
+        - plan
+        - totalApiRequests
+        - throttleCount
+        - configuredApiLimit
+        - peakUsage
+        - usagePercentage
+        - lastRequestAt
+        - lastThrottleAt
+        - status
+        - breakdown
+      properties:
+        orgId:
+          type: string
+        organizationName:
+          type: string
+          nullable: true
+        accountId:
+          type: string
+          nullable: true
+        plan:
+          $ref: '#/components/schemas/Plan'
+        totalApiRequests:
+          type: integer
+          minimum: 0
+        throttleCount:
+          type: integer
+          minimum: 0
+        configuredApiLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        peakUsage:
+          type: integer
+          minimum: 0
+        usagePercentage:
+          type: number
+          nullable: true
+          minimum: 0
+        lastRequestAt:
+          type: string
+          nullable: true
+          format: date-time
+        lastThrottleAt:
+          type: string
+          nullable: true
+          format: date-time
+        status:
+          type: string
+          enum:
+            - THROTTLED
+            - NEAR_LIMIT
+            - WATCH
+            - OK
+        breakdown:
+          type: object
+          required:
+            - publishedApi
+            - firstParty
+            - production
+            - sandbox
+          properties:
+            publishedApi:
+              $ref: '#/components/schemas/PlatformApiUsagePolicySummary'
+            firstParty:
+              $ref: '#/components/schemas/PlatformApiUsagePolicySummary'
+            production:
+              $ref: '#/components/schemas/PlatformApiUsageCategorySummary'
+            sandbox:
+              $ref: '#/components/schemas/PlatformApiUsageCategorySummary'
+
+    PlatformApiUsageResponse:
+      type: object
+      required:
+        - window
+        - sort
+        - limit
+        - nextCursor
+        - organizations
+        - totalOrganizations
+        - dataSource
+        - generatedAt
+      properties:
+        window:
+          type: string
+          enum:
+            - 1h
+            - 24h
+            - 7d
+            - 30d
+        sort:
+          type: string
+          enum:
+            - throttleCount
+            - usagePercentage
+        limit:
+          type: integer
+          minimum: 1
+        nextCursor:
+          type: string
+          nullable: true
+        organizations:
+          type: array
+          items:
+            $ref: '#/components/schemas/PlatformApiUsageOrganization'
+        totalOrganizations:
+          type: integer
+          minimum: 0
+        dataSource:
+          type: object
+          required:
+            - table
+            - rollupTableUsed
+            - precision
+            - usagePercentageBasis
+          properties:
+            table:
+              type: string
+              enum:
+                - usage-counters
+            rollupTableUsed:
+              type: boolean
+            precision:
+              type: string
+              enum:
+                - minute
+                - day
+            usagePercentageBasis:
+              type: string
+              enum:
+                - peak_minute
+                - daily_capacity
+        generatedAt:
+          type: string
+          format: date-time
+
     PlatformCostsResponse:
       type: object
       required:

package/package.json

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