add spec

Author: Flo4604

svc/api/openapi/gen.go

@@ -21,21 +21,26 @@ components:
             scheme: bearer
             type: http
     schemas:
-        ChproxyMetricsRequestBody:
-            type: array
-            description: Array of API request metric events to be processed
-            items:
-                type: object
-                additionalProperties: true
-        ChproxyMetricsResponseBody:
+        CacheInvalidateRequestBody:
             type: object
             required:
-                - status
+                - cacheName
+                - keys
             properties:
-                status:
+                cacheName:
                     type: string
-                    description: Processing status
-                    example: "OK"
+                    description: The name of the cache to invalidate entries from. Must match a registered cache resource name.
+                    example: "verification_key_by_hash"
+                keys:
+                    type: array
+                    minItems: 1
+                    description: |-
+                        The cache keys to invalidate. For string-keyed caches (verification_key_by_hash,
+                        clickhouse_setting), pass the raw key values. For scoped-key caches (live_api_by_id,
+                        ratelimit_namespace, etc.), pass keys in "workspaceId:resourceId" format.
+                    items:
+                        type: string
+                    example: ["abc123"]
         BadRequestErrorResponse:
             type: object
             required:
@@ -47,6 +52,23 @@ components:
                 error:
                     $ref: "#/components/schemas/BadRequestErrorDetails"
             description: Error response for invalid requests that cannot be processed due to client-side errors. This typically occurs when request parameters are missing, malformed, or fail validation rules. The response includes detailed information about the specific errors in the request, including the location of each error and suggestions for fixing it. When receiving this error, check the 'errors' array in the response for specific validation issues that need to be addressed before retrying.
+        UnauthorizedErrorResponse:
+            type: object
+            required:
+                - meta
+                - error
+            properties:
+                meta:
+                    $ref: "#/components/schemas/Meta"
+                error:
+                    $ref: "#/components/schemas/BaseError"
+            description: |-
+                Error response when authentication has failed or credentials are missing. This occurs when:
+                - No authentication token is provided in the request
+                - The provided token is invalid, expired, or malformed
+                - The token format doesn't match expected patterns
+
+                To resolve this error, ensure you're including a valid root key in the Authorization header.
         InternalServerErrorResponse:
             type: object
             required:
@@ -64,6 +86,21 @@ components:
                 - The request ID in the response can help Unkey support investigate the issue
                 - The error is likely temporary and retrying may succeed
                 - If the error persists, contact Unkey support with the request ID
+        ChproxyMetricsRequestBody:
+            type: array
+            description: Array of API request metric events to be processed
+            items:
+                type: object
+                additionalProperties: true
+        ChproxyMetricsResponseBody:
+            type: object
+            required:
+                - status
+            properties:
+                status:
+                    type: string
+                    description: Processing status
+                    example: "OK"
         ChproxyRatelimitsRequestBody:
             type: array
             description: Array of ratelimit events to be processed
@@ -115,23 +152,6 @@ components:
                     $ref: "#/components/schemas/Meta"
                 data:
                     $ref: "#/components/schemas/V2AnalyticsGetVerificationsResponseData"
-        UnauthorizedErrorResponse:
-            type: object
-            required:
-                - meta
-                - error
-            properties:
-                meta:
-                    $ref: "#/components/schemas/Meta"
-                error:
-                    $ref: "#/components/schemas/BaseError"
-            description: |-
-                Error response when authentication has failed or credentials are missing. This occurs when:
-                - No authentication token is provided in the request
-                - The provided token is invalid, expired, or malformed
-                - The token format doesn't match expected patterns
-
-                To resolve this error, ensure you're including a valid root key in the Authorization header.
         ForbiddenErrorResponse:
             type: object
             required:
@@ -3751,6 +3771,52 @@ info:
     version: 2.0.0
 openapi: 3.1.0
 paths:
+    /_internal/cache.invalidate:
+        post:
+            description: |-
+                Internal endpoint for invalidating cached entries across all API nodes.
+                Used by the dashboard to notify the API after mutations so stale cache
+                entries are evicted immediately rather than waiting for TTL expiry.
+
+                Invalidation is propagated to all cluster nodes via gossip when clustering
+                is enabled.
+
+                This endpoint requires a dedicated bearer token and should not be used by
+                external clients.
+            operationId: internalCacheInvalidate
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/CacheInvalidateRequestBody'
+                required: true
+            responses:
+                "200":
+                    description: Cache entries successfully invalidated
+                "400":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/BadRequestErrorResponse'
+                    description: Invalid request body, missing cacheName or keys
+                "401":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/UnauthorizedErrorResponse'
+                    description: Missing or invalid bearer token
+                "529":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/InternalServerErrorResponse'
+                    description: Failed to invalidate cache entries
+            security: []
+            summary: Invalidate cache entries
+            tags:
+                - internal
+            x-excluded: true
+            x-speakeasy-ignore: true
     /_internal/chproxy/metrics:
         post:
             description: |-

svc/api/openapi/openapi-generated.yaml

@@ -217,6 +217,10 @@ paths:
   /v2/permissions.deletePermission:
     $ref: "./spec/paths/v2/permissions/deletePermission/index.yaml"
 
+  # Cache Invalidation (Internal)
+  /_internal/cache.invalidate:
+    $ref: "./spec/paths/internal/cache_invalidate/index.yaml"
+
   # ClickHouse Proxy Endpoints (Internal)
   /_internal/chproxy/verifications:
     $ref: "./spec/paths/chproxy/verifications/index.yaml"

svc/api/openapi/openapi-split.yaml

@@ -0,0 +1,19 @@
+type: object
+required:
+  - cacheName
+  - keys
+properties:
+  cacheName:
+    type: string
+    description: The name of the cache to invalidate entries from. Must match a registered cache resource name.
+    example: "verification_key_by_hash"
+  keys:
+    type: array
+    minItems: 1
+    description: |-
+      The cache keys to invalidate. For string-keyed caches (verification_key_by_hash,
+      clickhouse_setting), pass the raw key values. For scoped-key caches (live_api_by_id,
+      ratelimit_namespace, etc.), pass keys in "workspaceId:resourceId" format.
+    items:
+      type: string
+    example: ["abc123"]

svc/api/openapi/spec/paths/internal/cache_invalidate/CacheInvalidateRequestBody.yaml

@@ -0,0 +1,45 @@
+post:
+  x-speakeasy-ignore: true
+  x-excluded: true
+  tags:
+    - internal
+  security: []
+  operationId: internalCacheInvalidate
+  summary: Invalidate cache entries
+  description: |-
+    Internal endpoint for invalidating cached entries across all API nodes.
+    Used by the dashboard to notify the API after mutations so stale cache
+    entries are evicted immediately rather than waiting for TTL expiry.
+
+    Invalidation is propagated to all cluster nodes via gossip when clustering
+    is enabled.
+
+    This endpoint requires a dedicated bearer token and should not be used by
+    external clients.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          "$ref": "./CacheInvalidateRequestBody.yaml"
+  responses:
+    "200":
+      description: Cache entries successfully invalidated
+    "400":
+      content:
+        application/json:
+          schema:
+            $ref: "../../../error/BadRequestErrorResponse.yaml"
+      description: Invalid request body, missing cacheName or keys
+    "401":
+      content:
+        application/json:
+          schema:
+            $ref: "../../../error/UnauthorizedErrorResponse.yaml"
+      description: Missing or invalid bearer token
+    "529":
+      content:
+        application/json:
+          schema:
+            $ref: "../../../error/InternalServerErrorResponse.yaml"
+      description: Failed to invalidate cache entries