@unkey/api 2.0.0-alpha.7 → 2.0.1

package/src/mcp-server/tools/keysUpdateKey.ts

@@ -0,0 +1,52 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { keysUpdateKey } from "../../funcs/keysUpdateKey.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2KeysUpdateKeyRequestBody$inboundSchema,
+};
+
+export const tool$keysUpdateKey: ToolDefinition<typeof args> = {
+  name: "keys-update-key",
+  description: `Update key settings
+
+Update key properties in response to plan changes, subscription updates, or account status changes.
+
+Use this for user upgrades/downgrades, role modifications, or administrative changes. Supports partial updates - only specify fields you want to change. Set fields to null to clear them.
+
+**Important**: Permissions and roles are replaced entirely. Use dedicated add/remove endpoints for incremental changes.
+
+**Required Permissions**
+
+Your root key must have one of the following permissions:
+- \`api.*.update_key\` (to update keys in any API)
+- \`api.<api_id>.update_key\` (to update keys in a specific API)
+
+**Side Effects**
+
+If you specify an \`externalId\` that doesn't exist, a new identity will be automatically created and linked to the key. Permission updates will auto-create any permissions that don't exist in your workspace. Changes take effect immediately but may take up to 30 seconds to propagate to all edge regions due to cache invalidation.
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await keysUpdateKey(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/keysVerifyKey.ts

@@ -0,0 +1,55 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { keysVerifyKey } from "../../funcs/keysVerifyKey.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2KeysVerifyKeyRequestBody$inboundSchema,
+};
+
+export const tool$keysVerifyKey: ToolDefinition<typeof args> = {
+  name: "keys-verify-key",
+  description: `Verify API key
+
+Verify an API key's validity and permissions for request authentication.
+
+Use this endpoint on every incoming request to your protected resources. It checks key validity, permissions, rate limits, and usage quotas in a single call.
+
+**Important**: Always returns HTTP 200. Check the \`valid\` field in response data to determine if the key is authorized.
+
+**Common use cases:**
+- Authenticate API requests before processing
+- Enforce permission-based access control
+- Track usage and apply rate limits
+
+**Required Permissions**
+
+Your root key needs one of:
+- \`api.*.verify_key\` (verify keys in any API)
+- \`api.<api_id>.verify_key\` (verify keys in specific API)
+
+If you are getting a NOT_FOUND error, ensure your root key has the required verify key permissions.
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await keysVerifyKey(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/keysWhoami.ts

@@ -0,0 +1,46 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { keysWhoami } from "../../funcs/keysWhoami.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2KeysWhoamiRequestBody$inboundSchema,
+};
+
+export const tool$keysWhoami: ToolDefinition<typeof args> = {
+  name: "keys-whoami",
+  description: `Get API key by hash
+
+Find out what key this is.
+
+**Required Permissions**
+
+Your root key must have one of the following permissions for basic key information:
+- \`api.*.read_key\` (to read keys from any API)
+- \`api.<api_id>.read_key\` (to read keys from a specific API)
+
+If your rootkey lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existance of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your root key has the correct permissions.
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await keysWhoami(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/permissionsCreatePermission.ts

@@ -0,0 +1,47 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { permissionsCreatePermission } from "../../funcs/permissionsCreatePermission.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2PermissionsCreatePermissionRequestBody$inboundSchema,
+};
+
+export const tool$permissionsCreatePermission: ToolDefinition<typeof args> = {
+  name: "permissions-create-permission",
+  description: `Create permission
+
+Create a new permission to define specific actions or capabilities in your RBAC system. Permissions can be assigned directly to API keys or included in roles.
+
+Use hierarchical naming patterns like \`documents.read\`, \`admin.users.delete\`, or \`billing.invoices.create\` for clear organization.
+
+**Important:** Permission names must be unique within the workspace. Once created, permissions are immediately available for assignment.
+
+**Required Permissions**
+
+Your root key must have the following permission:
+- \`rbac.*.create_permission\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await permissionsCreatePermission(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/permissionsCreateRole.ts

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { permissionsCreateRole } from "../../funcs/permissionsCreateRole.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2PermissionsCreateRoleRequestBody$inboundSchema,
+};
+
+export const tool$permissionsCreateRole: ToolDefinition<typeof args> = {
+  name: "permissions-create-role",
+  description: `Create role
+
+Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys.
+
+**Important:** Role names must be unique within the workspace. Once created, roles are immediately available for assignment.
+
+**Required Permissions**
+
+Your root key must have the following permission:
+- \`rbac.*.create_role\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await permissionsCreateRole(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/permissionsDeletePermission.ts

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { permissionsDeletePermission } from "../../funcs/permissionsDeletePermission.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2PermissionsDeletePermissionRequestBody$inboundSchema,
+};
+
+export const tool$permissionsDeletePermission: ToolDefinition<typeof args> = {
+  name: "permissions-delete-permission",
+  description: `Delete permission
+
+Remove a permission from your workspace. This also removes the permission from all API keys and roles.
+
+**Important:** This operation cannot be undone and immediately affects all API keys and roles that had this permission assigned.
+
+**Required Permissions**
+
+Your root key must have the following permission:
+- \`rbac.*.delete_permission\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await permissionsDeletePermission(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/permissionsDeleteRole.ts

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { permissionsDeleteRole } from "../../funcs/permissionsDeleteRole.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2PermissionsDeleteRoleRequestBody$inboundSchema,
+};
+
+export const tool$permissionsDeleteRole: ToolDefinition<typeof args> = {
+  name: "permissions-delete-role",
+  description: `Delete role
+
+Remove a role from your workspace. This also removes the role from all assigned API keys.
+
+**Important:** This operation cannot be undone and immediately affects all API keys that had this role assigned.
+
+**Required Permissions**
+
+Your root key must have the following permission:
+- \`rbac.*.delete_role\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await permissionsDeleteRole(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/permissionsGetPermission.ts

@@ -0,0 +1,43 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { permissionsGetPermission } from "../../funcs/permissionsGetPermission.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2PermissionsGetPermissionRequestBody$inboundSchema,
+};
+
+export const tool$permissionsGetPermission: ToolDefinition<typeof args> = {
+  name: "permissions-get-permission",
+  description: `Get permission
+
+Retrieve details about a specific permission including its name, description, and metadata.
+
+**Required Permissions**
+
+Your root key must have the following permission:
+- \`rbac.*.read_permission\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await permissionsGetPermission(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/permissionsGetRole.ts

@@ -0,0 +1,43 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { permissionsGetRole } from "../../funcs/permissionsGetRole.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2PermissionsGetRoleRequestBody$inboundSchema,
+};
+
+export const tool$permissionsGetRole: ToolDefinition<typeof args> = {
+  name: "permissions-get-role",
+  description: `Get role
+
+Retrieve details about a specific role including its assigned permissions.
+
+**Required Permissions**
+
+Your root key must have the following permission:
+- \`rbac.*.read_role\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await permissionsGetRole(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/permissionsListPermissions.ts

@@ -0,0 +1,43 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { permissionsListPermissions } from "../../funcs/permissionsListPermissions.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2PermissionsListPermissionsRequestBody$inboundSchema,
+};
+
+export const tool$permissionsListPermissions: ToolDefinition<typeof args> = {
+  name: "permissions-list-permissions",
+  description: `List permissions
+
+Retrieve all permissions in your workspace. Results are paginated and sorted alphabetically by permission name.
+
+**Required Permissions**
+
+Your root key must have the following permission:
+- \`rbac.*.read_permission\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await permissionsListPermissions(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/permissionsListRoles.ts

@@ -0,0 +1,43 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { permissionsListRoles } from "../../funcs/permissionsListRoles.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2PermissionsListRolesRequestBody$inboundSchema,
+};
+
+export const tool$permissionsListRoles: ToolDefinition<typeof args> = {
+  name: "permissions-list-roles",
+  description: `List roles
+
+Retrieve all roles in your workspace including their assigned permissions. Results are paginated and sorted alphabetically by role name.
+
+**Required Permissions**
+
+Your root key must have the following permission:
+- \`rbac.*.read_role\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await permissionsListRoles(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/ratelimitDeleteOverride.ts

@@ -12,7 +12,16 @@ const args = {
 
 export const tool$ratelimitDeleteOverride: ToolDefinition<typeof args> = {
   name: "ratelimit-delete-override",
-  description: ``,
+  description: `Delete ratelimit override
+
+Permanently remove a rate limit override. Affected identifiers immediately revert to the namespace default.
+
+Use this to remove temporary overrides, reset identifiers to standard limits, or clean up outdated rules.
+
+**Important:** Deletion is immediate and permanent. The override cannot be recovered and must be recreated if needed again.
+
+**Permissions:** Requires \`ratelimit.*.delete_override\` or \`ratelimit.<namespace_id>.delete_override\`
+`,
   args,
   tool: async (client, args, ctx) => {
     const [result, apiCall] = await ratelimitDeleteOverride(

package/src/mcp-server/tools/ratelimitGetOverride.ts

@@ -12,7 +12,16 @@ const args = {
 
 export const tool$ratelimitGetOverride: ToolDefinition<typeof args> = {
   name: "ratelimit-get-override",
-  description: ``,
+  description: `Get ratelimit override
+
+Retrieve the configuration of a specific rate limit override by its identifier.
+
+Use this to inspect override configurations, audit rate limiting policies, or debug rate limiting behavior.
+
+**Important:** The identifier must match exactly as specified when creating the override, including wildcard patterns.
+
+**Permissions:** Requires \`ratelimit.*.read_override\` or \`ratelimit.<namespace_id>.read_override\`
+`,
   args,
   tool: async (client, args, ctx) => {
     const [result, apiCall] = await ratelimitGetOverride(

package/src/mcp-server/tools/ratelimitLimit.ts

@@ -12,7 +12,24 @@ const args = {
 
 export const tool$ratelimitLimit: ToolDefinition<typeof args> = {
   name: "ratelimit-limit",
-  description: ``,
+  description: `Apply rate limiting
+
+Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.).
+
+Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports namespace organization, variable costs, and custom overrides.
+
+**Important**: Always returns HTTP 200. Check the \`success\` field to determine if the request should proceed.
+
+**Required Permissions**
+
+Your root key must have one of the following permissions:
+- \`ratelimit.*.limit\` (to check limits in any namespace)
+- \`ratelimit.<namespace_id>.limit\` (to check limits in a specific namespace)
+
+**Side Effects**
+
+Records rate limit metrics for analytics and monitoring, updates rate limit counters with sliding window algorithm, and optionally triggers override matching for custom limits.
+`,
   args,
   tool: async (client, args, ctx) => {
     const [result, apiCall] = await ratelimitLimit(

package/src/mcp-server/tools/ratelimitListOverrides.ts

@@ -12,7 +12,16 @@ const args = {
 
 export const tool$ratelimitListOverrides: ToolDefinition<typeof args> = {
   name: "ratelimit-list-overrides",
-  description: ``,
+  description: `List ratelimit overrides
+
+Retrieve a paginated list of all rate limit overrides in a namespace.
+
+Use this to audit rate limiting policies, build admin dashboards, or manage override configurations.
+
+**Important:** Results are paginated. Use the cursor parameter to retrieve additional pages when more results are available.
+
+**Permissions:** Requires \`ratelimit.*.read_override\` or \`ratelimit.<namespace_id>.read_override\`
+`,
   args,
   tool: async (client, args, ctx) => {
     const [result, apiCall] = await ratelimitListOverrides(

package/src/mcp-server/tools/ratelimitSetOverride.ts

@@ -12,7 +12,16 @@ const args = {
 
 export const tool$ratelimitSetOverride: ToolDefinition<typeof args> = {
   name: "ratelimit-set-override",
-  description: ``,
+  description: `Set ratelimit override
+
+Create or update a custom rate limit for specific identifiers, bypassing the namespace default.
+
+Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling.
+
+**Important:** Overrides take effect immediately and completely replace the default limit for matching identifiers. Use wildcard patterns (e.g., \`premium_*\`) to match multiple identifiers.
+
+**Permissions:** Requires \`ratelimit.*.set_override\` or \`ratelimit.<namespace_id>.set_override\`
+`,
   args,
   tool: async (client, args, ctx) => {
     const [result, apiCall] = await ratelimitSetOverride(

package/src/models/components/badrequesterrordetails.ts

@@ -13,29 +13,28 @@ import {
   ValidationError$outboundSchema,
 } from "./validationerror.js";
 
+/**
+ * Extended error details specifically for bad request (400) errors. This builds on the BaseError structure by adding an array of individual validation errors, making it easy to identify and fix multiple issues at once.
+ */
 export type BadRequestErrorDetails = {
   /**
-   * A human-readable explanation specific to this occurrence of the problem.
+   * A human-readable explanation specific to this occurrence of the problem. This provides detailed information about what went wrong and potential remediation steps. The message is intended to be helpful for developers troubleshooting the issue.
    */
   detail: string;
   /**
-   * A URI reference that identifies the specific occurrence of the problem.
-   */
-  instance?: string | undefined;
-  /**
-   * HTTP status code
+   * HTTP status code that corresponds to this error. This will match the status code in the HTTP response. Common codes include `400` (Bad Request), `401` (Unauthorized), `403` (Forbidden), `404` (Not Found), `409` (Conflict), and `500` (Internal Server Error).
    */
   status: number;
   /**
-   * A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
+   * A short, human-readable summary of the problem type. This remains constant from occurrence to occurrence of the same problem and should be used for programmatic handling.
    */
   title: string;
   /**
-   * A URI reference to human-readable documentation for the error.
+   * A URI reference that identifies the problem type. This provides a stable identifier for the error that can be used for documentation lookups and programmatic error handling. When followed, this URI should provide human-readable documentation for the problem type.
    */
   type: string;
   /**
-   * Optional list of individual error details
+   * List of individual validation errors that occurred in the request. Each error provides specific details about what failed validation, where the error occurred in the request, and suggestions for fixing it. This granular information helps developers quickly identify and resolve multiple issues in a single request without having to make repeated API calls.
    */
   errors: Array<ValidationError>;
 };
@@ -47,7 +46,6 @@ export const BadRequestErrorDetails$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   detail: z.string(),
-  instance: z.string().optional(),
   status: z.number().int(),
   title: z.string(),
   type: z.string(),
@@ -57,7 +55,6 @@ export const BadRequestErrorDetails$inboundSchema: z.ZodType<
 /** @internal */
 export type BadRequestErrorDetails$Outbound = {
   detail: string;
-  instance?: string | undefined;
   status: number;
   title: string;
   type: string;
@@ -71,7 +68,6 @@ export const BadRequestErrorDetails$outboundSchema: z.ZodType<
   BadRequestErrorDetails
 > = z.object({
   detail: z.string(),
-  instance: z.string().optional(),
   status: z.number().int(),
   title: z.string(),
   type: z.string(),