How to fix: On each tool, declare annotations.readOnlyHint, annotations.destructiveHint, and annotations.openWorldHint as booleans. The policy review separately assesses whether their values match the tool's actual behavior.
Shorten the title to an action and subject; move usage details into the description.
Description71/100
A query can use only the public alias `gateway_requests_v1`. CTEs, subqueries, UNION, and EXCEPT are permitted.
The root key must have the `project.*.read_gateway_requests` permission.
Unkey limits each query to the workspace of the root key. To get the data for one project, app, or environment, add a filter on `project_id`, `app_id`, or `environment_id`.
The workspace retention period and the workspace query limits apply.
For the columns and more query examples, see the gateway request analytics documentation.
The description explains the capability, when to use it, and what to expect.
Inputs74/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
The SQL query to run on your gateway request data.
A query can use only the public alias `gateway_requests_v1`. The physical `default.*` table names are not permitted.
Only SELECT queries are permitted. CTEs, subqueries, UNION, and EXCEPT are also permitted.
Unkey limits each query to the workspace of the root key. To get the data for one project, app, or environment, add a filter on `project_id`, `app_id`, or `environment_id`.
The workspace retention period and the workspace query limits apply.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_analytics_get_gateway_requests",
"title": "Query gateway request data",
"description": "A query can use only the public alias `gateway_requests_v1`. CTEs, subqueries, UNION, and EXCEPT are permitted.\nThe root key must have the `project.*.read_gateway_requests` permission.\nUnkey limits each query to the workspace of the root key. To get the data for one project, app, or environment, add a filter on `project_id`, `app_id`, or `environment_id`.\nThe workspace retention period and the workspace query limits apply.\nFor the columns and more query examples, see the gateway request analytics documentation.\n",
"inputSchema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "The SQL query to run on your gateway request data.\nA query can use only the public alias `gateway_requests_v1`. The physical `default.*` table names are not permitted.\nOnly SELECT queries are permitted. CTEs, subqueries, UNION, and EXCEPT are also permitted.\nUnkey limits each query to the workspace of the root key. To get the data for one project, app, or environment, add a filter on `project_id`, `app_id`, or `environment_id`.\nThe workspace retention period and the workspace query limits apply.\n"
}
}
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description70/100
Queries may reference only the five public rate limit analytics aliases: `ratelimits_v1`, `ratelimits_per_minute_v1`, `ratelimits_per_hour_v1`, `ratelimits_per_day_v1`, or `ratelimits_per_month_v1`. CTEs, subqueries, UNION, and EXCEPT are supported.
Queries are always restricted to the authenticated workspace. Wildcard analytics permission can read every namespace in that workspace; namespace-scoped permissions automatically restrict results to the permitted namespace IDs.
Workspace retention and query limits apply.
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
SQL query to execute against your rate limit analytics data.
Queries may reference only the five public aliases: `ratelimits_v1`, `ratelimits_per_minute_v1`, `ratelimits_per_hour_v1`, `ratelimits_per_day_v1`, or `ratelimits_per_month_v1`. Physical `default.*` table names are unsupported. CTEs, subqueries, UNION, and EXCEPT are supported.
Queries are always restricted to the authenticated workspace. Wildcard analytics permission can read every namespace in that workspace; namespace-scoped permissions automatically restrict results to the permitted namespace IDs.
Workspace retention and query limits apply.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_analytics_get_ratelimits",
"title": "Query rate limit data",
"description": "Queries may reference only the five public rate limit analytics aliases: `ratelimits_v1`, `ratelimits_per_minute_v1`, `ratelimits_per_hour_v1`, `ratelimits_per_day_v1`, or `ratelimits_per_month_v1`. CTEs, subqueries, UNION, and EXCEPT are supported.\nQueries are always restricted to the authenticated workspace. Wildcard analytics permission can read every namespace in that workspace; namespace-scoped permissions automatically restrict results to the permitted namespace IDs.\nWorkspace retention and query limits apply.\n",
"inputSchema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "SQL query to execute against your rate limit analytics data.\nQueries may reference only the five public aliases: `ratelimits_v1`, `ratelimits_per_minute_v1`, `ratelimits_per_hour_v1`, `ratelimits_per_day_v1`, or `ratelimits_per_month_v1`. Physical `default.*` table names are unsupported. CTEs, subqueries, UNION, and EXCEPT are supported.\nQueries are always restricted to the authenticated workspace. Wildcard analytics permission can read every namespace in that workspace; namespace-scoped permissions automatically restrict results to the permitted namespace IDs.\nWorkspace retention and query limits apply.\n"
}
}
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description75/100
A query can use only the public alias `runtime_logs_v1`. CTEs, subqueries, UNION, and EXCEPT are permitted.
The root key must have the `project.*.read_runtime_logs` permission.
Unkey limits each query to the workspace of the root key. To get the logs of one project, app, environment, or deployment, add a filter on `project_id`, `app_id`, `environment_id`, or `deployment_id`.
The workspace retention period and the workspace query limits apply.
For the table, the columns, and more query examples, see [Query runtime logs](/platform/analytics/get-runtime-logs).
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
The SQL query for your runtime log data.
A query can use only the public alias `runtime_logs_v1`. The physical `default.*` table name is not permitted. CTEs, subqueries, UNION, and EXCEPT are permitted.
Only SELECT queries are permitted.
Unkey limits each query to the workspace of the root key. To get the logs of one project, app, environment, or deployment, add a filter on `project_id`, `app_id`, `environment_id`, or `deployment_id`.
The workspace retention period and the workspace query limits apply.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_analytics_get_runtime_logs",
"title": "Query runtime log data",
"description": "A query can use only the public alias `runtime_logs_v1`. CTEs, subqueries, UNION, and EXCEPT are permitted.\nThe root key must have the `project.*.read_runtime_logs` permission.\nUnkey limits each query to the workspace of the root key. To get the logs of one project, app, environment, or deployment, add a filter on `project_id`, `app_id`, `environment_id`, or `deployment_id`.\nThe workspace retention period and the workspace query limits apply.\nFor the table, the columns, and more query examples, see [Query runtime logs](/platform/analytics/get-runtime-logs).\n",
"inputSchema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "The SQL query for your runtime log data.\nA query can use only the public alias `runtime_logs_v1`. The physical `default.*` table name is not permitted. CTEs, subqueries, UNION, and EXCEPT are permitted.\nOnly SELECT queries are permitted.\nUnkey limits each query to the workspace of the root key. To get the logs of one project, app, environment, or deployment, add a filter on `project_id`, `app_id`, `environment_id`, or `deployment_id`.\nThe workspace retention period and the workspace query limits apply.\n"
}
}
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description74/100
Execute custom SQL queries against your key verification analytics. CTEs, subqueries, UNION, and EXCEPT are supported.
Queries must use one of the five public aliases: `key_verifications_v1`, `key_verifications_per_minute_v1`, `key_verifications_per_hour_v1`, `key_verifications_per_day_v1`, or `key_verifications_per_month_v1`. Physical `default.*` table names are unsupported.
Queries are always restricted to the authenticated workspace. Wildcard analytics permission can read every API in that workspace; API-scoped permissions automatically restrict results to the permitted APIs.
For complete documentation including available tables, columns, data types, query examples, see the schema reference in the API documentation.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
SQL query to execute against your analytics data.
Queries may reference only the five public aliases: `key_verifications_v1`, `key_verifications_per_minute_v1`, `key_verifications_per_hour_v1`, `key_verifications_per_day_v1`, or `key_verifications_per_month_v1`. Physical `default.*` table names are unsupported.
Only SELECT queries are allowed. CTEs, subqueries, UNION, and EXCEPT are supported.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_analytics_get_verifications",
"title": "Query key verification data",
"description": "Execute custom SQL queries against your key verification analytics. CTEs, subqueries, UNION, and EXCEPT are supported.\nQueries must use one of the five public aliases: `key_verifications_v1`, `key_verifications_per_minute_v1`, `key_verifications_per_hour_v1`, `key_verifications_per_day_v1`, or `key_verifications_per_month_v1`. Physical `default.*` table names are unsupported.\nQueries are always restricted to the authenticated workspace. Wildcard analytics permission can read every API in that workspace; API-scoped permissions automatically restrict results to the permitted APIs.\nFor complete documentation including available tables, columns, data types, query examples, see the schema reference in the API documentation.\n",
"inputSchema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "SQL query to execute against your analytics data.\nQueries may reference only the five public aliases: `key_verifications_v1`, `key_verifications_per_minute_v1`, `key_verifications_per_hour_v1`, `key_verifications_per_day_v1`, or `key_verifications_per_month_v1`. Physical `default.*` table names are unsupported.\nOnly SELECT queries are allowed. CTEs, subqueries, UNION, and EXCEPT are supported.\n"
}
}
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Create an API namespace for organizing keys by environment, service, or product.
Use this to separate production from development keys, isolate different services, or manage multiple products. Each API gets a unique identifier and dedicated infrastructure for secure key operations.
**Important**: API names must be unique within your workspace and cannot be changed after creation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.create_api` (to create APIs in any workspace)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
Human-readable name for this API within your workspace.
Use descriptive names like 'Payment Service (prod)' or 'user-api-dev' to clearly identify purpose and environment.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apis_create_api",
"title": "Create API namespace",
"description": "Create an API namespace for organizing keys by environment, service, or product.\n\nUse this to separate production from development keys, isolate different services, or manage multiple products. Each API gets a unique identifier and dedicated infrastructure for secure key operations.\n\n**Important**: API names must be unique within your workspace and cannot be changed after creation.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `api.*.create_api` (to create APIs in any workspace)\n",
"inputSchema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 3,
"description": "Human-readable name for this API within your workspace.\nUse descriptive names like 'Payment Service (prod)' or 'user-api-dev' to clearly identify purpose and environment.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Permanently delete an API namespace and immediately invalidate all associated keys.
Use this for cleaning up development environments, retiring deprecated services, or removing unused resources.
All keys in the namespace are immediately marked as deleted and will fail verification with `code=NOT_FOUND`.
**Important**: This operation is immediate and permanent. Verify you have the correct API ID before deletion.
If delete protection is enabled, disable it first through the dashboard or API configuration.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.delete_api` (to delete any API)
- `api.<api_id>.delete_api` (to delete a specific API)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
apiId
Specifies which API namespace to permanently delete from your workspace.
Must be a valid API ID that begins with 'api_' and exists within your workspace.
Before proceeding, ensure you have the correct API ID and understand that this action cannot be undone. If you need to migrate functionality, create replacement keys in a new API namespace and update client applications before deletion.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apis_delete_api",
"title": "Delete API namespace",
"description": "Permanently delete an API namespace and immediately invalidate all associated keys.\n\nUse this for cleaning up development environments, retiring deprecated services, or removing unused resources.\nAll keys in the namespace are immediately marked as deleted and will fail verification with `code=NOT_FOUND`.\n\n**Important**: This operation is immediate and permanent. Verify you have the correct API ID before deletion.\nIf delete protection is enabled, disable it first through the dashboard or API configuration.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `api.*.delete_api` (to delete any API)\n- `api.<api_id>.delete_api` (to delete a specific API)\n",
"inputSchema": {
"type": "object",
"required": [
"apiId"
],
"properties": {
"apiId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 8,
"description": "Specifies which API namespace to permanently delete from your workspace.\nMust be a valid API ID that begins with 'api_' and exists within your workspace.\n\nBefore proceeding, ensure you have the correct API ID and understand that this action cannot be undone. If you need to migrate functionality, create replacement keys in a new API namespace and update client applications before deletion.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Retrieve basic information about an API namespace including its ID and name.
Use this to verify an API exists before performing operations, get the human-readable name when you only have the API ID, or confirm access to a specific namespace. For detailed key information, use the `listKeys` endpoint instead.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.read_api` (to read any API)
- `api.<api_id>.read_api` (to read a specific API)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
apiId
Specifies which API to retrieve by its unique identifier.
Must be a valid API ID that begins with 'api_' and exists within your workspace.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apis_get_api",
"title": "Get API namespace",
"description": "Retrieve basic information about an API namespace including its ID and name.\n\nUse this to verify an API exists before performing operations, get the human-readable name when you only have the API ID, or confirm access to a specific namespace. For detailed key information, use the `listKeys` endpoint instead.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `api.*.read_api` (to read any API)\n- `api.<api_id>.read_api` (to read a specific API)\n",
"inputSchema": {
"type": "object",
"required": [
"apiId"
],
"properties": {
"apiId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 8,
"description": "Specifies which API to retrieve by its unique identifier.\nMust be a valid API ID that begins with 'api_' and exists within your workspace.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Retrieve a paginated list of API keys for dashboard and administrative interfaces.
Use this to build key management dashboards, filter keys by user with `externalId`, or retrieve key details for administrative purposes. Each key includes status, metadata, permissions, and usage limits.
**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.
**Required Permissions**
Your root key must have one of the following permissions for basic key listing:
- `api.*.read_key` (to read keys from any API)
- `api.<api_id>.read_key` (to read keys from a specific API)
Additionally, you need read access to the API itself:
- `api.*.read_api` or `api.<api_id>.read_api`
Additional permission required for decrypt functionality:
- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
apiId
The API namespace whose keys you want to list.
Returns all keys in this API, subject to pagination and filters.
Clear enough to supply this argument.
cursor
Pagination cursor from previous response to fetch next page.
Use when `hasMore: true` in previous response.
Clear enough to supply this argument.
decrypt
When true, attempts to include the plaintext key value in the response. SECURITY WARNING:
- This requires special permissions on the calling root key
- Only works for keys created with 'recoverable: true'
- Exposes sensitive key material in the response
- Should only be used in secure administrative contexts
- Never enable this in user-facing applications
Clear enough to supply this argument.
externalId
Filter keys by external ID to find keys for a specific user or entity.
Must exactly match the externalId set during key creation.
Clear enough to supply this argument.
limit
Maximum number of keys to return per request.
Balance between response size and number of pagination calls needed.
Clear enough to supply this argument.
revalidateKeysCache
When true, reads keys and their identities from the primary database to avoid replica lag.
When false or omitted, reads from a replica, which may not reflect recent changes.
Primary reads can have higher latency, depending on your region.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apis_list_keys",
"title": "List API keys",
"description": "Retrieve a paginated list of API keys for dashboard and administrative interfaces.\n\nUse this to build key management dashboards, filter keys by user with `externalId`, or retrieve key details for administrative purposes. Each key includes status, metadata, permissions, and usage limits.\n\n**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions for basic key listing:\n- `api.*.read_key` (to read keys from any API)\n- `api.<api_id>.read_key` (to read keys from a specific API)\n\nAdditionally, you need read access to the API itself:\n- `api.*.read_api` or `api.<api_id>.read_api`\n\nAdditional permission required for decrypt functionality:\n- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`\n",
"inputSchema": {
"type": "object",
"required": [
"apiId"
],
"properties": {
"apiId": {
"type": "string",
"minLength": 1,
"description": "The API namespace whose keys you want to list.\nReturns all keys in this API, subject to pagination and filters.\n"
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of keys to return per request.\nBalance between response size and number of pagination calls needed.\n"
},
"cursor": {
"type": "string",
"description": "Pagination cursor from previous response to fetch next page.\nUse when `hasMore: true` in previous response.\n"
},
"decrypt": {
"type": "boolean",
"default": false,
"description": "When true, attempts to include the plaintext key value in the response. SECURITY WARNING:\n- This requires special permissions on the calling root key\n- Only works for keys created with 'recoverable: true'\n- Exposes sensitive key material in the response\n- Should only be used in secure administrative contexts\n- Never enable this in user-facing applications"
},
"externalId": {
"type": "string",
"minLength": 1,
"description": "Filter keys by external ID to find keys for a specific user or entity.\nMust exactly match the externalId set during key creation.\n"
},
"revalidateKeysCache": {
"type": "boolean",
"default": false,
"description": "When true, reads keys and their identities from the primary database to avoid replica lag.\nWhen false or omitted, reads from a replica, which may not reflect recent changes.\nPrimary reads can have higher latency, depending on your region."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
Create an app within a project. The app is created with default `production` and `preview` environments.
Set exactly one source. Use `git` to create a GitHub-sourced app and connect its repository. Use `oci` to create an app from a prebuilt OCI image.
The slug you provide is the stable, caller-defined handle used to reference this app. It must be unique within the project.
**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.create_app` (to create apps in any project)
- `project.<project_id>.create_app` (to create apps in a specific project)
The description explains the capability, when to use it, and what to expect.
Inputs76/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
git › defaultBranch
The branch this app's deployments track. This requires `repository`.
Omit it to adopt the repository's default branch on GitHub.
Clear enough to supply this argument.
git › repository
The GitHub repository to connect, as "owner/repo". The workspace must have
the Unkey GitHub App installed with access to it. Omit this field to create
the Git app before selecting its repository.
Clear enough to supply this argument.
name
Human-readable name for this app.
Clear enough to supply this argument.
oci › image
The configured default OCI image reference for new deployments. It must include an explicit tag or digest.
Clear enough to supply this argument.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
slug
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Resolve the mismatch between this description and its schema constraints.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apps_create_app",
"title": "Create app",
"description": "Create an app within a project. The app is created with default `production` and `preview` environments.\n\nSet exactly one source. Use `git` to create a GitHub-sourced app and connect its repository. Use `oci` to create an app from a prebuilt OCI image.\n\nThe slug you provide is the stable, caller-defined handle used to reference this app. It must be unique within the project.\n\n**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `project.*.create_app` (to create apps in any project)\n- `project.<project_id>.create_app` (to create apps in a specific project)\n",
"inputSchema": {
"type": "object",
"oneOf": [
{
"required": [
"git"
]
},
{
"required": [
"oci"
]
}
],
"required": [
"project",
"name",
"slug"
],
"properties": {
"git": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "The GitHub repository to connect, as \"owner/repo\". The workspace must have\nthe Unkey GitHub App installed with access to it. Omit this field to create\nthe Git app before selecting its repository.\n"
},
"defaultBranch": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "The branch this app's deployments track. This requires `repository`.\nOmit it to adopt the repository's default branch on GitHub.\n"
}
},
"description": "Configure Git as the app source. Provide `repository` to connect it during\ncreation, or use an empty object to connect a repository later.\n",
"additionalProperties": false
},
"oci": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"pattern": "\\S",
"maxLength": 256,
"minLength": 1,
"description": "The configured default OCI image reference for new deployments. It must include an explicit tag or digest."
}
},
"description": "An app's OCI image source.",
"additionalProperties": false
},
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Human-readable name for this app."
},
"slug": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"description": "Create an app with exactly one source: `git` or `oci`. Requests that omit a\nsource or provide both sources are rejected.\n",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Delete an existing app, identified by its id.
Deletion is asynchronous and eventually consistent. The app and all of its associated resources (environments, deployments, custom domains) are torn down by a background workflow. A successful response indicates the deletion was enqueued, not that every resource has already been removed.
Apps with delete protection enabled cannot be deleted until protection is disabled.
**Required Permissions**
Your root key must have one of the following permissions:
- `app.*.delete_app` (to delete any app)
- `app.<app_id>.delete_app` (to delete a specific app)
The description explains the capability, when to use it, and what to expect.
Inputs68/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apps_delete_app",
"title": "Delete app",
"description": "Delete an existing app, identified by its id.\n\nDeletion is asynchronous and eventually consistent. The app and all of its associated resources (environments, deployments, custom domains) are torn down by a background workflow. A successful response indicates the deletion was enqueued, not that every resource has already been removed.\n\nApps with delete protection enabled cannot be deleted until protection is disabled.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `app.*.delete_app` (to delete any app)\n- `app.<app_id>.delete_app` (to delete a specific app)\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Shorten the title to an action and subject; move usage details into the description.
Description79/100
Retrieve a single app by its id or slug within a project.
Use this to fetch app details after creation or to verify an app exists before performing operations.
**Required Permissions**
Your root key must have one of the following permissions:
- `app.*.read_app` (to read any app)
- `app.<app_id>.read_app` (to read a specific app)
Describe the returned information so the agent knows whether it will answer the request.
Inputs71/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apps_get_app",
"title": "Get app",
"description": "Retrieve a single app by its id or slug within a project.\n\nUse this to fetch app details after creation or to verify an app exists before performing operations.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `app.*.read_app` (to read any app)\n- `app.<app_id>.read_app` (to read a specific app)\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description93/100
Retrieve a paginated list of apps within a project.
Use this to enumerate every app in a project. Results are ordered by app id and paginated; when `hasMore` is true, pass the returned `cursor` to fetch the next page.
**Required Permissions**
Your root key must have the following permission:
- `app.*.read_app` (to read apps in any project)
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
cursor
Pagination cursor from a previous response to fetch the next page.
Use when `hasMore: true` in the previous response.
Clear enough to supply this argument.
limit
Maximum number of apps to return per request.
Balance between response size and number of pagination calls needed.
Clear enough to supply this argument.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Clear enough to supply this argument.
search
Free-form text to filter apps. Returns apps whose ID, name, or slug contains the search string. Matching is case-insensitive.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apps_list_apps",
"title": "List apps",
"description": "Retrieve a paginated list of apps within a project.\n\nUse this to enumerate every app in a project. Results are ordered by app id and paginated; when `hasMore` is true, pass the returned `cursor` to fetch the next page.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `app.*.read_app` (to read apps in any project)\n",
"inputSchema": {
"type": "object",
"required": [
"project"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of apps to return per request.\nBalance between response size and number of pagination calls needed.\n"
},
"cursor": {
"type": "string",
"description": "Pagination cursor from a previous response to fetch the next page.\nUse when `hasMore: true` in the previous response.\n"
},
"search": {
"type": "string",
"maxLength": 256,
"description": "Free-form text to filter apps. Returns apps whose ID, name, or slug contains the search string. Matching is case-insensitive."
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description84/100
Update an existing app, identified by its id.
The app name, slug, default branch, and delete protection setting can be changed. Omitted fields are left unchanged. Changing the slug affects the deployment domains generated for this app.
**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have one of the following permissions:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>#write` (to update a specific app)
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/*#write` (to update any app in a project)
- `unkey:v1:<workspace_id>:projects/*/apps/*#write` (to update any app in your workspace)
The same app write permission covers Git repository changes.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deleteProtection
Enable or disable delete protection for the app.
Omit this field to leave the current setting unchanged.
Clear enough to supply this argument.
git › anyOf › 0 › defaultBranch
The branch this app's deployments track. Omit to adopt the repository's
GitHub default branch on a new connection, keep the current branch when
replacing an already-connected repository, or set it alone to retarget the
branch of the connected repository.
Clear enough to supply this argument.
git › anyOf › 0 › repository
The GitHub repository to connect, as "owner/repo". Omit to change only the
tracked branch of the already-connected repository. The workspace must have
the Unkey GitHub App installed with access to it.
Clear enough to supply this argument.
name
New human-readable name for the app.
Omit this field to leave the current name unchanged.
Clear enough to supply this argument.
oci › allOf › 0 › image
The configured default OCI image reference for new deployments. It must include an explicit tag or digest.
Clear enough to supply this argument.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
slug
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Resolve the mismatch between this description and its schema constraints.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_apps_update_app",
"title": "Update app",
"description": "Update an existing app, identified by its id.\n\nThe app name, slug, default branch, and delete protection setting can be changed. Omitted fields are left unchanged. Changing the slug affects the deployment domains generated for this app.\n\n**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>#write` (to update a specific app)\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/*#write` (to update any app in a project)\n- `unkey:v1:<workspace_id>:projects/*/apps/*#write` (to update any app in your workspace)\n\nThe same app write permission covers Git repository changes.\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"git": {
"anyOf": [
{
"type": "object",
"properties": {
"repository": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "The GitHub repository to connect, as \"owner/repo\". Omit to change only the\ntracked branch of the already-connected repository. The workspace must have\nthe Unkey GitHub App installed with access to it.\n"
},
"defaultBranch": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "The branch this app's deployments track. Omit to adopt the repository's\nGitHub default branch on a new connection, keep the current branch when\nreplacing an already-connected repository, or set it alone to retarget the\nbranch of the connected repository.\n"
}
},
"minProperties": 1,
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Connect, reconfigure, or disconnect this app's GitHub repository.\nOmit to leave unchanged, set null to disconnect, or set an object with a\n\"repository\" to connect or replace it and/or a \"defaultBranch\" to set which\nbranch it tracks. Fields are independent, so send only the one you change.\n"
},
"oci": {
"allOf": [
{
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"pattern": "\\S",
"maxLength": 256,
"minLength": 1,
"description": "The configured default OCI image reference for new deployments. It must include an explicit tag or digest."
}
},
"description": "An app's OCI image source.",
"additionalProperties": false
}
],
"description": "Change the default image reference for an OCI-sourced app. This does not\ncreate a deployment. It can be combined with other app settings. Source\nswitching is not supported.\n"
},
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "New human-readable name for the app.\nOmit this field to leave the current name unchanged.\n"
},
"slug": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"deleteProtection": {
"type": "boolean",
"description": "Enable or disable delete protection for the app.\nOmit this field to leave the current setting unchanged.\n"
}
},
"description": "Provide at least one field to update. Omitted fields remain unchanged.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Authorize a deployment that is awaiting approval. Deployments from forked
pull requests run code from outside your repository, so they wait for a
project member to approve them before they build.
The deployment must have the status `awaiting_approval`. Authorization is
asynchronous: this endpoint only enqueues it and returns immediately. The
deployment then moves to `pending` and starts its build. Poll
`getDeployment` to follow its status. If the build cannot start, the
deployment returns to `awaiting_approval`.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deploymentId
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_authorize_deployment",
"title": "Authorize deployment",
"description": "Authorize a deployment that is awaiting approval. Deployments from forked\npull requests run code from outside your repository, so they wait for a\nproject member to approve them before they build.\n\nThe deployment must have the status `awaiting_approval`. Authorization is\nasynchronous: this endpoint only enqueues it and returns immediately. The\ndeployment then moves to `pending` and starts its build. Poll\n`getDeployment` to follow its status. If the build cannot start, the\ndeployment returns to `awaiting_approval`.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`\n",
"inputSchema": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Cancel a deployment that has not finished yet: queued, waiting for
approval, building, or deploying. Cancelling aborts its run and marks it
`cancelled`.
Only in-progress deployments can be cancelled. To take a `ready` preview
deployment offline, use `stopDeployment` instead.
Cancellation is asynchronous: this endpoint only enqueues it and returns
immediately. Poll `getDeployment` until the status reaches `cancelled`.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deploymentId
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_cancel_deployment",
"title": "Cancel deployment",
"description": "Cancel a deployment that has not finished yet: queued, waiting for\napproval, building, or deploying. Cancelling aborts its run and marks it\n`cancelled`.\n\nOnly in-progress deployments can be cancelled. To take a `ready` preview\ndeployment offline, use `stopDeployment` instead.\n\nCancellation is asynchronous: this endpoint only enqueues it and returns\nimmediately. Poll `getDeployment` until the status reaches `cancelled`.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`\n",
"inputSchema": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Create a deployment for an app in a project.
Omit the source to use the app's configured default. A Git app builds its default branch. An OCI app deploys its default image.
Optionally provide one source override:
- `oci`: deploy a prebuilt OCI image without a build. Mutable tags are resolved to immutable digests before rollout.
- `git`: build and deploy from the app's connected GitHub repository, a branch, a specific commit, or a fork commit. Requires the app to have a repository connected.
- `deployment`: re-run an existing deployment by its id. Git deployments rebuild from the recorded commit; OCI deployments reuse the recorded resolved image.
Returns immediately with a `deploymentId`. The build and rollout run asynchronously. Poll `deployments.getDeployment` to watch status until it is ready.
**Authentication**: requires a root key with `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/*#write`. Wildcards can replace resource IDs to grant access across a wider scope.
The description explains the capability, when to use it, and what to expect.
Inputs74/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deployment › deploymentId
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
git › branch
Branch to build (its HEAD). Omit branch and commitSha to use the app's default branch.
Clear enough to supply this argument.
git › commitSha
Commit to build (full or abbreviated SHA). Takes precedence over branch.
Clear enough to supply this argument.
git › repository
Build from a fork instead of the app's connected repository, as "owner/repo". Requires commitSha.
Clear enough to supply this argument.
oci › image
OCI image to deploy. Mutable tags are resolved to immutable digests before rollout.
Clear enough to supply this argument.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_create_deployment_v3",
"title": "Create deployment",
"description": "Create a deployment for an app in a project.\n\nOmit the source to use the app's configured default. A Git app builds its default branch. An OCI app deploys its default image.\n\nOptionally provide one source override:\n- `oci`: deploy a prebuilt OCI image without a build. Mutable tags are resolved to immutable digests before rollout.\n- `git`: build and deploy from the app's connected GitHub repository, a branch, a specific commit, or a fork commit. Requires the app to have a repository connected.\n- `deployment`: re-run an existing deployment by its id. Git deployments rebuild from the recorded commit; OCI deployments reuse the recorded resolved image.\n\nReturns immediately with a `deploymentId`. The build and rollout run asynchronously. Poll `deployments.getDeployment` to watch status until it is ready.\n\n**Authentication**: requires a root key with `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/*#write`. Wildcards can replace resource IDs to grant access across a wider scope.\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"git": {
"type": "object",
"properties": {
"branch": {
"type": "string",
"maxLength": 256,
"description": "Branch to build (its HEAD). Omit branch and commitSha to use the app's default branch."
},
"commitSha": {
"type": "string",
"maxLength": 40,
"description": "Commit to build (full or abbreviated SHA). Takes precedence over branch."
},
"repository": {
"type": "string",
"pattern": "^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$",
"maxLength": 256,
"description": "Build from a fork instead of the app's connected repository, as \"owner/repo\". Requires commitSha."
}
},
"description": "Build from the app's connected GitHub repository."
},
"oci": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"pattern": "\\S",
"maxLength": 256,
"minLength": 1,
"description": "OCI image to deploy. Mutable tags are resolved to immutable digests before rollout."
}
},
"description": "Deploy a prebuilt OCI image without a build.",
"additionalProperties": false
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"deployment": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"description": "Re-run an existing deployment."
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"description": "Create a deployment. Omit the source to use the app default, or provide one source override.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
Retrieve a single deployment by its id.
Use this to check a deployment's status after creating it, or to inspect the
runtime configuration of an existing deployment.
**Required Permissions**
Your root key must have this permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#read`
(use `*` for any level)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deploymentId
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_get_deployment",
"title": "Get deployment",
"description": "Retrieve a single deployment by its id.\n\nUse this to check a deployment's status after creating it, or to inspect the\nruntime configuration of an existing deployment.\n\n**Required Permissions**\n\nYour root key must have this permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#read`\n (use `*` for any level)\n",
"inputSchema": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"description": "Retrieve a single deployment, including its status and runtime configuration.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Retrieve the build output of a deployment as a list of log entries, in the
order the build printed them. A log entry is one chunk of build output,
and can contain several lines or part of a line.
Poll this endpoint to follow a running build:
- Send the `pagination.cursor` of the last response as `cursor`. The
response contains only the entries after it.
- When `hasMore` is true, request again now.
- When `hasMore` is false, you have all entries so far. Wait,
then request again with the same cursor.
- The cursor is absent only when the request had no cursor and the build
has no entries yet.
- A response can contain fewer than `limit` entries and still have
`hasMore: true` when the entries are large.
New entries become visible up to a few seconds after the build prints
them. To know that a build is done, check the deployment status with
`getDeployment`. After the status is no longer `building`, request until
you get an empty response at least 5 seconds later.
When a build attempt is retried, an entry from the earlier attempt can
arrive after the cursor has moved past it, and a poll does not return it.
A request without a cursor returns it. A deployment from a prebuilt image
has no build and returns no entries. Build logs are kept for 3 months.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>/buildLogs#read`
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response to fetch the entries after
it. Omit it to start at the first entry of the build.
Clear enough to supply this argument.
deploymentId
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of log entries to return. A response can contain fewer
entries and still have `hasMore: true` when the entries are large.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
stepId
Return only the log entries of this build step. Use the `stepId` of an
entry from a previous response. An unknown step returns no entries.
Omit this field to return the entries of every step.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_list_build_logs",
"title": "List build logs",
"description": "Retrieve the build output of a deployment as a list of log entries, in the\norder the build printed them. A log entry is one chunk of build output,\nand can contain several lines or part of a line.\n\nPoll this endpoint to follow a running build:\n\n- Send the `pagination.cursor` of the last response as `cursor`. The\n response contains only the entries after it.\n- When `hasMore` is true, request again now.\n- When `hasMore` is false, you have all entries so far. Wait,\n then request again with the same cursor.\n- The cursor is absent only when the request had no cursor and the build\n has no entries yet.\n- A response can contain fewer than `limit` entries and still have\n `hasMore: true` when the entries are large.\n\nNew entries become visible up to a few seconds after the build prints\nthem. To know that a build is done, check the deployment status with\n`getDeployment`. After the status is no longer `building`, request until\nyou get an empty response at least 5 seconds later.\n\nWhen a build attempt is retried, an entry from the earlier attempt can\narrive after the cursor has moved past it, and a poll does not return it.\nA request without a cursor returns it. A deployment from a prebuilt image\nhas no build and returns no entries. Build logs are kept for 3 months.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>/buildLogs#read`\n",
"inputSchema": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 500,
"minimum": 1,
"description": "Maximum number of log entries to return. A response can contain fewer\nentries and still have `hasMore: true` when the entries are large.\n"
},
"cursor": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Pagination cursor from a previous response to fetch the entries after\nit. Omit it to start at the first entry of the build.\n"
},
"stepId": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Return only the log entries of this build step. Use the `stepId` of an\nentry from a previous response. An unknown step returns no entries.\nOmit this field to return the entries of every step.\n"
},
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"description": "Retrieve the build log entries of a deployment. Get the deployment id from\n`createDeployment` or `listDeployments`.\n",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Retrieve a paginated list of deployments within a workspace, newest first.
Filter by project, app, environment, lifecycle status, git branch, and
creation time. All filters are optional; with none set, every deployment in
the workspace is returned. Filters nest: `app` requires `project`, and
`environment` and `branch` require both `project` and `app`. Results are
paginated; when `hasMore` is true, pass the returned `cursor` to fetch the
next page.
**Required Permissions**
Your root key must have this permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/*#read`
(use `*` for every level you do not filter by)
The permission must cover every deployment the filters select: a grant on
one environment is not sufficient for a request that spans more than that
environment.
Describe the returned information so the agent knows whether it will answer the request.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Restrict results to a single app, identified by its ID or slug.
Requires `project` to also be set.
Clear enough to supply this argument.
branch
Restrict results to deployments built from any of the given git branches.
Requires `project` and `app` to also be set. Omit or pass an empty list to
return deployments from every branch.
Clear enough to supply this argument.
cursor
Pagination cursor from a previous response to fetch the next page.
Use when `hasMore: true` in the previous response.
Clear enough to supply this argument.
endTime
Return only deployments created before this unix timestamp in
milliseconds (exclusive). Must be later than `startTime` when both are
set.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Restrict results to a single environment, identified by its ID or slug.
Requires `project` and `app` to also be set.
Clear enough to supply this argument.
limit
Maximum number of deployments to return per request.
Balance between response size and number of pagination calls needed.
Clear enough to supply this argument.
project
Restrict results to a single project, identified by its ID or slug.
Required when filtering by `app`, `environment`, or `branch`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
startTime
Return only deployments created at or after this unix timestamp in
milliseconds (inclusive).
Clear enough to supply this argument.
status
Restrict results to deployments in any of the given lifecycle statuses.
Omit to return deployments in every status.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_list_deployments",
"title": "List deployments",
"description": "Retrieve a paginated list of deployments within a workspace, newest first.\n\nFilter by project, app, environment, lifecycle status, git branch, and\ncreation time. All filters are optional; with none set, every deployment in\nthe workspace is returned. Filters nest: `app` requires `project`, and\n`environment` and `branch` require both `project` and `app`. Results are\npaginated; when `hasMore` is true, pass the returned `cursor` to fetch the\nnext page.\n\n**Required Permissions**\n\nYour root key must have this permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/*#read`\n (use `*` for every level you do not filter by)\n\nThe permission must cover every deployment the filters select: a grant on\none environment is not sufficient for a request that spans more than that\nenvironment.\n",
"inputSchema": {
"type": "object",
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Restrict results to a single app, identified by its ID or slug.\nRequires `project` to also be set.\n"
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of deployments to return per request.\nBalance between response size and number of pagination calls needed.\n"
},
"branch": {
"type": "array",
"items": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"maxItems": 50,
"description": "Restrict results to deployments built from any of the given git branches.\nRequires `project` and `app` to also be set. Omit or pass an empty list to\nreturn deployments from every branch.\n"
},
"cursor": {
"type": "string",
"description": "Pagination cursor from a previous response to fetch the next page.\nUse when `hasMore: true` in the previous response.\n"
},
"status": {
"type": "array",
"items": {
"enum": [
"pending",
"starting",
"building",
"deploying",
"network",
"finalizing",
"ready",
"failed",
"skipped",
"awaiting_approval",
"stopped",
"superseded",
"cancelled"
],
"type": "string",
"description": "Current lifecycle status of the deployment. Poll until it reaches a\nterminal state: ready (serving), failed, skipped, superseded, stopped,\nor cancelled.\n"
},
"maxItems": 13,
"description": "Restrict results to deployments in any of the given lifecycle statuses.\nOmit to return deployments in every status.\n"
},
"endTime": {
"type": "integer",
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 0,
"description": "Return only deployments created before this unix timestamp in\nmilliseconds (exclusive). Must be later than `startTime` when both are\nset.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Restrict results to a single project, identified by its ID or slug.\nRequired when filtering by `app`, `environment`, or `branch`.\n"
},
"startTime": {
"type": "integer",
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 0,
"description": "Return only deployments created at or after this unix timestamp in\nmilliseconds (inclusive).\n"
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Restrict results to a single environment, identified by its ID or slug.\nRequires `project` and `app` to also be set.\n"
}
},
"description": "Filter deployments within a workspace. All filters are optional; with none\nset, every deployment in the workspace is returned, newest first.\n",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Promote a deployment to become the current deployment for its environment.
All sticky domains are reassigned from the current deployment to the
promoted one, and the previous deployment is scheduled for standby.
The deployment must be ready, not already shutting down, belong to the
production environment, and its app must already have a current deployment.
Promoting the deployment that is already current fails, unless the app is in
a rolled-back state, in which case promoting the current deployment
confirms the rollback and re-enables automatic promotion of future
deployments.
Promotion runs as a durable workflow: this endpoint returns once the
promotion is accepted. Poll `getDeployment` or `listDeployments` to observe
the result.
**Required Permissions**
Your root key must have write permission on the environment:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>#write`
The description explains the capability, when to use it, and what to expect.
Inputs69/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deploymentId
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_promote_deployment",
"title": "Promote deployment",
"description": "Promote a deployment to become the current deployment for its environment.\nAll sticky domains are reassigned from the current deployment to the\npromoted one, and the previous deployment is scheduled for standby.\n\nThe deployment must be ready, not already shutting down, belong to the\nproduction environment, and its app must already have a current deployment.\nPromoting the deployment that is already current fails, unless the app is in\na rolled-back state, in which case promoting the current deployment\nconfirms the rollback and re-enables automatic promotion of future\ndeployments.\n\nPromotion runs as a durable workflow: this endpoint returns once the\npromotion is accepted. Poll `getDeployment` or `listDeployments` to observe\nthe result.\n\n**Required Permissions**\n\nYour root key must have write permission on the environment:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>#write`\n",
"inputSchema": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"description": "Promote a ready deployment to become the current deployment for its environment.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Roll live traffic back to a previous deployment. `deploymentId` is the
deployment to roll back TO; the app's current deployment is used as
the rollback source automatically.
The target deployment must be ready, not already shutting down, belong to
the production environment, and must not itself be the current deployment.
After a rollback the app is marked as rolled back, which prevents new
deployments from automatically taking over live traffic. Promote the
rolled-back deployment (or a newer one) to clear this state.
Rollback runs as a durable workflow: this endpoint returns once the
rollback is accepted. Poll `getDeployment` or `listDeployments` to observe
the result.
**Required Permissions**
Your root key must have write permission on the environment:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>#write`
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Input documentation gives an agent enough context to populate the arguments.
deploymentId
The deployment to roll back TO. Its app's current deployment is used
as the rollback source automatically.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_rollback_deployment",
"title": "Rollback deployment",
"description": "Roll live traffic back to a previous deployment. `deploymentId` is the\ndeployment to roll back TO; the app's current deployment is used as\nthe rollback source automatically.\n\nThe target deployment must be ready, not already shutting down, belong to\nthe production environment, and must not itself be the current deployment.\n\nAfter a rollback the app is marked as rolled back, which prevents new\ndeployments from automatically taking over live traffic. Promote the\nrolled-back deployment (or a newer one) to clear this state.\n\nRollback runs as a durable workflow: this endpoint returns once the\nrollback is accepted. Poll `getDeployment` or `listDeployments` to observe\nthe result.\n\n**Required Permissions**\n\nYour root key must have write permission on the environment:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>#write`\n",
"inputSchema": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "The deployment to roll back TO. Its app's current deployment is used\nas the rollback source automatically.\n"
}
},
"description": "Roll live traffic back to a previous deployment.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Start a deployment that was previously stopped with `stopDeployment`, so it
serves traffic again. The deployment keeps the configuration it had when it
was stopped; nothing is rebuilt or redeployed.
The deployment must currently be stopped, and must belong to a
non-production environment. Production deployments are never stopped, so
they cannot be started.
Starting is asynchronous: this endpoint only enqueues the start and returns
immediately. Poll `getDeployment` until the status reaches `ready`.
**Required Permissions**
Your root key must have write permission on the deployment:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deploymentId
The stopped deployment to start.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_start_deployment",
"title": "Start deployment",
"description": "Start a deployment that was previously stopped with `stopDeployment`, so it\nserves traffic again. The deployment keeps the configuration it had when it\nwas stopped; nothing is rebuilt or redeployed.\n\nThe deployment must currently be stopped, and must belong to a\nnon-production environment. Production deployments are never stopped, so\nthey cannot be started.\n\nStarting is asynchronous: this endpoint only enqueues the start and returns\nimmediately. Poll `getDeployment` until the status reaches `ready`.\n\n**Required Permissions**\n\nYour root key must have write permission on the deployment:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`\n",
"inputSchema": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "The stopped deployment to start."
}
},
"description": "Start a stopped preview deployment so it serves traffic again.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Stop a running deployment that is not the app's live production deployment.
Stopped deployments keep their configuration. Preview deployments can be
resumed later with `startDeployment`.
The deployment must be ready and running. Previous production deployments
can be stopped, but stopping one removes instant rollback to it.
A deployment that is already draining from a previous stop is rejected
with a precondition error.
Stopping is asynchronous: this endpoint only enqueues the stop and returns
immediately. Poll `getDeployment` until the status reaches `stopped`.
**Required Permissions**
Your root key must have write permission on the deployment:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deploymentId
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_deployments_stop_deployment",
"title": "Stop deployment",
"description": "Stop a running deployment that is not the app's live production deployment.\nStopped deployments keep their configuration. Preview deployments can be\nresumed later with `startDeployment`.\n\nThe deployment must be ready and running. Previous production deployments\ncan be stopped, but stopping one removes instant rollback to it.\nA deployment that is already draining from a previous stop is rejected\nwith a precondition error.\n\nStopping is asynchronous: this endpoint only enqueues the stop and returns\nimmediately. Poll `getDeployment` until the status reaches `stopped`.\n\n**Required Permissions**\n\nYour root key must have write permission on the deployment:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`\n",
"inputSchema": {
"type": "object",
"required": [
"deploymentId"
],
"properties": {
"deploymentId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"description": "Stop a running preview deployment to free up resources.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Attach a custom domain to an environment and start verifying it.
The domain is created in the `pending` state and does not serve traffic until verification succeeds. Verification runs in the background and polls DNS, so it is eventually consistent.
The response returns `dnsRecords`: every record needed to finish setup, already resolved for whether this domain is an apex or a subdomain. Create every entry exactly as given. One record establishes routing and one proves ownership, and both are needed: whether ownership can be inferred from the routing record depends on how your provider publishes it, and a name another workspace has already verified can only be claimed through the ownership record. Neither is knowable before the records exist.
When your DNS provider supports Domain Connect, the response also carries a `domainConnect` object; opening its `url` applies the same records at the provider in one step. The object is absent when the shortcut is unavailable.
Domains are unique per workspace, so the same name cannot be attached to two environments. Attaching a domain that already exists in your workspace returns a 409 conflict.
How many domains you may attach is set by your plan. Attaching one beyond that allowance returns a 403; upgrade the plan or remove a domain you no longer need.
**Important**: verification stops after 24 hours without the required DNS records, and the domain moves to `failed`.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.create_domain` (to attach domains to any environment)
- `environment.<environment_id>.create_domain` (to attach domains to a specific environment)
The description explains the capability, when to use it, and what to expect.
Inputs67/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Fully qualified domain name to attach to the environment, without a scheme, port, or path.
Must be unique across your entire workspace: the same name cannot be attached to two environments.
The name must sit under a registrable domain: 'api.acme.co.uk' is accepted, the public suffix
'co.uk' itself is not. Internationalized names may be sent in Unicode or Punycode form; either
way the domain is stored and returned in its canonical form, lowercase ASCII with Unicode labels
Punycode encoded, and the DNS records in the response use that form.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_domains_create_domain",
"title": "Create domain",
"description": "Attach a custom domain to an environment and start verifying it.\n\nThe domain is created in the `pending` state and does not serve traffic until verification succeeds. Verification runs in the background and polls DNS, so it is eventually consistent.\n\nThe response returns `dnsRecords`: every record needed to finish setup, already resolved for whether this domain is an apex or a subdomain. Create every entry exactly as given. One record establishes routing and one proves ownership, and both are needed: whether ownership can be inferred from the routing record depends on how your provider publishes it, and a name another workspace has already verified can only be claimed through the ownership record. Neither is knowable before the records exist.\n\nWhen your DNS provider supports Domain Connect, the response also carries a `domainConnect` object; opening its `url` applies the same records at the provider in one step. The object is absent when the shortcut is unavailable.\n\nDomains are unique per workspace, so the same name cannot be attached to two environments. Attaching a domain that already exists in your workspace returns a 409 conflict.\n\nHow many domains you may attach is set by your plan. Attaching one beyond that allowance returns a 403; upgrade the plan or remove a domain you no longer need.\n\n**Important**: verification stops after 24 hours without the required DNS records, and the domain moves to `failed`.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `environment.*.create_domain` (to attach domains to any environment)\n- `environment.<environment_id>.create_domain` (to attach domains to a specific environment)\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment",
"domain"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"domain": {
"type": "string",
"maxLength": 253,
"minLength": 4,
"description": "Fully qualified domain name to attach to the environment, without a scheme, port, or path.\nMust be unique across your entire workspace: the same name cannot be attached to two environments.\n\nThe name must sit under a registrable domain: 'api.acme.co.uk' is accepted, the public suffix\n'co.uk' itself is not. Internationalized names may be sent in Unicode or Punycode form; either\nway the domain is stored and returned in its canonical form, lowercase ASCII with Unicode labels\nPunycode encoded, and the DNS records in the response use that form.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description96/100
Delete a custom domain from your workspace.
Address the domain by its id or by its name. Names are unique per workspace, so
`api.acme.com` is enough.
Unkey stops serving the domain. Later requests fail with a certificate error. The DNS
records at your provider stay in place.
**Required Permissions**
Your root key must have `delete` permission on the domain:
`unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/domains/<domain_id>#delete`.
Use `*` in place of resource IDs to grant access to all matching domains in your workspace.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Identifies a domain by its Unkey ID or by its name. Pass a 'dom_'-prefixed ID, or a fully
qualified domain name such as 'api.acme.com' without a scheme, port, or path. You can give an
internationalized name in Unicode or Punycode form. Both forms address the same domain.
Domain names are unique per workspace, so the name alone addresses the domain. You do not
need to supply a project, app, or environment.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_domains_delete_domain",
"title": "Delete domain",
"description": "Delete a custom domain from your workspace.\n\nAddress the domain by its id or by its name. Names are unique per workspace, so\n`api.acme.com` is enough.\n\nUnkey stops serving the domain. Later requests fail with a certificate error. The DNS\nrecords at your provider stay in place.\n\n**Required Permissions**\n\nYour root key must have `delete` permission on the domain:\n`unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/domains/<domain_id>#delete`.\nUse `*` in place of resource IDs to grant access to all matching domains in your workspace.\n",
"inputSchema": {
"type": "object",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"maxLength": 253,
"minLength": 4,
"description": "Identifies a domain by its Unkey ID or by its name. Pass a 'dom_'-prefixed ID, or a fully\nqualified domain name such as 'api.acme.com' without a scheme, port, or path. You can give an\ninternationalized name in Unicode or Punycode form. Both forms address the same domain.\n\nDomain names are unique per workspace, so the name alone addresses the domain. You do not\nneed to supply a project, app, or environment.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Retrieve a custom domain and its verification status.
Address the domain by its id or by its name. Names are unique per workspace, so
`api.acme.com` is sufficient. You do not need to supply a project, app, or environment.
Use this endpoint to poll after `domains.createDomain`. Verification runs in the background
and checks DNS approximately each minute.
`status: verified` means the domain is verified. Unkey has configured routing and requested a
certificate. Each entry in `dnsRecords` has a `verified` flag. The flag shows which records
Unkey has read back, so you can see which records are still missing. Some providers hide a
record from DNS lookups, for example a proxied or flattened routing record. Such a record stays
`false` while it serves traffic. `verificationError` gives the reason for the last failed
attempt.
`dnsRecords` contains the same values that `domains.createDomain` returned. Use it to recover
the values without creating the domain again.
**Important**: verification stops 24 hours after the domain was created, and the status becomes
`failed`. The window starts at `createdAt`, not at the last attempt.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_domain` (to read domains in any environment)
- `environment.<environment_id>.read_domain` (to read domains in a specific environment)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Identifies a domain by its Unkey ID or by its name. Pass a 'dom_'-prefixed ID, or a fully
qualified domain name such as 'api.acme.com' without a scheme, port, or path. You can give an
internationalized name in Unicode or Punycode form. Both forms address the same domain.
Domain names are unique per workspace, so the name alone addresses the domain. You do not
need to supply a project, app, or environment.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_domains_get_domain",
"title": "Get domain",
"description": "Retrieve a custom domain and its verification status.\n\nAddress the domain by its id or by its name. Names are unique per workspace, so\n`api.acme.com` is sufficient. You do not need to supply a project, app, or environment.\n\nUse this endpoint to poll after `domains.createDomain`. Verification runs in the background\nand checks DNS approximately each minute.\n\n`status: verified` means the domain is verified. Unkey has configured routing and requested a\ncertificate. Each entry in `dnsRecords` has a `verified` flag. The flag shows which records\nUnkey has read back, so you can see which records are still missing. Some providers hide a\nrecord from DNS lookups, for example a proxied or flattened routing record. Such a record stays\n`false` while it serves traffic. `verificationError` gives the reason for the last failed\nattempt.\n\n`dnsRecords` contains the same values that `domains.createDomain` returned. Use it to recover\nthe values without creating the domain again.\n\n**Important**: verification stops 24 hours after the domain was created, and the status becomes\n`failed`. The window starts at `createdAt`, not at the last attempt.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `environment.*.read_domain` (to read domains in any environment)\n- `environment.<environment_id>.read_domain` (to read domains in a specific environment)\n",
"inputSchema": {
"type": "object",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"maxLength": 253,
"minLength": 4,
"description": "Identifies a domain by its Unkey ID or by its name. Pass a 'dom_'-prefixed ID, or a fully\nqualified domain name such as 'api.acme.com' without a scheme, port, or path. You can give an\ninternationalized name in Unicode or Punycode form. Both forms address the same domain.\n\nDomain names are unique per workspace, so the name alone addresses the domain. You do not\nneed to supply a project, app, or environment.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description97/100
List your custom domains with their verification status and DNS records.
Filter by project, app, or environment using IDs or slugs, or send `{}` to list
domains across your workspace.
Use any filter on its own or combine filters to narrow the results.
Results match all supplied filters. Omitting `environment` includes all matching environments.
Results include only domains you have permission to read, sorted by ID.
When `hasMore` is true, send the returned `cursor` to get the next page.
`status: verified` means the domain is verified. Unkey has configured routing and requested a
certificate. Each domain includes its full `dnsRecords`. Each record has a `verified` flag.
The flag shows which records Unkey has read back, so you can see which records are still
missing without a second call. Some providers hide a record from DNS lookups, for example a
proxied or flattened routing record. Such a record stays `false` while it serves traffic.
**Required Permissions**
Use a root key with the `environment.*.read_domain` permission.
A successful request returns an empty list if no matching domains are readable by your key.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Match domains whose app ID or slug equals this value. This filter does not require a
project or environment filter.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
The pagination cursor from the response that came before.
Send it to get the next page when that response has `hasMore: true`.
Clear enough to supply this argument.
environment
Match domains whose environment ID or slug equals this value. This filter does not require
a project or app filter.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
The maximum number of domains one response contains.
A small limit makes the response smaller, but makes more requests necessary.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Match domains whose project ID or slug equals this value. This filter does not require
an app or environment filter.
Clear enough to supply this argument.
search
Free-form text to filter domains. Returns domains whose ID or name contains the search string. Matching is case-insensitive.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_domains_list_domains",
"title": "List domains",
"description": "List your custom domains with their verification status and DNS records.\nFilter by project, app, or environment using IDs or slugs, or send `{}` to list\ndomains across your workspace.\n\nUse any filter on its own or combine filters to narrow the results.\nResults match all supplied filters. Omitting `environment` includes all matching environments.\n\nResults include only domains you have permission to read, sorted by ID.\nWhen `hasMore` is true, send the returned `cursor` to get the next page.\n\n`status: verified` means the domain is verified. Unkey has configured routing and requested a\ncertificate. Each domain includes its full `dnsRecords`. Each record has a `verified` flag.\nThe flag shows which records Unkey has read back, so you can see which records are still\nmissing without a second call. Some providers hide a record from DNS lookups, for example a\nproxied or flattened routing record. Such a record stays `false` while it serves traffic.\n\n**Required Permissions**\n\nUse a root key with the `environment.*.read_domain` permission.\nA successful request returns an empty list if no matching domains are readable by your key.\n",
"inputSchema": {
"type": "object",
"properties": {
"app": {
"allOf": [
{
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
],
"description": "Match domains whose app ID or slug equals this value. This filter does not require a\nproject or environment filter.\n"
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "The maximum number of domains one response contains.\nA small limit makes the response smaller, but makes more requests necessary.\n"
},
"cursor": {
"type": "string",
"description": "The pagination cursor from the response that came before.\nSend it to get the next page when that response has `hasMore: true`.\n"
},
"search": {
"type": "string",
"maxLength": 256,
"description": "Free-form text to filter domains. Returns domains whose ID or name contains the search string. Matching is case-insensitive."
},
"project": {
"allOf": [
{
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
],
"description": "Match domains whose project ID or slug equals this value. This filter does not require\nan app or environment filter.\n"
},
"environment": {
"allOf": [
{
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
],
"description": "Match domains whose environment ID or slug equals this value. This filter does not require\na project or app filter.\n"
}
},
"description": "Filter domains within a workspace. All filters are optional and combine with AND. Each resource\nfilter matches its ID or slug directly, even when its parent filters are omitted. A missing\nresource or a resource that does not match the other filters produces an empty list.\n",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Restart verification for a custom domain.
Address the domain by its ID or by its name. Names are unique per workspace, so
`api.acme.com` is enough.
Call this after you correct the DNS records of a domain that shows `failed`, or to give a
`pending` domain a new 24-hour verification period. The domain goes back to `pending` and
the 24-hour period starts again.
The endpoint returns when Unkey accepts the retry. Poll `domains.getDomain` for the result.
A domain that is already `verified` returns a 412.
**Required Permissions**
Your root key must have `write` on the domain:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/domains/<domain_id>#write`
- `unkey:v1:<workspace_id>:projects/*/apps/*/environments/*/domains/*#write` (all domains in your workspace)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Identifies a domain by its name or by its ID. Send the fully qualified domain name, such as
'api.acme.com', without a scheme, port, or path, or send the domain ID that
domains.createDomain returns. You can send an internationalized name in Unicode or in
Punycode form. Both forms address the same domain.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_domains_verify_domain",
"title": "Verify domain",
"description": "Restart verification for a custom domain.\n\nAddress the domain by its ID or by its name. Names are unique per workspace, so\n`api.acme.com` is enough.\n\nCall this after you correct the DNS records of a domain that shows `failed`, or to give a\n`pending` domain a new 24-hour verification period. The domain goes back to `pending` and\nthe 24-hour period starts again.\n\nThe endpoint returns when Unkey accepts the retry. Poll `domains.getDomain` for the result.\n\nA domain that is already `verified` returns a 412.\n\n**Required Permissions**\n\nYour root key must have `write` on the domain:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/domains/<domain_id>#write`\n- `unkey:v1:<workspace_id>:projects/*/apps/*/environments/*/domains/*#write` (all domains in your workspace)\n",
"inputSchema": {
"type": "object",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"maxLength": 253,
"minLength": 4,
"description": "Identifies a domain by its name or by its ID. Send the fully qualified domain name, such as\n'api.acme.com', without a scheme, port, or path, or send the domain ID that\ndomains.createDomain returns. You can send an internationalized name in Unicode or in\nPunycode form. Both forms address the same domain.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description80/100
Retrieve a single environment by its id.
Use this to fetch environment details after creation or to verify an environment exists before performing operations.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_environment` (to read any environment)
- `environment.<environment_id>.read_environment` (to read a specific environment)
Describe the returned information so the agent knows whether it will answer the request.
Inputs54/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_environments_get_environment",
"title": "Get environment",
"description": "Retrieve a single environment by its id.\n\nUse this to fetch environment details after creation or to verify an environment exists before performing operations.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `environment.*.read_environment` (to read any environment)\n- `environment.<environment_id>.read_environment` (to read a specific environment)\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description97/100
Retrieve the environment variables for an environment.
Identify the environment by its project, app, and environment identifiers.
Results are ordered by variable id and paginated; when `hasMore` is true,
pass the returned `cursor` to fetch the next page.
`recoverable` variables are returned with their decrypted plaintext value.
`writeonly` variables never expose a value: only the key, kind, and
description are returned.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_environment_variables` (for any environment)
- `environment.<environment_id>.read_environment_variables` (for a specific environment)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response to fetch the next page.
Use when `hasMore: true` in the previous response.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of variables to return per request.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_environments_list_environment_variables",
"title": "List environment variables",
"description": "Retrieve the environment variables for an environment.\n\nIdentify the environment by its project, app, and environment identifiers.\nResults are ordered by variable id and paginated; when `hasMore` is true,\npass the returned `cursor` to fetch the next page.\n\n`recoverable` variables are returned with their decrypted plaintext value.\n`writeonly` variables never expose a value: only the key, kind, and\ndescription are returned.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `environment.*.read_environment_variables` (for any environment)\n- `environment.<environment_id>.read_environment_variables` (for a specific environment)\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of variables to return per request."
},
"cursor": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Pagination cursor from a previous response to fetch the next page.\nUse when `hasMore: true` in the previous response.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description90/100
Retrieve the environments within an app.
Use this to enumerate every environment in an app. Identify the app by its project slug and app slug. Results are ordered by environment id. An app has only a handful of environments, so all of them are returned in a single response.
**Required Permissions**
Your root key must have the following permission:
- `environment.*.read_environment` (to read environments in any app)
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_environments_list_environments",
"title": "List environments",
"description": "Retrieve the environments within an app.\n\nUse this to enumerate every environment in an app. Identify the app by its project slug and app slug. Results are ordered by environment id. An app has only a handful of environments, so all of them are returned in a single response.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `environment.*.read_environment` (to read environments in any app)\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description97/100
Remove environment variables from an environment in a single atomic request.
This operation only deletes keys by name. Keys in the payload that exist are
removed; keys that are not present are ignored, since their absence already
matches the requested state. To replace or update values, use
`setEnvironmentVariables` instead. The whole operation is atomic: if any part
fails the environment is left unchanged.
Duplicate keys in the payload collapse to a single removal. Values are never
read or returned.
**Required Permissions**
Your root key must have `delete` permission on the environment's variable collection:
`unkey:v1:{workspace_id}:projects/{project_id}/apps/{app_id}/environments/{environment_id}/variables/*#delete`.
Replace the placeholders with resource IDs, not names or slugs. A broader
permission that covers this collection also grants access.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
variables
The names of the variables to remove. Keys that exist are deleted; keys
that are not present are ignored, since their absence already matches the
requested state.
Duplicate keys collapse to a single removal. The whole operation is atomic:
if any part fails the environment is left unchanged. Limited to 50
variables per request.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_environments_remove_environment_variables",
"title": "Remove environment variables",
"description": "Remove environment variables from an environment in a single atomic request.\n\nThis operation only deletes keys by name. Keys in the payload that exist are\nremoved; keys that are not present are ignored, since their absence already\nmatches the requested state. To replace or update values, use\n`setEnvironmentVariables` instead. The whole operation is atomic: if any part\nfails the environment is left unchanged.\n\nDuplicate keys in the payload collapse to a single removal. Values are never\nread or returned.\n\n**Required Permissions**\n\nYour root key must have `delete` permission on the environment's variable collection:\n`unkey:v1:{workspace_id}:projects/{project_id}/apps/{app_id}/environments/{environment_id}/variables/*#delete`.\n\nReplace the placeholders with resource IDs, not names or slugs. A broader\npermission that covers this collection also grants access.\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment",
"variables"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"variables": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
"maxLength": 256,
"minLength": 1,
"description": "The name of a variable to remove. Must be a POSIX shell name: letters,\ndigits, and underscores only, and must not start with a digit.\n"
},
"maxItems": 50,
"minItems": 1,
"description": "The names of the variables to remove. Keys that exist are deleted; keys\nthat are not present are ignored, since their absence already matches the\nrequested state.\n\nDuplicate keys collapse to a single removal. The whole operation is atomic:\nif any part fails the environment is left unchanged. Limited to 50\nvariables per request.\n"
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Shorten the title to an action and subject; move usage details into the description.
Description95/100
Create or update environment variables for an environment in a single atomic
request.
By default this is an upsert: each variable in the payload is created if new
or fully overwritten if the key already exists, and any variable not in the
payload is left untouched. This lets you change one variable without
re-sending the others, which matters for write-only secrets you can no longer
read back.
Set `prune: true` to make it a full replace instead: after upserting, every
variable not in the payload is deleted. Sending `prune: true` with an empty
`variables` list resets the environment by deleting every variable.
Each variable is written exactly as sent, never merged, so omitted optional
fields fall back to their defaults rather than the previous value. Values are
always encrypted at rest. Set `kind: recoverable` to allow a value to be read
back; it defaults to `writeonly`, which can never be read back through the API.
**Required Permissions**
Your root key must have `write` on the environment's variable collection:
`unkey:v1:{workspace_id}:projects/{project_id}/apps/{app_id}/environments/{environment_id}/variables/*#write`.
When `prune` is true, it must also have `delete` on the same collection:
`unkey:v1:{workspace_id}:projects/{project_id}/apps/{app_id}/environments/{environment_id}/variables/*#delete`.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
prune
Optional. Defaults to false. When false, the variables above are upserted
and any existing variable not in the list is kept. When true, this becomes
a full replace: after upserting, every variable not in the list is deleted.
Combined with an empty `variables` list, `prune: true` resets the entire
environment by deleting every variable.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
variables › items › description
Human-readable description of the variable.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
variables › items › key
The variable name. Must be a POSIX shell name: letters, digits, and
underscores only, and must not start with a digit. Other names are
unreachable from shells and most runtimes.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
variables › items › kind
How the value may be read back. Defaults to `writeonly`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
variables › items › value
The variable value. Always encrypted at rest. The limit is enforced
server-side in UTF-8 bytes, so a multibyte value may be rejected before
it reaches this code-point maximum.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_environments_set_environment_variables",
"title": "Set environment variables",
"description": "Create or update environment variables for an environment in a single atomic\nrequest.\n\nBy default this is an upsert: each variable in the payload is created if new\nor fully overwritten if the key already exists, and any variable not in the\npayload is left untouched. This lets you change one variable without\nre-sending the others, which matters for write-only secrets you can no longer\nread back.\n\nSet `prune: true` to make it a full replace instead: after upserting, every\nvariable not in the payload is deleted. Sending `prune: true` with an empty\n`variables` list resets the environment by deleting every variable.\n\nEach variable is written exactly as sent, never merged, so omitted optional\nfields fall back to their defaults rather than the previous value. Values are\nalways encrypted at rest. Set `kind: recoverable` to allow a value to be read\nback; it defaults to `writeonly`, which can never be read back through the API.\n\n**Required Permissions**\n\nYour root key must have `write` on the environment's variable collection:\n`unkey:v1:{workspace_id}:projects/{project_id}/apps/{app_id}/environments/{environment_id}/variables/*#write`.\n\nWhen `prune` is true, it must also have `delete` on the same collection:\n`unkey:v1:{workspace_id}:projects/{project_id}/apps/{app_id}/environments/{environment_id}/variables/*#delete`.\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment",
"variables"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"prune": {
"type": "boolean",
"default": false,
"description": "Optional. Defaults to false. When false, the variables above are upserted\nand any existing variable not in the list is kept. When true, this becomes\na full replace: after upserting, every variable not in the list is deleted.\nCombined with an empty `variables` list, `prune: true` resets the entire\nenvironment by deleting every variable."
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"variables": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
"maxLength": 256,
"minLength": 1,
"description": "The variable name. Must be a POSIX shell name: letters, digits, and\nunderscores only, and must not start with a digit. Other names are\nunreachable from shells and most runtimes.\n"
},
"kind": {
"allOf": [
{
"enum": [
"recoverable",
"writeonly"
],
"type": "string",
"description": "How the value may be read back. `writeonly` values can never be read back\nthrough the API; `recoverable` values can be decrypted. Values are encrypted\nat rest either way.\n"
}
],
"default": "writeonly",
"description": "How the value may be read back. Defaults to `writeonly`.\n"
},
"value": {
"type": "string",
"maxLength": 16384,
"minLength": 1,
"description": "The variable value. Always encrypted at rest. The limit is enforced\nserver-side in UTF-8 bytes, so a multibyte value may be rejected before\nit reaches this code-point maximum.\n"
},
"description": {
"type": "string",
"maxLength": 255,
"description": "Human-readable description of the variable.\n"
}
},
"description": "A single environment variable to set.",
"additionalProperties": false
},
"maxItems": 50,
"description": "The variables to upsert. Each entry is created if its key is new or fully\noverwritten if the key already exists. Existing variables whose keys are\nnot in this list are left untouched, unless `prune` is true.\n\nEach entry is written exactly as sent, never merged with the current\nstate. Only `value` is required; omitted optional fields (`kind`,\n`description`) fall back to their defaults rather than any previous value,\nso overwriting a variable without a `description` clears it.\n\nEach key may appear at most once; a duplicate key is rejected with a 400.\nThe whole operation is atomic: if any part fails the environment is left\nunchanged. All values are encrypted at rest. Limited to 50 variables per\nrequest.\n"
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Update the build, runtime, and regional settings for an environment.
All settings fields are optional. Omit a field to leave it unchanged. For
nullable fields (`dockerfile`, `healthcheck`, `openapiSpecPath`), send null
to clear the value. When `regions` is present it replaces the full set of
regions for the environment.
**Required Permissions**
Your root key must have `#write` permission on the environment, for example:
- `unkey:v1:<workspace_id>:projects/*/apps/*/environments/*#write` (any environment in your workspace)
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>#write` (a specific environment)
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
autoDeploy
Whether pushes auto-deploy.
Omit to leave unchanged.
Explain the meaning of this value, not just its name.
buildCommand
Overrides the build command auto-detected by Railpack.
Omit to leave unchanged; set null to clear and fall back to auto-detection.
Clear enough to supply this argument.
command
Override container entrypoint command.
Omit to leave unchanged.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dockerfile
Path to the Dockerfile used for builds.
Omit to leave unchanged; set null to clear and fall back to Railpack.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
healthcheck › anyOf › 0 › failureThreshold
Consecutive failures before the container is restarted. Defaults to 3 when omitted.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
healthcheck › anyOf › 0 › initialDelaySeconds
Delay before the first probe runs, in seconds. Defaults to 0 when omitted.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
healthcheck › anyOf › 0 › intervalSeconds
How often the probe runs, in seconds. Defaults to 10 when omitted.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
healthcheck › anyOf › 0 › method
HTTP method used to probe the container.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
healthcheck › anyOf › 0 › path
HTTP path probed on the container. Must start with a slash.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
healthcheck › anyOf › 0 › timeoutSeconds
Per-probe timeout, in seconds. Defaults to 5 when omitted.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
memoryMib
Memory allocation in MiB. Minimum 256, in steps of 256.
The upper bound is your workspace's per-instance quota; exceeding it returns 400.
Omit to leave unchanged.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
openapiSpecPath
Path to the OpenAPI spec file within the build. Must start with a slash.
Omit to leave unchanged; set null to clear.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
port
Container port the app listens on.
Omit to leave unchanged.
Clear enough to supply this argument.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Clear enough to supply this argument.
regions › items › name
Region name, such as us-east-1.
Clear enough to supply this argument.
regions › items › replicas › max
Maximum number of replicas.
Clear enough to supply this argument.
regions › items › replicas › min
Minimum number of replicas.
Clear enough to supply this argument.
rootDirectory
The directory your app lives in. Unkey builds from here.
Use "." for the repository root, or set a subdirectory when your app
is nested (e.g., services/api). Omit to leave unchanged.
Clear enough to supply this argument.
shutdownSignal
Signal sent to the container on shutdown.
Omit to leave unchanged.
Clear enough to supply this argument.
storageMib
Ephemeral storage allocation in MiB, in steps of 512 (0 for none).
The upper bound is your workspace's per-instance quota; exceeding it returns 400.
Omit to leave unchanged.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
upstreamProtocol
Protocol used to reach the upstream container.
Omit to leave unchanged.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
vCpus
CPU allocation in vCPUs. Minimum 0.25 (1/4 vCPU), in steps of 0.25.
The upper bound is your workspace's per-instance quota; exceeding it returns 400.
Omit to leave unchanged.
Clear enough to supply this argument.
watchPaths
Glob patterns that trigger auto-deploys when matching files change.
Do not start a pattern with "/" or "./".
Use "src/**" for everything under a directory and "**/*.go" for a file type.
A pattern with no wildcard matches only that exact file, so "src" is not "src/**".
Omit to leave unchanged. Invalid patterns are rejected with a 400.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_environments_update_settings",
"title": "Update environment settings",
"description": "Update the build, runtime, and regional settings for an environment.\n\nAll settings fields are optional. Omit a field to leave it unchanged. For\nnullable fields (`dockerfile`, `healthcheck`, `openapiSpecPath`), send null\nto clear the value. When `regions` is present it replaces the full set of\nregions for the environment.\n\n**Required Permissions**\n\nYour root key must have `#write` permission on the environment, for example:\n- `unkey:v1:<workspace_id>:projects/*/apps/*/environments/*#write` (any environment in your workspace)\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>#write` (a specific environment)\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"port": {
"type": "integer",
"maximum": 65535,
"minimum": 1,
"description": "Container port the app listens on.\nOmit to leave unchanged.\n"
},
"vCpus": {
"type": "number",
"format": "double",
"minimum": 0.25,
"multipleOf": 0.25,
"description": "CPU allocation in vCPUs. Minimum 0.25 (1/4 vCPU), in steps of 0.25.\nThe upper bound is your workspace's per-instance quota; exceeding it returns 400.\nOmit to leave unchanged.\n"
},
"command": {
"type": "array",
"items": {
"type": "string",
"maxLength": 4096
},
"maxItems": 10,
"description": "Override container entrypoint command.\nOmit to leave unchanged.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"regions": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"replicas"
],
"properties": {
"name": {
"type": "string",
"maxLength": 64,
"minLength": 1,
"description": "Region name, such as us-east-1."
},
"replicas": {
"type": "object",
"required": [
"min",
"max"
],
"properties": {
"max": {
"type": "integer",
"description": "Maximum number of replicas."
},
"min": {
"type": "integer",
"description": "Minimum number of replicas."
}
},
"description": "Min and max replica bounds for autoscaling in a region.",
"additionalProperties": false
}
},
"description": "Replica bounds for a single region the environment deploys to.",
"additionalProperties": false
},
"maxItems": 5,
"minItems": 1,
"description": "Desired set of regions with per-region replica bounds.\nOmit to leave regions unchanged; when present, this replaces the full set\n(regions absent from the list are removed). At least one region is required;\nan empty list is rejected because an environment cannot have zero regions.\n"
},
"memoryMib": {
"type": "integer",
"minimum": 256,
"multipleOf": 256,
"description": "Memory allocation in MiB. Minimum 256, in steps of 256.\nThe upper bound is your workspace's per-instance quota; exceeding it returns 400.\nOmit to leave unchanged.\n"
},
"autoDeploy": {
"type": "boolean",
"description": "Whether pushes auto-deploy.\nOmit to leave unchanged.\n"
},
"dockerfile": {
"type": [
"string",
"null"
],
"maxLength": 500,
"minLength": 1,
"description": "Path to the Dockerfile used for builds.\nOmit to leave unchanged; set null to clear and fall back to Railpack.\n"
},
"storageMib": {
"type": "integer",
"minimum": 0,
"multipleOf": 512,
"description": "Ephemeral storage allocation in MiB, in steps of 512 (0 for none).\nThe upper bound is your workspace's per-instance quota; exceeding it returns 400.\nOmit to leave unchanged.\n"
},
"watchPaths": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"maxItems": 10,
"description": "Glob patterns that trigger auto-deploys when matching files change.\nDo not start a pattern with \"/\" or \"./\".\nUse \"src/**\" for everything under a directory and \"**/*.go\" for a file type.\nA pattern with no wildcard matches only that exact file, so \"src\" is not \"src/**\".\nOmit to leave unchanged. Invalid patterns are rejected with a 400.\n"
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"healthcheck": {
"anyOf": [
{
"type": "object",
"required": [
"method",
"path"
],
"properties": {
"path": {
"type": "string",
"pattern": "^(/[\\w\\-]+)+(\\.[\\w]+)?$",
"maxLength": 512,
"minLength": 1,
"description": "HTTP path probed on the container. Must start with a slash.\n"
},
"method": {
"enum": [
"GET",
"POST"
],
"type": "string",
"description": "HTTP method used to probe the container.\n"
},
"timeoutSeconds": {
"type": "integer",
"maximum": 3600,
"minimum": 1,
"description": "Per-probe timeout, in seconds. Defaults to 5 when omitted.\n"
},
"intervalSeconds": {
"type": "integer",
"maximum": 3600,
"minimum": 1,
"description": "How often the probe runs, in seconds. Defaults to 10 when omitted.\n"
},
"failureThreshold": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Consecutive failures before the container is restarted. Defaults to 3 when omitted.\n"
},
"initialDelaySeconds": {
"type": "integer",
"maximum": 3600,
"minimum": 0,
"description": "Delay before the first probe runs, in seconds. Defaults to 0 when omitted.\n"
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "HTTP healthcheck configuration.\nOmit to leave unchanged; set null to remove.\n"
},
"buildCommand": {
"type": [
"string",
"null"
],
"maxLength": 1000,
"minLength": 1,
"description": "Overrides the build command auto-detected by Railpack.\nOmit to leave unchanged; set null to clear and fall back to auto-detection.\n"
},
"rootDirectory": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "The directory your app lives in. Unkey builds from here.\nUse \".\" for the repository root, or set a subdirectory when your app\nis nested (e.g., services/api). Omit to leave unchanged.\n"
},
"shutdownSignal": {
"enum": [
"SIGTERM",
"SIGINT",
"SIGQUIT",
"SIGKILL"
],
"type": "string",
"description": "Signal sent to the container on shutdown.\nOmit to leave unchanged.\n"
},
"openapiSpecPath": {
"type": [
"string",
"null"
],
"pattern": "^(/[\\w\\-]+)+(\\.[\\w]+)?$",
"maxLength": 512,
"minLength": 1,
"description": "Path to the OpenAPI spec file within the build. Must start with a slash.\nOmit to leave unchanged; set null to clear.\n"
},
"upstreamProtocol": {
"enum": [
"http1",
"h2c"
],
"type": "string",
"description": "Protocol used to reach the upstream container.\nOmit to leave unchanged.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Retrieve an environment's gateway policies in evaluation order: the
gateway evaluates them top to bottom and the first rejection
short-circuits the request.
The full policy list is returned in a single response.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_policies` (for any environment)
- `environment.<environment_id>.read_policies` (for a specific environment)
The description explains the capability, when to use it, and what to expect.
Inputs55/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_gateway_list_policies",
"title": "List policies",
"description": "Retrieve an environment's gateway policies in evaluation order: the\ngateway evaluates them top to bottom and the first rejection\nshort-circuits the request.\n\nThe full policy list is returned in a single response.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `environment.*.read_policies` (for any environment)\n- `environment.<environment_id>.read_policies` (for a specific environment)\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description91/100
Replace an environment's gateway policies in a single atomic request.
Policies run at the edge before requests reach your app: verify API keys,
rate limit, block requests outright, or validate them against your
OpenAPI spec.
Policies are an ordered list: the gateway evaluates them top to bottom
and the first rejection short-circuits the request.
Each policy sets exactly one of `keyauth`, `ratelimit`, `firewall` or
`openapi`, plus optional `match` expressions restricting which requests
it applies to.
Every call is a full replace: the environment's policies become exactly
the request list in the given order, and the server generates a fresh id
for each one. An empty list removes all policies. The operation is
atomic: if any policy is invalid, nothing is written.
**Required Permissions**
Your root key must have both permissions on the target environment's gateway policies:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/gateway/policies/*#write`
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/gateway/policies/*#delete`
Replace the placeholders with resource IDs. Wildcard grants can cover multiple
resources, but access remains limited to the root key's workspace.
The description explains the capability, when to use it, and what to expect.
Inputs73/100
45 of 54 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
policies › items › enabled
Disabled policies are stored but skipped during evaluation.
Clear enough to supply this argument.
policies › items › firewall › action
What to do with matching requests.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
policies › items › keyauth › credits
Usage credits a matching request deducts from the verified key. Defaults
to 1. Set to 0 to verify the key without spending credits, or to a higher
value to charge more per request. Keys with unlimited usage are
unaffected.
Clear enough to supply this argument.
policies › items › keyauth › keyspaces
Keyspaces to verify keys against, referenced by id. All keyspaces must
belong to your workspace.
Matches when the remote IP is in none of these ranges. Entries are CIDRs
such as `198.51.100.0/24` or single addresses such as `198.51.100.7`.
Clear enough to supply this argument.
policies › items › name
Human-readable name shown in the dashboard.
Clear enough to supply this argument.
policies › items › openapi
Validates matching requests against the app's uploaded OpenAPI spec. Has no
configuration of its own. If no spec has been uploaded for the deployment,
the policy is a no-op and requests pass through unvalidated.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_gateway_set_policies",
"title": "Set policies",
"description": "Replace an environment's gateway policies in a single atomic request.\nPolicies run at the edge before requests reach your app: verify API keys,\nrate limit, block requests outright, or validate them against your\nOpenAPI spec.\n\nPolicies are an ordered list: the gateway evaluates them top to bottom\nand the first rejection short-circuits the request.\n\nEach policy sets exactly one of `keyauth`, `ratelimit`, `firewall` or\n`openapi`, plus optional `match` expressions restricting which requests\nit applies to.\n\nEvery call is a full replace: the environment's policies become exactly\nthe request list in the given order, and the server generates a fresh id\nfor each one. An empty list removes all policies. The operation is\natomic: if any policy is invalid, nothing is written.\n\n**Required Permissions**\n\nYour root key must have both permissions on the target environment's gateway policies:\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/gateway/policies/*#write`\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/gateway/policies/*#delete`\n\nReplace the placeholders with resource IDs. Wildcard grants can cover multiple\nresources, but access remains limited to the root key's workspace.\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment",
"policies"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"policies": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"enabled"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Human-readable name shown in the dashboard."
},
"match": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "object",
"properties": {
"exact": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input equals this value."
},
"regex": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input satisfies this RE2 regular expression. Invalid\npatterns are rejected when the policy is created."
},
"prefix": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input starts with this value."
},
"ignoreCase": {
"type": "boolean",
"description": "Compare case-insensitively. May accompany any match mode."
}
},
"description": "String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.",
"additionalProperties": false
}
},
"description": "Matches on the request path.",
"additionalProperties": false
},
"header": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"value": {
"type": "object",
"properties": {
"exact": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input equals this value."
},
"regex": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input satisfies this RE2 regular expression. Invalid\npatterns are rejected when the policy is created."
},
"prefix": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input starts with this value."
},
"ignoreCase": {
"type": "boolean",
"description": "Compare case-insensitively. May accompany any match mode."
}
},
"description": "String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.",
"additionalProperties": false
},
"present": {
"type": "boolean",
"description": "Matches when the field is present if true, or absent if false, regardless of value.\nDefaults to true when neither `present` nor `value` is supplied."
}
},
"description": "Matches a named request field (header or query parameter). Set `present` or\n`value`, not both. If neither is supplied, the field must be present.",
"additionalProperties": false
},
"method": {
"type": "object",
"required": [
"methods"
],
"properties": {
"methods": {
"type": "array",
"items": {
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE",
"HEAD",
"OPTIONS"
],
"type": "string"
},
"minItems": 1
}
},
"description": "Matches when the request method is one of the listed methods.",
"additionalProperties": false
},
"remoteIp": {
"type": "object",
"properties": {
"in": {
"type": "array",
"items": {
"type": "string",
"maxLength": 43,
"minLength": 1
},
"maxItems": 100,
"minItems": 1,
"description": "Matches when the remote IP is in at least one of these ranges. Entries\nare CIDRs such as `203.0.113.0/24` or single addresses such as\n`203.0.113.7`."
},
"notIn": {
"type": "array",
"items": {
"type": "string",
"maxLength": 43,
"minLength": 1
},
"maxItems": 100,
"minItems": 1,
"description": "Matches when the remote IP is in none of these ranges. Entries are CIDRs\nsuch as `198.51.100.0/24` or single addresses such as `198.51.100.7`."
}
},
"description": "Matches the remote IP against IPv4 or IPv6 CIDR ranges. Exactly one of `in`\nor `notIn` must be set. Entries are rejected if they have host bits set (such\nas `10.1.2.3/8`), are IPv4-mapped IPv6 addresses, or carry a zone. Single\naddresses are returned as full-length prefixes, such as `203.0.113.7/32`.",
"additionalProperties": false
},
"queryParam": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"value": {
"type": "object",
"properties": {
"exact": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input equals this value."
},
"regex": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input satisfies this RE2 regular expression. Invalid\npatterns are rejected when the policy is created."
},
"prefix": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input starts with this value."
},
"ignoreCase": {
"type": "boolean",
"description": "Compare case-insensitively. May accompany any match mode."
}
},
"description": "String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.",
"additionalProperties": false
},
"present": {
"type": "boolean",
"description": "Matches when the field is present if true, or absent if false, regardless of value.\nDefaults to true when neither `present` nor `value` is supplied."
}
},
"description": "Matches a named request field (header or query parameter). Set `present` or\n`value`, not both. If neither is supplied, the field must be present.",
"additionalProperties": false
}
},
"description": "A single request match expression. Exactly one of `path`, `method`,\n`header`, `queryParam` or `remoteIp` must be set.",
"additionalProperties": false
},
"maxItems": 10,
"description": "Optional request matchers. The policy applies only to requests matching\nall expressions; omit to apply to every request."
},
"enabled": {
"type": "boolean",
"description": "Disabled policies are stored but skipped during evaluation."
},
"keyauth": {
"type": "object",
"required": [
"keyspaces"
],
"properties": {
"credits": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Usage credits a matching request deducts from the verified key. Defaults\nto 1. Set to 0 to verify the key without spending credits, or to a higher\nvalue to charge more per request. Keys with unlimited usage are\nunaffected."
},
"keyspaces": {
"type": "array",
"items": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"maxItems": 5,
"minItems": 1,
"description": "Keyspaces to verify keys against, referenced by id. All keyspaces must\nbelong to your workspace."
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"bearer": {
"type": "object",
"properties": {},
"description": "Extract the key from the `Authorization Bearer` header.",
"additionalProperties": false
},
"header": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"stripPrefix": {
"type": "string",
"maxLength": 256,
"description": "Optional prefix removed from the header value before verification."
}
},
"description": "Extract the key from a custom header.",
"additionalProperties": false
},
"queryParam": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
}
},
"description": "Extract the key from a query parameter.",
"additionalProperties": false
}
},
"description": "Where to look for the API key on incoming requests. Exactly one of\n`bearer`, `header` or `queryParam` must be set.",
"additionalProperties": false
},
"description": "Where to look for the key on incoming requests, tried in order. Defaults\nto the `Authorization Bearer` header when omitted."
},
"ratelimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"cost": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Cost charged against the limit per request. Defaults to 1."
},
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Name of a rate limit configured on the key or its identity, or the name\nof the inline override defined by `limit` and `duration`."
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Inline override: maximum number of operations per window. Must be set\ntogether with `duration`."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Inline override: window duration in milliseconds. Must be set together\nwith `limit`."
}
},
"description": "A rate limit applied during key verification. `limit` and `duration`\nmust be set together or both omitted; a partial pair is rejected.",
"additionalProperties": false
},
"maxItems": 10,
"description": "Rate limits applied during key verification."
},
"permissionQuery": {
"type": "string",
"maxLength": 1000,
"description": "Optional permission query the verified key must satisfy, e.g.\n`documents.read AND documents.write`."
}
},
"description": "Verifies Unkey API keys on matching requests.",
"additionalProperties": false
},
"logging": {
"type": "object",
"properties": {
"query": {
"type": "boolean",
"default": false,
"description": "Capture the query string and query parameters. Query data is a\nseparate opt-in because URLs can contain secrets, for example\n`?api_key=...`."
},
"requestBody": {
"type": "boolean",
"default": false,
"description": "Capture the request body, up to the capture limit."
},
"responseBody": {
"type": "boolean",
"default": false,
"description": "Capture the response body, up to the capture limit."
},
"requestHeaders": {
"type": "boolean",
"default": false,
"description": "Capture request headers, the user agent, and the client IP. The user\nagent and client IP are included because they identify the client."
},
"responseHeaders": {
"type": "boolean",
"default": false,
"description": "Capture response headers."
}
},
"description": "Adds request data to the log entries of matching requests. The gateway\nalways records a basic log entry for every request: method, host, path,\nstatus, and latency. Each capture setting is a separate opt-in: request\nheaders, response headers, request body, response body, and query data.\nThe policy's `match` expressions select the requests. A policy without\n`match` expressions matches every request. If more than one enabled\nlogging policy matches a request, the gateway combines their settings.\nThe gateway always redacts the `Authorization` header and configured key\nlocations before it stores headers or query data.",
"additionalProperties": false
},
"openapi": {
"type": "object",
"properties": {},
"description": "Validates matching requests against the app's uploaded OpenAPI spec. Has no\nconfiguration of its own. If no spec has been uploaded for the deployment,\nthe policy is a no-op and requests pass through unvalidated.",
"additionalProperties": false
},
"firewall": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"enum": [
"ACTION_DENY"
],
"type": "string",
"description": "What to do with matching requests."
}
},
"description": "Blocks matching requests.",
"additionalProperties": false
},
"ratelimit": {
"type": "object",
"required": [
"limit",
"windowMs"
],
"properties": {
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Maximum number of requests per window."
},
"windowMs": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Window duration in milliseconds."
},
"identifier": {
"allOf": [
{
"type": "object",
"properties": {
"path": {
"type": "object",
"properties": {},
"description": "Rate limit by the request path.",
"additionalProperties": false
},
"header": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
}
},
"description": "Rate limit by the value of a request header.",
"additionalProperties": false
},
"remoteIp": {
"type": "object",
"properties": {},
"description": "Rate limit by the remote IP.",
"additionalProperties": false
},
"principalField": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Rate limit by a field extracted from the authenticated principal.",
"additionalProperties": false
},
"authenticatedSubject": {
"type": "object",
"properties": {},
"description": "Rate limit by the authenticated subject (e.g. the verified key).",
"additionalProperties": false
}
},
"description": "How requests are grouped for rate limiting. Exactly one of `remoteIp`,\n`header`, `authenticatedSubject`, `path` or `principalField` must be set.",
"additionalProperties": false
}
],
"deprecated": true,
"description": "Deprecated. Accepted for compatibility with old clients. Use\n`identifiers` with one entry. Responses always return `identifiers`."
},
"identifiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "object",
"properties": {},
"description": "Rate limit by the request path.",
"additionalProperties": false
},
"header": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
}
},
"description": "Rate limit by the value of a request header.",
"additionalProperties": false
},
"remoteIp": {
"type": "object",
"properties": {},
"description": "Rate limit by the remote IP.",
"additionalProperties": false
},
"principalField": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Rate limit by a field extracted from the authenticated principal.",
"additionalProperties": false
},
"authenticatedSubject": {
"type": "object",
"properties": {},
"description": "Rate limit by the authenticated subject (e.g. the verified key).",
"additionalProperties": false
}
},
"description": "How requests are grouped for rate limiting. Exactly one of `remoteIp`,\n`header`, `authenticatedSubject`, `path` or `principalField` must be set.",
"additionalProperties": false
},
"maxItems": 5,
"minItems": 1,
"description": "Ordered list of sources that form a compound rate limit key. The\ngateway resolves each source for each request. Each unique\ncombination of resolved values has its own counter. All counters use\nthe same limit and window. Example: `[authenticatedSubject, path]`\nlimits each subject separately on each path."
}
},
"description": "Rate limits matching requests. Set `identifiers` with 1 to 5 sources.\nThe deprecated `identifier` field is accepted in place of a one-entry\n`identifiers` list; set exactly one of the two.",
"additionalProperties": false
}
},
"description": "A gateway policy. Exactly one of `keyauth`, `ratelimit`, `firewall`,\n`openapi` or `logging` must be set. The server generates an id for every\npolicy it stores.",
"additionalProperties": false
},
"maxItems": 50,
"description": "The environment's complete policy list, in evaluation order. Every call\nreplaces all stored policies with exactly this list; an empty list\nremoves every policy. The operation is atomic: if any policy is\ninvalid, nothing is written. An environment can hold at most 50\npolicies."
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Shorten the title to an action and subject; move usage details into the description.
Description93/100
Update a single policy in place without resending the environment's full
policy list. The policy keeps its id and its position in the evaluation
order, and all other policies are untouched.
Omitted fields keep their stored values; at least one updatable field
must be provided. Setting `match` to null removes all match expressions
so the policy applies to every request. Providing one of `keyauth`,
`ratelimit`, `firewall` or `openapi` replaces the policy's rule
entirely, including switching its type; at most one may be set.
Policy ids are regenerated whenever `gateway.setPolicies` replaces the
list, so fetch current ids via `gateway.listPolicies` first.
**Required Permissions**
Your root key must have `write` permission on the policy:
`unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/gateway/policies/<policy_id>#write`.
Use `*` in place of a resource ID to grant access to all resources at that level.
The description explains the capability, when to use it, and what to expect.
Inputs76/100
46 of 55 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
app
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
enabled
Enable or disable the policy. Disabled policies are stored but skipped
during evaluation. Omit to keep the current setting.
Clear enough to supply this argument.
environment
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
firewall › action
What to do with matching requests.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyauth › credits
Usage credits a matching request deducts from the verified key. Defaults
to 1. Set to 0 to verify the key without spending credits, or to a higher
value to charge more per request. Keys with unlimited usage are
unaffected.
Clear enough to supply this argument.
keyauth › keyspaces
Keyspaces to verify keys against, referenced by id. All keyspaces must
belong to your workspace.
Clear enough to supply this argument.
keyauth › locations › items › bearer
Extract the key from the `Authorization Bearer` header.
Clear enough to supply this argument.
keyauth › locations › items › header › name
Not provided
Missing description. Explain what this value means and how to supply it.
Optional prefix removed from the header value before verification.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyauth › locations › items › queryParam › name
Not provided
Missing description. Explain what this value means and how to supply it.
keyauth › permissionQuery
Optional permission query the verified key must satisfy, e.g.
`documents.read AND documents.write`.
Clear enough to supply this argument.
keyauth › ratelimits › items › cost
Cost charged against the limit per request. Defaults to 1.
Clear enough to supply this argument.
keyauth › ratelimits › items › duration
Inline override: window duration in milliseconds. Must be set together
with `limit`.
Clear enough to supply this argument.
keyauth › ratelimits › items › limit
Inline override: maximum number of operations per window. Must be set
together with `duration`.
Clear enough to supply this argument.
keyauth › ratelimits › items › name
Name of a rate limit configured on the key or its identity, or the name
of the inline override defined by `limit` and `duration`.
Clear enough to supply this argument.
logging › query
Capture the query string and query parameters. Query data is a
separate opt-in because URLs can contain secrets, for example
`?api_key=...`.
Clear enough to supply this argument.
logging › requestBody
Capture the request body, up to the capture limit.
Clear enough to supply this argument.
logging › requestHeaders
Capture request headers, the user agent, and the client IP. The user
agent and client IP are included because they identify the client.
Clear enough to supply this argument.
logging › responseBody
Capture the response body, up to the capture limit.
Clear enough to supply this argument.
logging › responseHeaders
Capture response headers.
Clear enough to supply this argument.
match › items › header › name
Not provided
Missing description. Explain what this value means and how to supply it.
match › items › header › present
Matches when the field is present if true, or absent if false, regardless of value.
Defaults to true when neither `present` nor `value` is supplied.
Clear enough to supply this argument.
match › items › header › value › exact
Matches when the input equals this value.
Clear enough to supply this argument.
match › items › header › value › ignoreCase
Compare case-insensitively. May accompany any match mode.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › header › value › prefix
Matches when the input starts with this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › header › value › regex
Matches when the input satisfies this RE2 regular expression. Invalid
patterns are rejected when the policy is created.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › method › methods
Not provided
Missing description. Explain what this value means and how to supply it.
match › items › path › path › exact
Matches when the input equals this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › path › path › ignoreCase
Compare case-insensitively. May accompany any match mode.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › path › path › prefix
Matches when the input starts with this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › path › path › regex
Matches when the input satisfies this RE2 regular expression. Invalid
patterns are rejected when the policy is created.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › queryParam › name
Not provided
Missing description. Explain what this value means and how to supply it.
match › items › queryParam › present
Matches when the field is present if true, or absent if false, regardless of value.
Defaults to true when neither `present` nor `value` is supplied.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › queryParam › value › exact
Matches when the input equals this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match › items › queryParam › value › ignoreCase
Compare case-insensitively. May accompany any match mode.
Clear enough to supply this argument.
match › items › queryParam › value › prefix
Matches when the input starts with this value.
Clear enough to supply this argument.
match › items › queryParam › value › regex
Matches when the input satisfies this RE2 regular expression. Invalid
patterns are rejected when the policy is created.
Clear enough to supply this argument.
match › items › remoteIp › in
Matches when the remote IP is in at least one of these ranges. Entries
are CIDRs such as `203.0.113.0/24` or single addresses such as
`203.0.113.7`.
Clear enough to supply this argument.
match › items › remoteIp › notIn
Matches when the remote IP is in none of these ranges. Entries are CIDRs
such as `198.51.100.0/24` or single addresses such as `198.51.100.7`.
Clear enough to supply this argument.
name
New human-readable name. Omit to keep the current name.
Clear enough to supply this argument.
openapi
Validates matching requests against the app's uploaded OpenAPI spec. Has no
configuration of its own. If no spec has been uploaded for the deployment,
the policy is a no-op and requests pass through unvalidated.
Clear enough to supply this argument.
policyId
Id of the policy to update, as returned by `gateway.listPolicies`.
Ids are regenerated whenever `gateway.setPolicies` replaces the list,
so list the policies first if you are unsure the id is current.
Clear enough to supply this argument.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_gateway_update_policy",
"title": "Update policy",
"description": "Update a single policy in place without resending the environment's full\npolicy list. The policy keeps its id and its position in the evaluation\norder, and all other policies are untouched.\n\nOmitted fields keep their stored values; at least one updatable field\nmust be provided. Setting `match` to null removes all match expressions\nso the policy applies to every request. Providing one of `keyauth`,\n`ratelimit`, `firewall` or `openapi` replaces the policy's rule\nentirely, including switching its type; at most one may be set.\n\nPolicy ids are regenerated whenever `gateway.setPolicies` replaces the\nlist, so fetch current ids via `gateway.listPolicies` first.\n\n**Required Permissions**\n\nYour root key must have `write` permission on the policy:\n`unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/gateway/policies/<policy_id>#write`.\nUse `*` in place of a resource ID to grant access to all resources at that level.\n",
"inputSchema": {
"type": "object",
"required": [
"project",
"app",
"environment",
"policyId"
],
"properties": {
"app": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "New human-readable name. Omit to keep the current name."
},
"match": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"path": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "object",
"properties": {
"exact": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input equals this value."
},
"regex": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input satisfies this RE2 regular expression. Invalid\npatterns are rejected when the policy is created."
},
"prefix": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input starts with this value."
},
"ignoreCase": {
"type": "boolean",
"description": "Compare case-insensitively. May accompany any match mode."
}
},
"description": "String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.",
"additionalProperties": false
}
},
"description": "Matches on the request path.",
"additionalProperties": false
},
"header": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"value": {
"type": "object",
"properties": {
"exact": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input equals this value."
},
"regex": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input satisfies this RE2 regular expression. Invalid\npatterns are rejected when the policy is created."
},
"prefix": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input starts with this value."
},
"ignoreCase": {
"type": "boolean",
"description": "Compare case-insensitively. May accompany any match mode."
}
},
"description": "String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.",
"additionalProperties": false
},
"present": {
"type": "boolean",
"description": "Matches when the field is present if true, or absent if false, regardless of value.\nDefaults to true when neither `present` nor `value` is supplied."
}
},
"description": "Matches a named request field (header or query parameter). Set `present` or\n`value`, not both. If neither is supplied, the field must be present.",
"additionalProperties": false
},
"method": {
"type": "object",
"required": [
"methods"
],
"properties": {
"methods": {
"type": "array",
"items": {
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE",
"HEAD",
"OPTIONS"
],
"type": "string"
},
"minItems": 1
}
},
"description": "Matches when the request method is one of the listed methods.",
"additionalProperties": false
},
"remoteIp": {
"type": "object",
"properties": {
"in": {
"type": "array",
"items": {
"type": "string",
"maxLength": 43,
"minLength": 1
},
"maxItems": 100,
"minItems": 1,
"description": "Matches when the remote IP is in at least one of these ranges. Entries\nare CIDRs such as `203.0.113.0/24` or single addresses such as\n`203.0.113.7`."
},
"notIn": {
"type": "array",
"items": {
"type": "string",
"maxLength": 43,
"minLength": 1
},
"maxItems": 100,
"minItems": 1,
"description": "Matches when the remote IP is in none of these ranges. Entries are CIDRs\nsuch as `198.51.100.0/24` or single addresses such as `198.51.100.7`."
}
},
"description": "Matches the remote IP against IPv4 or IPv6 CIDR ranges. Exactly one of `in`\nor `notIn` must be set. Entries are rejected if they have host bits set (such\nas `10.1.2.3/8`), are IPv4-mapped IPv6 addresses, or carry a zone. Single\naddresses are returned as full-length prefixes, such as `203.0.113.7/32`.",
"additionalProperties": false
},
"queryParam": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"value": {
"type": "object",
"properties": {
"exact": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input equals this value."
},
"regex": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input satisfies this RE2 regular expression. Invalid\npatterns are rejected when the policy is created."
},
"prefix": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Matches when the input starts with this value."
},
"ignoreCase": {
"type": "boolean",
"description": "Compare case-insensitively. May accompany any match mode."
}
},
"description": "String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.",
"additionalProperties": false
},
"present": {
"type": "boolean",
"description": "Matches when the field is present if true, or absent if false, regardless of value.\nDefaults to true when neither `present` nor `value` is supplied."
}
},
"description": "Matches a named request field (header or query parameter). Set `present` or\n`value`, not both. If neither is supplied, the field must be present.",
"additionalProperties": false
}
},
"description": "A single request match expression. Exactly one of `path`, `method`,\n`header`, `queryParam` or `remoteIp` must be set.",
"additionalProperties": false
},
"maxItems": 10,
"description": "Replaces all match expressions. Set null to remove them so the policy\napplies to every request. Omit to keep the current expressions."
},
"enabled": {
"type": "boolean",
"description": "Enable or disable the policy. Disabled policies are stored but skipped\nduring evaluation. Omit to keep the current setting."
},
"keyauth": {
"type": "object",
"required": [
"keyspaces"
],
"properties": {
"credits": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Usage credits a matching request deducts from the verified key. Defaults\nto 1. Set to 0 to verify the key without spending credits, or to a higher\nvalue to charge more per request. Keys with unlimited usage are\nunaffected."
},
"keyspaces": {
"type": "array",
"items": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"maxItems": 5,
"minItems": 1,
"description": "Keyspaces to verify keys against, referenced by id. All keyspaces must\nbelong to your workspace."
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"bearer": {
"type": "object",
"properties": {},
"description": "Extract the key from the `Authorization Bearer` header.",
"additionalProperties": false
},
"header": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
},
"stripPrefix": {
"type": "string",
"maxLength": 256,
"description": "Optional prefix removed from the header value before verification."
}
},
"description": "Extract the key from a custom header.",
"additionalProperties": false
},
"queryParam": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
}
},
"description": "Extract the key from a query parameter.",
"additionalProperties": false
}
},
"description": "Where to look for the API key on incoming requests. Exactly one of\n`bearer`, `header` or `queryParam` must be set.",
"additionalProperties": false
},
"description": "Where to look for the key on incoming requests, tried in order. Defaults\nto the `Authorization Bearer` header when omitted."
},
"ratelimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"cost": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Cost charged against the limit per request. Defaults to 1."
},
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Name of a rate limit configured on the key or its identity, or the name\nof the inline override defined by `limit` and `duration`."
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Inline override: maximum number of operations per window. Must be set\ntogether with `duration`."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Inline override: window duration in milliseconds. Must be set together\nwith `limit`."
}
},
"description": "A rate limit applied during key verification. `limit` and `duration`\nmust be set together or both omitted; a partial pair is rejected.",
"additionalProperties": false
},
"maxItems": 10,
"description": "Rate limits applied during key verification."
},
"permissionQuery": {
"type": "string",
"maxLength": 1000,
"description": "Optional permission query the verified key must satisfy, e.g.\n`documents.read AND documents.write`."
}
},
"description": "Verifies Unkey API keys on matching requests.",
"additionalProperties": false
},
"logging": {
"type": "object",
"properties": {
"query": {
"type": "boolean",
"default": false,
"description": "Capture the query string and query parameters. Query data is a\nseparate opt-in because URLs can contain secrets, for example\n`?api_key=...`."
},
"requestBody": {
"type": "boolean",
"default": false,
"description": "Capture the request body, up to the capture limit."
},
"responseBody": {
"type": "boolean",
"default": false,
"description": "Capture the response body, up to the capture limit."
},
"requestHeaders": {
"type": "boolean",
"default": false,
"description": "Capture request headers, the user agent, and the client IP. The user\nagent and client IP are included because they identify the client."
},
"responseHeaders": {
"type": "boolean",
"default": false,
"description": "Capture response headers."
}
},
"description": "Adds request data to the log entries of matching requests. The gateway\nalways records a basic log entry for every request: method, host, path,\nstatus, and latency. Each capture setting is a separate opt-in: request\nheaders, response headers, request body, response body, and query data.\nThe policy's `match` expressions select the requests. A policy without\n`match` expressions matches every request. If more than one enabled\nlogging policy matches a request, the gateway combines their settings.\nThe gateway always redacts the `Authorization` header and configured key\nlocations before it stores headers or query data.",
"additionalProperties": false
},
"openapi": {
"type": "object",
"properties": {},
"description": "Validates matching requests against the app's uploaded OpenAPI spec. Has no\nconfiguration of its own. If no spec has been uploaded for the deployment,\nthe policy is a no-op and requests pass through unvalidated.",
"additionalProperties": false
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"firewall": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"enum": [
"ACTION_DENY"
],
"type": "string",
"description": "What to do with matching requests."
}
},
"description": "Blocks matching requests.",
"additionalProperties": false
},
"policyId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Id of the policy to update, as returned by `gateway.listPolicies`.\nIds are regenerated whenever `gateway.setPolicies` replaces the list,\nso list the policies first if you are unsure the id is current."
},
"ratelimit": {
"type": "object",
"required": [
"limit",
"windowMs"
],
"properties": {
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Maximum number of requests per window."
},
"windowMs": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Window duration in milliseconds."
},
"identifier": {
"allOf": [
{
"type": "object",
"properties": {
"path": {
"type": "object",
"properties": {},
"description": "Rate limit by the request path.",
"additionalProperties": false
},
"header": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
}
},
"description": "Rate limit by the value of a request header.",
"additionalProperties": false
},
"remoteIp": {
"type": "object",
"properties": {},
"description": "Rate limit by the remote IP.",
"additionalProperties": false
},
"principalField": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Rate limit by a field extracted from the authenticated principal.",
"additionalProperties": false
},
"authenticatedSubject": {
"type": "object",
"properties": {},
"description": "Rate limit by the authenticated subject (e.g. the verified key).",
"additionalProperties": false
}
},
"description": "How requests are grouped for rate limiting. Exactly one of `remoteIp`,\n`header`, `authenticatedSubject`, `path` or `principalField` must be set.",
"additionalProperties": false
}
],
"deprecated": true,
"description": "Deprecated. Accepted for compatibility with old clients. Use\n`identifiers` with one entry. Responses always return `identifiers`."
},
"identifiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "object",
"properties": {},
"description": "Rate limit by the request path.",
"additionalProperties": false
},
"header": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1
}
},
"description": "Rate limit by the value of a request header.",
"additionalProperties": false
},
"remoteIp": {
"type": "object",
"properties": {},
"description": "Rate limit by the remote IP.",
"additionalProperties": false
},
"principalField": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Rate limit by a field extracted from the authenticated principal.",
"additionalProperties": false
},
"authenticatedSubject": {
"type": "object",
"properties": {},
"description": "Rate limit by the authenticated subject (e.g. the verified key).",
"additionalProperties": false
}
},
"description": "How requests are grouped for rate limiting. Exactly one of `remoteIp`,\n`header`, `authenticatedSubject`, `path` or `principalField` must be set.",
"additionalProperties": false
},
"maxItems": 5,
"minItems": 1,
"description": "Ordered list of sources that form a compound rate limit key. The\ngateway resolves each source for each request. Each unique\ncombination of resolved values has its own counter. All counters use\nthe same limit and window. Example: `[authenticatedSubject, path]`\nlimits each subject separately on each path."
}
},
"description": "Rate limits matching requests. Set `identifiers` with 1 to 5 sources.\nThe deprecated `identifier` field is accepted in place of a one-entry\n`identifiers` list; set exactly one of the two.",
"additionalProperties": false
},
"environment": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"description": "Partial update of a single policy. Omitted fields keep their stored\nvalues; at least one updatable field must be provided. Providing one of\n`keyauth`, `ratelimit`, `firewall`, `openapi` or `logging` replaces the\npolicy's rule entirely, including switching its type; at most one may be\nset.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Start installing the Unkey GitHub App for your workspace. Returns a GitHub
App install URL: open it in a browser to install the app and grant
repository access. After installation GitHub returns to Unkey, which binds
the installation to your workspace and lands you in the workspace settings.
Installation is workspace-wide and takes no parameters. Once installed, link
repositories to individual apps with the `git` field on `apps.createApp` and
`apps.updateApp`.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:github/apps/*#write`
Replace `<workspace_id>` with the authenticated workspace ID.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
No input fields.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_github_install_app",
"title": "Install GitHub App",
"description": "Start installing the Unkey GitHub App for your workspace. Returns a GitHub\nApp install URL: open it in a browser to install the app and grant\nrepository access. After installation GitHub returns to Unkey, which binds\nthe installation to your workspace and lands you in the workspace settings.\n\nInstallation is workspace-wide and takes no parameters. Once installed, link\nrepositories to individual apps with the `git` field on `apps.createApp` and\n`apps.updateApp`.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:github/apps/*#write`\n\nReplace `<workspace_id>` with the authenticated workspace ID.\n",
"inputSchema": {
"type": "object"
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description74/100
Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits and metadata across all associated keys.
Perfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting across different services.
**Important**
Requires `unkey:v1:<workspaceId>:projects/<projectId>/identities/*#write` for the workspace's default project.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
externalId
Creates an identity using your system's unique identifier for a user, organization, or entity.
Must be stable and unique across your workspace - duplicate externalIds return CONFLICT errors.
This identifier links Unkey identities to your authentication system, database records, or tenant structure.
Avoid changing externalIds after creation as this breaks the link between your systems.
Use consistent identifier patterns across your application for easier management and debugging.
Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.
Essential for implementing proper multi-tenant isolation and user-specific rate limiting.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
meta
Stores arbitrary JSON metadata returned during key verification for contextual information.
Eliminates additional database lookups during verification, improving performance for stateless services.
Avoid storing sensitive data here as it's returned in verification responses.
Large metadata objects increase verification latency and should stay under 10KB total size.
Use this for subscription details, feature flags, user preferences, and organization information.
Metadata is returned as-is whenever keys associated with this identity are verified.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
ratelimits › items › autoApply
Whether this ratelimit should be automatically applied when verifying a key.
Clear enough to supply this argument.
ratelimits › items › duration
The duration for each ratelimit window in milliseconds.
This controls how long the rate limit counter accumulates before resetting. Common values include:
- 1000 (1 second): For strict per-second limits on high-frequency operations
- 60000 (1 minute): For moderate API usage control
- 3600000 (1 hour): For less frequent but costly operations
- 86400000 (24 hours): For daily quotas
Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
ratelimits › items › limit
The maximum number of operations allowed within the specified time window.
When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:
- Your infrastructure capacity and scaling limitations
- Fair usage expectations for your service
- Different tier levels for various user types
- The relative cost of the operations being limited
Higher values allow more frequent access but may impact service performance.
Clear enough to supply this argument.
ratelimits › items › name
The name of this rate limit. This name is used to identify which limit to check during key verification.
Best practices for limit names:
- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'
- Be consistent with naming conventions across your application
- Create separate limits for different resource types or operation costs
- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')
You will reference this exact name when verifying keys to check against this specific limit.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_identities_create_identity",
"title": "Create Identity",
"description": "Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits and metadata across all associated keys.\n\nPerfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting across different services.\n\n**Important**\nRequires `unkey:v1:<workspaceId>:projects/<projectId>/identities/*#write` for the workspace's default project.\n",
"inputSchema": {
"type": "object",
"required": [
"externalId"
],
"properties": {
"meta": {
"type": "object",
"description": "Stores arbitrary JSON metadata returned during key verification for contextual information.\nEliminates additional database lookups during verification, improving performance for stateless services.\nAvoid storing sensitive data here as it's returned in verification responses.\n\nLarge metadata objects increase verification latency and should stay under 10KB total size.\nUse this for subscription details, feature flags, user preferences, and organization information.\nMetadata is returned as-is whenever keys associated with this identity are verified.\n",
"maxProperties": 100,
"additionalProperties": true
},
"externalId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_.-]+$",
"maxLength": 255,
"minLength": 1,
"description": "Creates an identity using your system's unique identifier for a user, organization, or entity.\nMust be stable and unique across your workspace - duplicate externalIds return CONFLICT errors.\nThis identifier links Unkey identities to your authentication system, database records, or tenant structure.\n\nAvoid changing externalIds after creation as this breaks the link between your systems.\nUse consistent identifier patterns across your application for easier management and debugging.\nAccepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.\nEssential for implementing proper multi-tenant isolation and user-specific rate limiting.\n"
},
"ratelimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"limit",
"duration",
"autoApply"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 3,
"description": "The name of this rate limit. This name is used to identify which limit to check during key verification.\n\nBest practices for limit names:\n- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'\n- Be consistent with naming conventions across your application\n- Create separate limits for different resource types or operation costs\n- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')\n\nYou will reference this exact name when verifying keys to check against this specific limit."
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "The maximum number of operations allowed within the specified time window.\n\nWhen this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:\n- Your infrastructure capacity and scaling limitations\n- Fair usage expectations for your service\n- Different tier levels for various user types\n- The relative cost of the operations being limited\n\nHigher values allow more frequent access but may impact service performance."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1000,
"description": "The duration for each ratelimit window in milliseconds.\n\nThis controls how long the rate limit counter accumulates before resetting. Common values include:\n- 1000 (1 second): For strict per-second limits on high-frequency operations\n- 60000 (1 minute): For moderate API usage control\n- 3600000 (1 hour): For less frequent but costly operations\n- 86400000 (24 hours): For daily quotas\n\nShorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion."
},
"autoApply": {
"type": "boolean",
"default": false,
"description": "Whether this ratelimit should be automatically applied when verifying a key."
}
}
},
"maxItems": 50,
"description": "Defines shared rate limits that apply to all keys belonging to this identity.\nPrevents abuse by users with multiple keys by enforcing consistent limits across their entire key portfolio.\nEssential for implementing fair usage policies and tiered access levels in multi-tenant applications.\n\nRate limit counters are shared across all keys with this identity, regardless of how many keys the user creates.\nDuring verification, specify which named limits to check for enforcement.\nIdentity rate limits supplement any key-specific rate limits that may also be configured.\n- Each named limit can have different thresholds and windows\n\nWhen verifying keys, you can specify which limits you want to use and all keys attached to this identity will share the limits, regardless of which specific key is used.\n"
}
}
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Permanently delete an identity. This operation cannot be undone.
Use this for data cleanup, compliance requirements, or when removing entities from your system.
> **Important**
> Requires `identity.*.delete_identity` permission
> Associated API keys remain functional but lose shared resources
> External ID becomes available for reuse immediately
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Input documentation gives an agent enough context to populate the arguments.
identity
The ID of the identity to delete. This can be either the externalId (from your own system that was used during identity creation) or the identityId (the internal ID returned by the identity service).
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_identities_delete_identity",
"title": "Delete Identity",
"description": "Permanently delete an identity. This operation cannot be undone.\n\nUse this for data cleanup, compliance requirements, or when removing entities from your system.\n\n> **Important**\n> Requires `identity.*.delete_identity` permission\n> Associated API keys remain functional but lose shared resources\n> External ID becomes available for reuse immediately\n",
"inputSchema": {
"type": "object",
"required": [
"identity"
],
"properties": {
"identity": {
"type": "string",
"minLength": 1,
"description": "The ID of the identity to delete. This can be either the externalId (from your own system that was used during identity creation) or the identityId (the internal ID returned by the identity service)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Retrieve an identity by external ID. Returns metadata, rate limits, and other associated data.
Use this to check if an identity exists, view configurations, or build management dashboards.
> **Important**
> Requires `identity.*.read_identity` permission
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Input documentation gives an agent enough context to populate the arguments.
identity
The ID of the identity to retrieve. This can be either the externalId (from your own system that was used during identity creation) or the identityId (the internal ID returned by the identity service).
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_identities_get_identity",
"title": "Get Identity",
"description": "Retrieve an identity by external ID. Returns metadata, rate limits, and other associated data.\n\nUse this to check if an identity exists, view configurations, or build management dashboards.\n\n> **Important**\n> Requires `identity.*.read_identity` permission\n",
"inputSchema": {
"type": "object",
"required": [
"identity"
],
"properties": {
"identity": {
"type": "string",
"minLength": 1,
"description": "The ID of the identity to retrieve. This can be either the externalId (from your own system that was used during identity creation) or the identityId (the internal ID returned by the identity service)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations.
Perfect for building management dashboards, auditing configurations, or browsing your identities.
> **Important**
> Requires `identity.*.read_identity` permission
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response. Use this to fetch subsequent pages of results when the response contains a cursor value.
Clear enough to supply this argument.
limit
The maximum number of identities to return in a single request. Use this to control response size and loading performance.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Free-form text to filter identities. Returns identities whose ID or external ID contains the search string. Matching is case-insensitive.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_identities_list_identities",
"title": "List Identities",
"description": "Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations.\n\nPerfect for building management dashboards, auditing configurations, or browsing your identities.\n\n> **Important**\n> Requires `identity.*.read_identity` permission\n",
"inputSchema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "The maximum number of identities to return in a single request. Use this to control response size and loading performance."
},
"cursor": {
"type": "string",
"description": "Pagination cursor from a previous response. Use this to fetch subsequent pages of results when the response contains a cursor value."
},
"search": {
"type": "string",
"maxLength": 256,
"description": "Free-form text to filter identities. Returns identities whose ID or external ID contains the search string. Matching is case-insensitive."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Update an identity's metadata and rate limits. Only specified fields are modified - others remain unchanged.
Perfect for subscription changes, plan upgrades, or updating user information. Changes take effect immediately.
> **Important**
> Requires `unkey:v1:{workspaceId}:projects/{projectId}/identities/{identityId}#write` permission for the identity
> Rate limit changes propagate within 30 seconds
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
identity
The ID of the identity to update. Accepts either the externalId (your system-generated identifier) or the identityId (internal identifier returned by the identity service).
Clear enough to supply this argument.
meta
Replaces all existing metadata with this new metadata object.
Omitting this field preserves existing metadata, while providing an empty object clears all metadata.
Avoid storing sensitive data here as it's returned in verification responses.
Large metadata objects increase verification latency and should stay under 10KB total size.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
ratelimits › items › autoApply
Whether this ratelimit should be automatically applied when verifying a key.
Clear enough to supply this argument.
ratelimits › items › duration
The duration for each ratelimit window in milliseconds.
This controls how long the rate limit counter accumulates before resetting. Common values include:
- 1000 (1 second): For strict per-second limits on high-frequency operations
- 60000 (1 minute): For moderate API usage control
- 3600000 (1 hour): For less frequent but costly operations
- 86400000 (24 hours): For daily quotas
Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
ratelimits › items › limit
The maximum number of operations allowed within the specified time window.
When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:
- Your infrastructure capacity and scaling limitations
- Fair usage expectations for your service
- Different tier levels for various user types
- The relative cost of the operations being limited
Higher values allow more frequent access but may impact service performance.
Clear enough to supply this argument.
ratelimits › items › name
The name of this rate limit. This name is used to identify which limit to check during key verification.
Best practices for limit names:
- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'
- Be consistent with naming conventions across your application
- Create separate limits for different resource types or operation costs
- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')
You will reference this exact name when verifying keys to check against this specific limit.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_identities_update_identity",
"title": "Update Identity",
"description": "Update an identity's metadata and rate limits. Only specified fields are modified - others remain unchanged.\n\nPerfect for subscription changes, plan upgrades, or updating user information. Changes take effect immediately.\n\n> **Important**\n> Requires `unkey:v1:{workspaceId}:projects/{projectId}/identities/{identityId}#write` permission for the identity\n> Rate limit changes propagate within 30 seconds\n",
"inputSchema": {
"type": "object",
"required": [
"identity"
],
"properties": {
"meta": {
"type": "object",
"description": "Replaces all existing metadata with this new metadata object.\nOmitting this field preserves existing metadata, while providing an empty object clears all metadata.\nAvoid storing sensitive data here as it's returned in verification responses.\nLarge metadata objects increase verification latency and should stay under 10KB total size.\n",
"maxProperties": 100,
"additionalProperties": true
},
"identity": {
"type": "string",
"minLength": 1,
"description": "The ID of the identity to update. Accepts either the externalId (your system-generated identifier) or the identityId (internal identifier returned by the identity service)."
},
"ratelimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"limit",
"duration",
"autoApply"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 3,
"description": "The name of this rate limit. This name is used to identify which limit to check during key verification.\n\nBest practices for limit names:\n- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'\n- Be consistent with naming conventions across your application\n- Create separate limits for different resource types or operation costs\n- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')\n\nYou will reference this exact name when verifying keys to check against this specific limit."
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "The maximum number of operations allowed within the specified time window.\n\nWhen this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:\n- Your infrastructure capacity and scaling limitations\n- Fair usage expectations for your service\n- Different tier levels for various user types\n- The relative cost of the operations being limited\n\nHigher values allow more frequent access but may impact service performance."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1000,
"description": "The duration for each ratelimit window in milliseconds.\n\nThis controls how long the rate limit counter accumulates before resetting. Common values include:\n- 1000 (1 second): For strict per-second limits on high-frequency operations\n- 60000 (1 minute): For moderate API usage control\n- 3600000 (1 hour): For less frequent but costly operations\n- 86400000 (24 hours): For daily quotas\n\nShorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion."
},
"autoApply": {
"type": "boolean",
"default": false,
"description": "Whether this ratelimit should be automatically applied when verifying a key."
}
}
},
"maxItems": 50,
"description": "Replaces all existing identity rate limits with this complete list of rate limits.\nOmitting this field preserves existing rate limits, while providing an empty array removes all rate limits.\nThese limits are shared across all keys belonging to this identity, preventing abuse through multiple keys.\nRate limit changes take effect immediately but may take up to 30 seconds to propagate across all regions.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Add permissions to a key without affecting existing permissions.
Use this for privilege upgrades, enabling new features, or plan changes that grant additional capabilities. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have `write` on `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>`.
To create missing permission slugs, it must also have `write` on `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*`.
Adding existing permissions does not require this additional grant.
**Side Effects**
Invalidates the key cache for immediate effect, and makes permissions available for verification within 30 seconds across all regions.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyId
Specifies which key receives the additional permissions using the database identifier returned from `keys.createKey`.
Do not confuse this with the actual API key string that users include in requests.
Clear enough to supply this argument.
permissions
Grants additional permissions to the key through direct assignment or automatic creation.
Duplicate permissions are ignored automatically, making this operation idempotent.
Adding permissions never removes existing permissions or role-based permissions.
To create missing permission slugs, your root key must also have `write` on `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*` in the key's project. Without this grant, the operation fails with a 403 error if your root key can read the key, or a 404 error otherwise.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_add_permissions",
"title": "Add key permissions",
"description": "Add permissions to a key without affecting existing permissions.\n\nUse this for privilege upgrades, enabling new features, or plan changes that grant additional capabilities. Permissions granted through roles remain unchanged.\n\n**Important**: Changes take effect immediately with up to 30-second edge propagation.\n\n**Required Permissions**\n\nYour root key must have `write` on `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>`.\n\nTo create missing permission slugs, it must also have `write` on `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*`.\nAdding existing permissions does not require this additional grant.\n\n**Side Effects**\n\nInvalidates the key cache for immediate effect, and makes permissions available for verification within 30 seconds across all regions.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId",
"permissions"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key receives the additional permissions using the database identifier returned from `keys.createKey`.\nDo not confuse this with the actual API key string that users include in requests.\n"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "Specify the permission by its slug."
},
"maxItems": 1000,
"minItems": 1,
"description": "Grants additional permissions to the key through direct assignment or automatic creation.\nDuplicate permissions are ignored automatically, making this operation idempotent.\n\nAdding permissions never removes existing permissions or role-based permissions.\n\nTo create missing permission slugs, your root key must also have `write` on `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*` in the key's project. Without this grant, the operation fails with a 403 error if your root key can read the key, or a 404 error otherwise.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Add roles to a key without affecting existing roles or permissions.
Use this for privilege upgrades, enabling new feature sets, or subscription changes that grant additional role-based capabilities. Direct permissions remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write` for the target key. Wildcard grants that cover this resource and action also work.
**Side Effects**
Invalidates the key cache for immediate effect, and makes role assignments available for verification within 30 seconds across all regions.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyId
Specifies which key receives the additional roles using the database identifier returned from `createKey`.
Do not confuse this with the actual API key string that users include in requests.
Added roles supplement existing roles and permissions without replacing them.
Role assignments take effect immediately but may take up to 30 seconds to propagate across all regions.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
roles
Assigns additional roles to the key through direct assignment to existing workspace roles.
Operations are idempotent - adding existing roles has no effect and causes no errors.
All roles must already exist in the workspace - roles cannot be created automatically.
Invalid roles cause the entire operation to fail atomically, ensuring consistent state.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_add_roles",
"title": "Add key roles",
"description": "Add roles to a key without affecting existing roles or permissions.\n\nUse this for privilege upgrades, enabling new feature sets, or subscription changes that grant additional role-based capabilities. Direct permissions remain unchanged.\n\n**Important**: Changes take effect immediately with up to 30-second edge propagation.\n\n**Required Permissions**\n\nYour root key must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write` for the target key. Wildcard grants that cover this resource and action also work.\n\n**Side Effects**\n\nInvalidates the key cache for immediate effect, and makes role assignments available for verification within 30 seconds across all regions.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId",
"roles"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key receives the additional roles using the database identifier returned from `createKey`.\nDo not confuse this with the actual API key string that users include in requests.\nAdded roles supplement existing roles and permissions without replacing them.\nRole assignments take effect immediately but may take up to 30 seconds to propagate across all regions.\n"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "Specify the role by name."
},
"maxItems": 100,
"minItems": 1,
"description": "Assigns additional roles to the key through direct assignment to existing workspace roles.\nOperations are idempotent - adding existing roles has no effect and causes no errors.\n\nAll roles must already exist in the workspace - roles cannot be created automatically.\nInvalid roles cause the entire operation to fail atomically, ensuring consistent state.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
Create a new API key for user authentication and authorization.
Use this endpoint when users sign up, upgrade subscription tiers, or need additional keys. Keys are cryptographically secure and unique to the specified API namespace.
**Important**: Store the returned key securely. Unless you create a recoverable key, the plaintext cannot be retrieved later. Recoverable keys require key encryption and permission to decrypt them.
**Common use cases:**
- Generate keys for new user registrations
- Create additional keys for different applications
- Issue keys with specific permissions or limits
**Required Permissions**
Your credential needs `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write` for the target keyspace. Use the keyspace's project ID, not the API's project ID if they differ. A grant with wildcard project or keyspace segments can cover multiple keyspaces in the authorized workspace.
Recoverable keys use the same write permission. They also require the keyspace to support key encryption.
Without write permission, this endpoint returns 404 to hide whether the API exists. If your credential can read the keyspace, it returns 403 and names the missing write permission instead.
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
apiId
The API namespace this key belongs to.
Keys from different APIs cannot access each other.
Clear enough to supply this argument.
byteLength
Controls the cryptographic strength of the generated key in bytes.
Higher values increase security but result in longer keys that may be more annoying to handle.
The default 16 bytes provides 2^128 possible combinations, sufficient for most applications.
Consider 32 bytes for highly sensitive APIs, but avoid values above 64 bytes unless specifically required.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
credits › refill › amount
Number of credits to add during each refill cycle.
Clear enough to supply this argument.
credits › refill › interval
How often credits are automatically refilled.
Explain the meaning of this value, not just its name.
credits › refill › refillDay
Day of the month for monthly refills (1-31).
Only required when interval is 'monthly'.
For days beyond the month's length, refill occurs on the last day of the month.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
credits › remaining
Number of credits remaining (null for unlimited).
Clear enough to supply this argument.
enabled
Controls whether the key is active immediately upon creation.
When set to `false`, the key exists but all verification attempts fail with `code=DISABLED`.
Useful for pre-creating keys that will be activated later or for keys requiring manual approval.
Most keys should be created with `enabled=true` for immediate use.
Clear enough to supply this argument.
expires
Sets when this key automatically expires as a Unix timestamp in milliseconds.
Verification fails with code=EXPIRED immediately after this time passes.
Omitting this field creates a permanent key that never expires.
Avoid setting timestamps in the past as they immediately invalidate the key.
Keys expire based on server time, not client time, which prevents timezone-related issues.
Essential for trial periods, temporary access, and security compliance requiring key rotation.
Clear enough to supply this argument.
externalId
Links this key to a user or entity in your system using your own identifier.
Returned during verification to identify the key owner without additional database lookups.
Essential for user-specific analytics, billing, and multi-tenant key management.
Use your primary user ID, organization ID, or tenant ID for best results.
Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.
Clear enough to supply this argument.
meta
Stores arbitrary JSON metadata returned during key verification for contextual information.
Eliminates additional database lookups during verification, improving performance for stateless services.
Avoid storing sensitive data here as it's returned in verification responses.
Large metadata objects increase verification latency and should stay under 10KB total size.
Clear enough to supply this argument.
name
Sets a human-readable identifier for internal organization and dashboard display.
Never exposed to end users, only visible in management interfaces and API responses.
Avoid generic names like "API Key" when managing multiple keys for the same user or service.
Clear enough to supply this argument.
permissions
Grants specific permissions directly to this key without requiring role membership.
Each entry is a permission ID or slug. IDs are matched first, then slugs.
An entry that matches no permission creates a permission with that slug.
Wildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.
Direct permissions supplement any permissions inherited from assigned roles.
Clear enough to supply this argument.
prefix
Adds a visual identifier to the beginning of the generated key for easier recognition in logs and dashboards.
The prefix becomes part of the actual key string (e.g., `prod_xxxxxxxxx`).
Avoid using sensitive information in prefixes as they may appear in logs and error messages.
Clear enough to supply this argument.
ratelimits › items › autoApply
Whether this ratelimit should be automatically applied when verifying a key.
Clear enough to supply this argument.
ratelimits › items › duration
The duration for each ratelimit window in milliseconds.
This controls how long the rate limit counter accumulates before resetting. Common values include:
- 1000 (1 second): For strict per-second limits on high-frequency operations
- 60000 (1 minute): For moderate API usage control
- 3600000 (1 hour): For less frequent but costly operations
- 86400000 (24 hours): For daily quotas
Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion.
Clear enough to supply this argument.
ratelimits › items › limit
The maximum number of operations allowed within the specified time window.
When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:
- Your infrastructure capacity and scaling limitations
- Fair usage expectations for your service
- Different tier levels for various user types
- The relative cost of the operations being limited
Higher values allow more frequent access but may impact service performance.
Clear enough to supply this argument.
ratelimits › items › name
The name of this rate limit. This name is used to identify which limit to check during key verification.
Best practices for limit names:
- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'
- Be consistent with naming conventions across your application
- Create separate limits for different resource types or operation costs
- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')
You will reference this exact name when verifying keys to check against this specific limit.
Clear enough to supply this argument.
recoverable
Controls whether the plaintext key is stored in an encrypted vault for later retrieval.
When true, allows recovering the actual key value using keys.getKey with decrypt=true.
When false, the key value cannot be retrieved after creation for maximum security.
Only enable for development keys or when key recovery is absolutely necessary.
Clear enough to supply this argument.
roles
Assigns existing roles to this key for permission management through role-based access control.
Roles must already exist in your workspace before assignment.
During verification, all permissions from assigned roles are checked against requested permissions.
Roles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_create_key",
"title": "Create API key",
"description": "Create a new API key for user authentication and authorization.\n\nUse this endpoint when users sign up, upgrade subscription tiers, or need additional keys. Keys are cryptographically secure and unique to the specified API namespace.\n\n**Important**: Store the returned key securely. Unless you create a recoverable key, the plaintext cannot be retrieved later. Recoverable keys require key encryption and permission to decrypt them.\n\n**Common use cases:**\n- Generate keys for new user registrations\n- Create additional keys for different applications\n- Issue keys with specific permissions or limits\n\n**Required Permissions**\n\nYour credential needs `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write` for the target keyspace. Use the keyspace's project ID, not the API's project ID if they differ. A grant with wildcard project or keyspace segments can cover multiple keyspaces in the authorized workspace.\n\nRecoverable keys use the same write permission. They also require the keyspace to support key encryption.\n\nWithout write permission, this endpoint returns 404 to hide whether the API exists. If your credential can read the keyspace, it returns 403 and names the missing write permission instead.\n",
"inputSchema": {
"type": "object",
"required": [
"apiId"
],
"properties": {
"meta": {
"type": "object",
"description": "Stores arbitrary JSON metadata returned during key verification for contextual information.\nEliminates additional database lookups during verification, improving performance for stateless services.\nAvoid storing sensitive data here as it's returned in verification responses.\nLarge metadata objects increase verification latency and should stay under 10KB total size.\n",
"maxProperties": 100,
"additionalProperties": true
},
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Sets a human-readable identifier for internal organization and dashboard display.\nNever exposed to end users, only visible in management interfaces and API responses.\nAvoid generic names like \"API Key\" when managing multiple keys for the same user or service.\n"
},
"apiId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "The API namespace this key belongs to.\nKeys from different APIs cannot access each other.\n"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128,
"minLength": 1
},
"maxItems": 100,
"description": "Assigns existing roles to this key for permission management through role-based access control.\nRoles must already exist in your workspace before assignment.\nDuring verification, all permissions from assigned roles are checked against requested permissions.\nRoles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.\n"
},
"prefix": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 16,
"minLength": 1,
"description": "Adds a visual identifier to the beginning of the generated key for easier recognition in logs and dashboards.\nThe prefix becomes part of the actual key string (e.g., `prod_xxxxxxxxx`).\nAvoid using sensitive information in prefixes as they may appear in logs and error messages.\n"
},
"credits": {
"type": "object",
"required": [
"remaining"
],
"properties": {
"refill": {
"type": "object",
"required": [
"interval",
"amount"
],
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 1,
"description": "Number of credits to add during each refill cycle."
},
"interval": {
"enum": [
"daily",
"monthly"
],
"type": "string",
"description": "How often credits are automatically refilled."
},
"refillDay": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day of the month for monthly refills (1-31).\nOnly required when interval is 'monthly'.\nFor days beyond the month's length, refill occurs on the last day of the month.\n"
}
},
"description": "Configuration for automatic credit refill behavior.",
"additionalProperties": false
},
"remaining": {
"type": [
"integer",
"null"
],
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 0,
"description": "Number of credits remaining (null for unlimited)."
}
},
"description": "Controls usage-based limits through credit consumption with optional automatic refills.\nUnlike rate limits which control frequency, credits control total usage with global consistency.\nEssential for implementing usage-based pricing, subscription tiers, and hard usage quotas.\nOmitting this field creates unlimited usage, while setting null is not allowed during creation.\n",
"additionalProperties": false
},
"enabled": {
"type": "boolean",
"default": true,
"description": "Controls whether the key is active immediately upon creation.\nWhen set to `false`, the key exists but all verification attempts fail with `code=DISABLED`.\nUseful for pre-creating keys that will be activated later or for keys requiring manual approval.\nMost keys should be created with `enabled=true` for immediate use.\n"
},
"expires": {
"type": "integer",
"format": "int64",
"maximum": 4102444800000,
"minimum": 0,
"description": "Sets when this key automatically expires as a Unix timestamp in milliseconds.\nVerification fails with code=EXPIRED immediately after this time passes.\nOmitting this field creates a permanent key that never expires.\n\nAvoid setting timestamps in the past as they immediately invalidate the key.\nKeys expire based on server time, not client time, which prevents timezone-related issues.\nEssential for trial periods, temporary access, and security compliance requiring key rotation.\n"
},
"byteLength": {
"type": "integer",
"default": 16,
"maximum": 255,
"minimum": 16,
"description": "Controls the cryptographic strength of the generated key in bytes.\nHigher values increase security but result in longer keys that may be more annoying to handle.\nThe default 16 bytes provides 2^128 possible combinations, sufficient for most applications.\nConsider 32 bytes for highly sensitive APIs, but avoid values above 64 bytes unless specifically required.\n"
},
"externalId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_.-]+$",
"maxLength": 255,
"minLength": 1,
"description": "Links this key to a user or entity in your system using your own identifier.\nReturned during verification to identify the key owner without additional database lookups.\nEssential for user-specific analytics, billing, and multi-tenant key management.\nUse your primary user ID, organization ID, or tenant ID for best results.\nAccepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.\n"
},
"ratelimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"limit",
"duration",
"autoApply"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 3,
"description": "The name of this rate limit. This name is used to identify which limit to check during key verification.\n\nBest practices for limit names:\n- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'\n- Be consistent with naming conventions across your application\n- Create separate limits for different resource types or operation costs\n- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')\n\nYou will reference this exact name when verifying keys to check against this specific limit."
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "The maximum number of operations allowed within the specified time window.\n\nWhen this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:\n- Your infrastructure capacity and scaling limitations\n- Fair usage expectations for your service\n- Different tier levels for various user types\n- The relative cost of the operations being limited\n\nHigher values allow more frequent access but may impact service performance."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1000,
"description": "The duration for each ratelimit window in milliseconds.\n\nThis controls how long the rate limit counter accumulates before resetting. Common values include:\n- 1000 (1 second): For strict per-second limits on high-frequency operations\n- 60000 (1 minute): For moderate API usage control\n- 3600000 (1 hour): For less frequent but costly operations\n- 86400000 (24 hours): For daily quotas\n\nShorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion."
},
"autoApply": {
"type": "boolean",
"default": false,
"description": "Whether this ratelimit should be automatically applied when verifying a key."
}
}
},
"maxItems": 50,
"description": "Defines time-based rate limits that protect against abuse by controlling request frequency.\nUnlike credits which track total usage, rate limits reset automatically after each window expires.\nMultiple rate limits can control different operation types with separate thresholds and windows.\nEssential for preventing API abuse while maintaining good performance for legitimate usage.\n"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1
},
"maxItems": 1000,
"description": "Grants specific permissions directly to this key without requiring role membership.\nEach entry is a permission ID or slug. IDs are matched first, then slugs.\nAn entry that matches no permission creates a permission with that slug.\nWildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.\nDirect permissions supplement any permissions inherited from assigned roles.\n"
},
"recoverable": {
"type": "boolean",
"default": false,
"description": "Controls whether the plaintext key is stored in an encrypted vault for later retrieval.\nWhen true, allows recovering the actual key value using keys.getKey with decrypt=true.\nWhen false, the key value cannot be retrieved after creation for maximum security.\nOnly enable for development keys or when key recovery is absolutely necessary.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Delete API keys from user accounts or for cleanup purposes.
Use this for user-requested key revocation, account deletion workflows, or cleaning up unused keys. Keys are immediately invalidated. Two modes: soft delete (default, preserves audit records) and permanent delete.
**Important**: For temporary access control, use `updateKey` with `enabled: false` instead of deletion.
**Required Permissions**
Your credential must have one of the following permissions:
- `unkey:v1:<workspace_id>:projects/*/keyspaces/*/keys/*#delete` (to delete keys in any project)
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/*/keys/*#delete` (to delete keys in a specific project)
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#delete` (to delete keys in a specific keyspace)
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#delete` (to delete a specific key)
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
keyId
Specifies which key to delete using the database identifier returned from `createKey`.
Do not confuse this with the actual API key string that users include in requests.
Deletion immediately invalidates the key, causing all future verification attempts to fail with `code=NOT_FOUND`.
Key deletion triggers cache invalidation across all regions but may take up to 30 seconds to fully propagate.
Clear enough to supply this argument.
permanent
Controls deletion behavior between recoverable soft-deletion and irreversible permanent erasure.
Soft deletion (default) preserves key data for potential recovery through direct database operations.
Permanent deletion completely removes all traces including hash values and metadata with no recovery option.
Use permanent deletion only for regulatory compliance (GDPR), resolving hash collisions, or when reusing identical key strings.
Permanent deletion cannot be undone and may affect analytics data that references the deleted key.
Most applications should use soft deletion to maintain audit trails and prevent accidental data loss.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_delete_key",
"title": "Delete API keys",
"description": "Delete API keys from user accounts or for cleanup purposes.\n\nUse this for user-requested key revocation, account deletion workflows, or cleaning up unused keys. Keys are immediately invalidated. Two modes: soft delete (default, preserves audit records) and permanent delete.\n\n**Important**: For temporary access control, use `updateKey` with `enabled: false` instead of deletion.\n\n**Required Permissions**\n\nYour credential must have one of the following permissions:\n- `unkey:v1:<workspace_id>:projects/*/keyspaces/*/keys/*#delete` (to delete keys in any project)\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/*/keys/*#delete` (to delete keys in a specific project)\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#delete` (to delete keys in a specific keyspace)\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#delete` (to delete a specific key)\n",
"inputSchema": {
"type": "object",
"required": [
"keyId"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key to delete using the database identifier returned from `createKey`.\nDo not confuse this with the actual API key string that users include in requests.\nDeletion immediately invalidates the key, causing all future verification attempts to fail with `code=NOT_FOUND`.\nKey deletion triggers cache invalidation across all regions but may take up to 30 seconds to fully propagate.\n"
},
"permanent": {
"type": "boolean",
"default": false,
"description": "Controls deletion behavior between recoverable soft-deletion and irreversible permanent erasure.\nSoft deletion (default) preserves key data for potential recovery through direct database operations.\nPermanent deletion completely removes all traces including hash values and metadata with no recovery option.\n\nUse permanent deletion only for regulatory compliance (GDPR), resolving hash collisions, or when reusing identical key strings.\nPermanent deletion cannot be undone and may affect analytics data that references the deleted key.\nMost applications should use soft deletion to maintain audit trails and prevent accidental data loss.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Retrieve detailed key information for dashboard interfaces and administrative purposes.
Use this to build key management dashboards showing users their key details, status, permissions, and usage data. You can identify keys by `keyId` or the actual key string.
**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.
**Required Permissions**
Your credential 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)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)
Additional permission required for decrypt functionality:
- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#decrypt_key`
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Input documentation gives an agent enough context to populate the arguments.
decrypt
Controls whether to include the plaintext key value in the response for recovery purposes.
Only works for keys created with `recoverable=true` and requires the `decrypt_key` permission.
Returned keys must be handled securely, never logged, cached, or stored insecurely.
Use only for legitimate recovery scenarios like user password resets or emergency access.
Most applications should keep this false to maintain security best practices and avoid accidental key exposure.
Decryption requests are audited and may trigger security alerts in enterprise environments.
Clear enough to supply this argument.
keyId
Specifies which key to retrieve using the database identifier returned from `keys.createKey`.
Do not confuse this with the actual API key string that users include in requests.
Key data includes metadata, permissions, usage statistics, and configuration but never the plaintext key value unless `decrypt=true`.
Find this ID in creation responses, key listings, dashboard, or verification responses.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_get_key",
"title": "Get API key",
"description": "Retrieve detailed key information for dashboard interfaces and administrative purposes.\n\nUse this to build key management dashboards showing users their key details, status, permissions, and usage data. You can identify keys by `keyId` or the actual key string.\n\n**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.\n\n**Required Permissions**\n\nYour credential must have one of the following permissions for basic key information:\n- `api.*.read_key` (to read keys from any API)\n- `api.<api_id>.read_key` (to read keys from a specific API)\n- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)\n- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)\n- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)\n\nAdditional permission required for decrypt functionality:\n- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`\n- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#decrypt_key`\n- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#decrypt_key`\n- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#decrypt_key`\n",
"inputSchema": {
"type": "object",
"required": [
"keyId"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key to retrieve using the database identifier returned from `keys.createKey`.\nDo not confuse this with the actual API key string that users include in requests.\nKey data includes metadata, permissions, usage statistics, and configuration but never the plaintext key value unless `decrypt=true`.\nFind this ID in creation responses, key listings, dashboard, or verification responses.\n"
},
"decrypt": {
"type": "boolean",
"default": false,
"description": "Controls whether to include the plaintext key value in the response for recovery purposes.\nOnly works for keys created with `recoverable=true` and requires the `decrypt_key` permission.\nReturned keys must be handled securely, never logged, cached, or stored insecurely.\n\nUse only for legitimate recovery scenarios like user password resets or emergency access.\nMost applications should keep this false to maintain security best practices and avoid accidental key exposure.\nDecryption requests are audited and may trigger security alerts in enterprise environments.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description61/100
Returns HTTP 200 even on partial success; hashes that could not be migrated are listed under `data.failed`.
**Required Permissions**
Your root key must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write` for the target keyspace in its project and workspace.
Describe the concrete operation and its scope instead of restating the tool name.
Inputs82/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
apiId
The ID of the API that the keys should be inserted into
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keys › items › credits › refill › amount
Number of credits to add during each refill cycle.
Clear enough to supply this argument.
keys › items › credits › refill › interval
How often credits are automatically refilled.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keys › items › credits › refill › refillDay
Day of the month for monthly refills (1-31).
Only required when interval is 'monthly'.
For days beyond the month's length, refill occurs on the last day of the month.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keys › items › credits › remaining
Number of credits remaining (null for unlimited).
Clear enough to supply this argument.
keys › items › enabled
Controls whether the key is active immediately upon creation.
When set to `false`, the key exists but all verification attempts fail with `code=DISABLED`.
Useful for pre-creating keys that will be activated later or for keys requiring manual approval.
Most keys should be created with `enabled=true` for immediate use.
Clear enough to supply this argument.
keys › items › expires
Sets when this key automatically expires as a Unix timestamp in milliseconds.
Verification fails with code=EXPIRED immediately after this time passes.
Omitting this field creates a permanent key that never expires.
Avoid setting timestamps in the past as they immediately invalidate the key.
Keys expire based on server time, not client time, which prevents timezone-related issues.
Essential for trial periods, temporary access, and security compliance requiring key rotation.
Clear enough to supply this argument.
keys › items › externalId
Links this key to a user or entity in your system using your own identifier.
Returned during verification to identify the key owner without additional database lookups.
Essential for user-specific analytics, billing, and multi-tenant key management.
Use your primary user ID, organization ID, or tenant ID for best results.
Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.
Clear enough to supply this argument.
keys › items › hash
The current hash of the key on your side
Explain the meaning of this value, not just its name.
keys › items › meta
Stores arbitrary JSON metadata returned during key verification for contextual information.
Eliminates additional database lookups during verification, improving performance for stateless services.
Avoid storing sensitive data here as it's returned in verification responses.
Large metadata objects increase verification latency and should stay under 10KB total size.
Clear enough to supply this argument.
keys › items › name
Sets a human-readable identifier for internal organization and dashboard display.
Never exposed to end users, only visible in management interfaces and API responses.
Avoid generic names like "API Key" when managing multiple keys for the same user or service.
Clear enough to supply this argument.
keys › items › permissions
Grants specific permissions directly to this key without requiring role membership.
Wildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.
Direct permissions supplement any permissions inherited from assigned roles.
Clear enough to supply this argument.
keys › items › ratelimits › items › autoApply
Whether this ratelimit should be automatically applied when verifying a key.
Clear enough to supply this argument.
keys › items › ratelimits › items › duration
The duration for each ratelimit window in milliseconds.
This controls how long the rate limit counter accumulates before resetting. Common values include:
- 1000 (1 second): For strict per-second limits on high-frequency operations
- 60000 (1 minute): For moderate API usage control
- 3600000 (1 hour): For less frequent but costly operations
- 86400000 (24 hours): For daily quotas
Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion.
Clear enough to supply this argument.
keys › items › ratelimits › items › limit
The maximum number of operations allowed within the specified time window.
When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:
- Your infrastructure capacity and scaling limitations
- Fair usage expectations for your service
- Different tier levels for various user types
- The relative cost of the operations being limited
Higher values allow more frequent access but may impact service performance.
Clear enough to supply this argument.
keys › items › ratelimits › items › name
The name of this rate limit. This name is used to identify which limit to check during key verification.
Best practices for limit names:
- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'
- Be consistent with naming conventions across your application
- Create separate limits for different resource types or operation costs
- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')
You will reference this exact name when verifying keys to check against this specific limit.
Clear enough to supply this argument.
keys › items › roles
Assigns existing roles to this key for permission management through role-based access control.
Roles must already exist in your workspace before assignment.
During verification, all permissions from assigned roles are checked against requested permissions.
Roles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.
Clear enough to supply this argument.
migrationId
Identifier of the configured migration provider/strategy to use (e.g., "your_company"). You will receive this from Unkey's support staff.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_migrate_keys",
"title": "Migrate API key(s)",
"description": "Returns HTTP 200 even on partial success; hashes that could not be migrated are listed under `data.failed`.\n\n**Required Permissions**\nYour root key must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write` for the target keyspace in its project and workspace.\n",
"inputSchema": {
"type": "object",
"required": [
"migrationId",
"apiId",
"keys"
],
"properties": {
"keys": {
"type": "array",
"items": {
"type": "object",
"required": [
"hash"
],
"properties": {
"hash": {
"type": "string",
"minLength": 3,
"description": "The current hash of the key on your side"
},
"meta": {
"type": "object",
"description": "Stores arbitrary JSON metadata returned during key verification for contextual information.\nEliminates additional database lookups during verification, improving performance for stateless services.\nAvoid storing sensitive data here as it's returned in verification responses.\nLarge metadata objects increase verification latency and should stay under 10KB total size.\n",
"maxProperties": 100,
"additionalProperties": true
},
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Sets a human-readable identifier for internal organization and dashboard display.\nNever exposed to end users, only visible in management interfaces and API responses.\nAvoid generic names like \"API Key\" when managing multiple keys for the same user or service.\n"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128,
"minLength": 1
},
"maxItems": 100,
"description": "Assigns existing roles to this key for permission management through role-based access control.\nRoles must already exist in your workspace before assignment.\nDuring verification, all permissions from assigned roles are checked against requested permissions.\nRoles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.\n"
},
"credits": {
"type": "object",
"required": [
"remaining"
],
"properties": {
"refill": {
"type": "object",
"required": [
"interval",
"amount"
],
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 1,
"description": "Number of credits to add during each refill cycle."
},
"interval": {
"enum": [
"daily",
"monthly"
],
"type": "string",
"description": "How often credits are automatically refilled."
},
"refillDay": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day of the month for monthly refills (1-31).\nOnly required when interval is 'monthly'.\nFor days beyond the month's length, refill occurs on the last day of the month.\n"
}
},
"description": "Configuration for automatic credit refill behavior.",
"additionalProperties": false
},
"remaining": {
"type": [
"integer",
"null"
],
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 0,
"description": "Number of credits remaining (null for unlimited)."
}
},
"description": "Controls usage-based limits through credit consumption with optional automatic refills.\nUnlike rate limits which control frequency, credits control total usage with global consistency.\nEssential for implementing usage-based pricing, subscription tiers, and hard usage quotas.\nOmitting this field creates unlimited usage, while setting null is not allowed during creation.\n",
"additionalProperties": false
},
"enabled": {
"type": "boolean",
"default": true,
"description": "Controls whether the key is active immediately upon creation.\nWhen set to `false`, the key exists but all verification attempts fail with `code=DISABLED`.\nUseful for pre-creating keys that will be activated later or for keys requiring manual approval.\nMost keys should be created with `enabled=true` for immediate use.\n"
},
"expires": {
"type": "integer",
"format": "int64",
"maximum": 4102444800000,
"minimum": 0,
"description": "Sets when this key automatically expires as a Unix timestamp in milliseconds.\nVerification fails with code=EXPIRED immediately after this time passes.\nOmitting this field creates a permanent key that never expires.\n\nAvoid setting timestamps in the past as they immediately invalidate the key.\nKeys expire based on server time, not client time, which prevents timezone-related issues.\nEssential for trial periods, temporary access, and security compliance requiring key rotation.\n"
},
"externalId": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Links this key to a user or entity in your system using your own identifier.\nReturned during verification to identify the key owner without additional database lookups.\nEssential for user-specific analytics, billing, and multi-tenant key management.\nUse your primary user ID, organization ID, or tenant ID for best results.\nAccepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.\n"
},
"ratelimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"limit",
"duration",
"autoApply"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 3,
"description": "The name of this rate limit. This name is used to identify which limit to check during key verification.\n\nBest practices for limit names:\n- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'\n- Be consistent with naming conventions across your application\n- Create separate limits for different resource types or operation costs\n- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')\n\nYou will reference this exact name when verifying keys to check against this specific limit."
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "The maximum number of operations allowed within the specified time window.\n\nWhen this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:\n- Your infrastructure capacity and scaling limitations\n- Fair usage expectations for your service\n- Different tier levels for various user types\n- The relative cost of the operations being limited\n\nHigher values allow more frequent access but may impact service performance."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1000,
"description": "The duration for each ratelimit window in milliseconds.\n\nThis controls how long the rate limit counter accumulates before resetting. Common values include:\n- 1000 (1 second): For strict per-second limits on high-frequency operations\n- 60000 (1 minute): For moderate API usage control\n- 3600000 (1 hour): For less frequent but costly operations\n- 86400000 (24 hours): For daily quotas\n\nShorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion."
},
"autoApply": {
"type": "boolean",
"default": false,
"description": "Whether this ratelimit should be automatically applied when verifying a key."
}
}
},
"maxItems": 50,
"description": "Defines time-based rate limits that protect against abuse by controlling request frequency.\nUnlike credits which track total usage, rate limits reset automatically after each window expires.\nMultiple rate limits can control different operation types with separate thresholds and windows.\nEssential for preventing API abuse while maintaining good performance for legitimate usage.\n"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1
},
"maxItems": 1000,
"description": "Grants specific permissions directly to this key without requiring role membership.\nWildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.\nDirect permissions supplement any permissions inherited from assigned roles.\n"
}
},
"additionalProperties": false
},
"minItems": 1
},
"apiId": {
"type": "string",
"maxLength": 255,
"minLength": 3,
"description": "The ID of the API that the keys should be inserted into"
},
"migrationId": {
"type": "string",
"maxLength": 255,
"minLength": 3,
"description": "Identifier of the configured migration provider/strategy to use (e.g., \"your_company\"). You will receive this from Unkey's support staff."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Remove permissions from a key without affecting existing roles or other permissions.
Use this for privilege downgrades, removing temporary access, or plan changes that revoke specific capabilities. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write` for the target key. Wildcard grants that include the target key also authorize this operation.
**Side Effects**
Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.
The description explains the capability, when to use it, and what to expect.
Inputs50/100
Resolve the mismatch between this description and its schema constraints.
keyId
Specifies which key to remove permissions from using the database identifier returned from `keys.createKey`.
Do not confuse this with the actual API key string that users include in requests.
Clear enough to supply this argument.
permissions
Removes direct permissions from the key without affecting role-based permissions.
You can either use a permission slug, or the permission ID.
After removal, verification checks for these permissions will fail unless granted through roles.
Resolve the mismatch between this description and its schema constraints.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_remove_permissions",
"title": "Remove key permissions",
"description": "Remove permissions from a key without affecting existing roles or other permissions.\n\nUse this for privilege downgrades, removing temporary access, or plan changes that revoke specific capabilities. Permissions granted through roles remain unchanged.\n\n**Important**: Changes take effect immediately with up to 30-second edge propagation.\n\n**Required Permissions**\n\nYour root key must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write` for the target key. Wildcard grants that include the target key also authorize this operation.\n\n**Side Effects**\n\nInvalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId",
"permissions"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key to remove permissions from using the database identifier returned from `keys.createKey`.\nDo not confuse this with the actual API key string that users include in requests.\n"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "Specify the permission by its slug."
},
"maxItems": 1000,
"minItems": 1,
"description": "Removes direct permissions from the key without affecting role-based permissions.\n\nYou can either use a permission slug, or the permission ID.\n\nAfter removal, verification checks for these permissions will fail unless granted through roles.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Remove roles from a key without affecting direct permissions or other roles.
Use this for privilege downgrades, removing temporary access, or subscription changes that revoke specific role-based capabilities. Direct permissions remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have the following permission for the target key:
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write`
**Side Effects**
Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyId
Specifies which key loses the roles using the database identifier returned from createKey.
Do not confuse this with the actual API key string that users include in requests.
Removing roles only affects direct assignments, not permissions inherited from other sources.
Role changes take effect immediately but may take up to 30 seconds to propagate across all regions.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
roles
Removes direct role assignments from the key without affecting other role sources or permissions.
Operations are idempotent - removing non-assigned roles has no effect and causes no errors.
After removal, the key loses access to permissions that were only granted through these roles.
Invalid role references cause the entire operation to fail atomically, ensuring consistent state.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_remove_roles",
"title": "Remove key roles",
"description": "Remove roles from a key without affecting direct permissions or other roles.\n\nUse this for privilege downgrades, removing temporary access, or subscription changes that revoke specific role-based capabilities. Direct permissions remain unchanged.\n\n**Important**: Changes take effect immediately with up to 30-second edge propagation.\n\n**Required Permissions**\n\nYour root key must have the following permission for the target key:\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write`\n\n**Side Effects**\n\nInvalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId",
"roles"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key loses the roles using the database identifier returned from createKey.\nDo not confuse this with the actual API key string that users include in requests.\nRemoving roles only affects direct assignments, not permissions inherited from other sources.\nRole changes take effect immediately but may take up to 30 seconds to propagate across all regions.\n"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "Specify the role by name."
},
"maxItems": 100,
"minItems": 1,
"description": "Removes direct role assignments from the key without affecting other role sources or permissions.\nOperations are idempotent - removing non-assigned roles has no effect and causes no errors.\n\nAfter removal, the key loses access to permissions that were only granted through these roles.\nInvalid role references cause the entire operation to fail atomically, ensuring consistent state.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Generate a new API key while preserving the configuration from an existing key.
This operation creates a fresh key with a new token while maintaining all settings from the original key:
- Permissions and roles
- Custom metadata
- Rate limit configurations
- Identity associations
- Remaining credits
- Recovery settings
**Key Generation:**
- The system attempts to extract the prefix from the original key
- If prefix extraction fails, the default API prefix is used
- Key length follows the API's default byte configuration (or 16 bytes if not specified)
**Original Key Handling:**
- The original key will be revoked after the duration specified in `expiration`
- Set `expiration` to 0 to revoke immediately
- This allows for graceful key rotation with an overlap period
Common use cases include:
- Rotating keys for security compliance
- Issuing replacement keys for compromised credentials
- Creating backup keys with identical permissions
**Important:** Analytics and usage metrics are tracked at both the key level AND identity level. If the original key has an identity, the new key will inherit it, allowing you to track usage across both individual keys and the overall identity.
**Required Permissions**
Your credential must grant `write` on the original key:
`unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write`.
A matching wildcard grant also satisfies this requirement. The same permission applies to recoverable keys.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
expiration
Duration in milliseconds until the ORIGINAL key is revoked, starting from now.
This parameter controls the overlap period for key rotation:
- Set to `0` to revoke the original key immediately
- Positive values keep the original key active for the specified duration
- Set to `null` to keep the original key active; it keeps its current expiration, if any
- Allows graceful migration by giving users time to update their credentials
Common overlap periods:
- Immediate revocation: 0
- 1 hour grace period: 3600000
- 24 hours grace period: 86400000
- 7 days grace period: 604800000
- 30 days grace period: 2592000000
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyId
The database identifier of the key to reroll.
This is the unique ID returned when creating or listing keys, NOT the actual API key token.
You can find this ID in:
- The response from `keys.createKey`
- Key verification responses
- The Unkey dashboard
- API key listing endpoints
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_reroll_key",
"title": "Reroll Key",
"description": "Generate a new API key while preserving the configuration from an existing key.\n\nThis operation creates a fresh key with a new token while maintaining all settings from the original key:\n- Permissions and roles\n- Custom metadata\n- Rate limit configurations\n- Identity associations\n- Remaining credits\n- Recovery settings\n\n**Key Generation:**\n- The system attempts to extract the prefix from the original key\n- If prefix extraction fails, the default API prefix is used\n- Key length follows the API's default byte configuration (or 16 bytes if not specified)\n\n**Original Key Handling:**\n- The original key will be revoked after the duration specified in `expiration`\n- Set `expiration` to 0 to revoke immediately\n- This allows for graceful key rotation with an overlap period\n\nCommon use cases include:\n- Rotating keys for security compliance\n- Issuing replacement keys for compromised credentials\n- Creating backup keys with identical permissions\n\n**Important:** Analytics and usage metrics are tracked at both the key level AND identity level. If the original key has an identity, the new key will inherit it, allowing you to track usage across both individual keys and the overall identity.\n\n**Required Permissions**\n\nYour credential must grant `write` on the original key:\n`unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write`.\nA matching wildcard grant also satisfies this requirement. The same permission applies to recoverable keys.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId",
"expiration"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "The database identifier of the key to reroll.\n\nThis is the unique ID returned when creating or listing keys, NOT the actual API key token.\nYou can find this ID in:\n- The response from `keys.createKey`\n- Key verification responses\n- The Unkey dashboard\n- API key listing endpoints\n"
},
"expiration": {
"type": [
"integer",
"null"
],
"format": "int64",
"maximum": 4102444800000,
"minimum": 0,
"description": "Duration in milliseconds until the ORIGINAL key is revoked, starting from now.\n\nThis parameter controls the overlap period for key rotation:\n- Set to `0` to revoke the original key immediately\n- Positive values keep the original key active for the specified duration\n- Set to `null` to keep the original key active; it keeps its current expiration, if any\n- Allows graceful migration by giving users time to update their credentials\n\nCommon overlap periods:\n- Immediate revocation: 0\n- 1 hour grace period: 3600000\n- 24 hours grace period: 86400000\n- 7 days grace period: 604800000\n- 30 days grace period: 2592000000\n"
}
}
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Replace all permissions on a key with the specified set in a single atomic operation.
Use this to synchronize with external systems, reset permissions to a known state, or apply standardized permission templates. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have `write` on the target key:
- `unkey:v1:{workspace_id}:projects/{project_id}/keyspaces/{keyspace_id}/keys/{key_id}#write`
When any requested permission slug does not exist in the key's project, your root key must also have:
- `unkey:v1:{workspace_id}:projects/{project_id}/rbac/permissions/*#write`
Use the keyspace ID, not the API ID. You can use wildcard resource IDs to grant access to multiple resources.
**Side Effects**
Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyId
Specifies which key receives the additional permissions using the database identifier returned from `keys.createKey`.
Do not confuse this with the actual API key string that users include in requests.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
permissions
The permissions to set for this key.
This is a complete replacement operation - it overwrites all existing direct permissions with this new set.
Key behaviors:
- Providing an empty array removes all direct permissions from the key
- This only affects direct permissions - permissions granted through roles are not affected
- All existing direct permissions not included in this list will be removed
To create missing permission slugs in the key's project, your root key must also have `unkey:v1:{workspace_id}:projects/{project_id}/rbac/permissions/*#write`. Without this grant, the operation returns HTTP 403. Setting existing permissions does not require this additional grant.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_set_permissions",
"title": "Set key permissions",
"description": "Replace all permissions on a key with the specified set in a single atomic operation.\n\nUse this to synchronize with external systems, reset permissions to a known state, or apply standardized permission templates. Permissions granted through roles remain unchanged.\n\n**Important**: Changes take effect immediately with up to 30-second edge propagation.\n\n**Required Permissions**\n\nYour root key must have `write` on the target key:\n- `unkey:v1:{workspace_id}:projects/{project_id}/keyspaces/{keyspace_id}/keys/{key_id}#write`\n\nWhen any requested permission slug does not exist in the key's project, your root key must also have:\n- `unkey:v1:{workspace_id}:projects/{project_id}/rbac/permissions/*#write`\n\nUse the keyspace ID, not the API ID. You can use wildcard resource IDs to grant access to multiple resources.\n\n**Side Effects**\n\nInvalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId",
"permissions"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key receives the additional permissions using the database identifier returned from `keys.createKey`.\nDo not confuse this with the actual API key string that users include in requests.\n"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "Specify the permission by its slug."
},
"description": "The permissions to set for this key.\n\nThis is a complete replacement operation - it overwrites all existing direct permissions with this new set.\n\nKey behaviors:\n- Providing an empty array removes all direct permissions from the key\n- This only affects direct permissions - permissions granted through roles are not affected\n- All existing direct permissions not included in this list will be removed\n\nTo create missing permission slugs in the key's project, your root key must also have `unkey:v1:{workspace_id}:projects/{project_id}/rbac/permissions/*#write`. Without this grant, the operation returns HTTP 403. Setting existing permissions does not require this additional grant."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Replace all roles on a key with the specified set in a single atomic operation.
Use this to synchronize with external systems, reset roles to a known state, or apply standardized role templates. Direct permissions are never affected.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write` for the target key. A wildcard grant that covers the target key also authorizes this operation.
**Side Effects**
Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyId
Specifies which key gets the complete role replacement using the database identifier returned from createKey.
Do not confuse this with the actual API key string that users include in requests.
This is a wholesale replacement operation that removes all existing roles not included in the request.
Role changes take effect immediately but may take up to 30 seconds to propagate across all regions.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
roles
Replaces all existing role assignments with this complete list of roles.
This is a wholesale replacement operation, not an incremental update like add/remove operations.
Providing an empty array removes all direct role assignments from the key.
All roles must already exist in the workspace - roles cannot be created automatically.
Invalid role references cause the entire operation to fail atomically, ensuring consistent state.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_set_roles",
"title": "Set key roles",
"description": "Replace all roles on a key with the specified set in a single atomic operation.\n\nUse this to synchronize with external systems, reset roles to a known state, or apply standardized role templates. Direct permissions are never affected.\n\n**Important**: Changes take effect immediately with up to 30-second edge propagation.\n\n**Required Permissions**\n\nYour root key must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write` for the target key. A wildcard grant that covers the target key also authorizes this operation.\n\n**Side Effects**\n\nInvalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId",
"roles"
],
"properties": {
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key gets the complete role replacement using the database identifier returned from createKey.\nDo not confuse this with the actual API key string that users include in requests.\nThis is a wholesale replacement operation that removes all existing roles not included in the request.\nRole changes take effect immediately but may take up to 30 seconds to propagate across all regions.\n"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "Specify the role by name."
},
"maxItems": 100,
"description": "Replaces all existing role assignments with this complete list of roles.\nThis is a wholesale replacement operation, not an incremental update like add/remove operations.\n\nProviding an empty array removes all direct role assignments from the key.\nAll roles must already exist in the workspace - roles cannot be created automatically.\nInvalid role references cause the entire operation to fail atomically, ensuring consistent state.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Update credit quotas in response to plan changes, billing cycles, or usage purchases.
Use this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three operations: set, increment, or decrement credits. Set to null for unlimited usage.
**Important**: Setting unlimited credits automatically clears existing refill configurations.
**Required Permissions**
Your credential 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)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#update_key` (to update keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#update_key` (to update keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#update_key` (to update a specific key)
**Side Effects**
Credit updates remove the key from cache immediately. Setting credits to unlimited automatically clears any existing refill settings. Changes take effect instantly but may take up to 30 seconds to propagate to all edge regions.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyId
The ID of the key to update (begins with `key_`). This is the database reference ID for the key, not the actual API key string that users authenticate with. This ID uniquely identifies which key's credits will be updated.
Clear enough to supply this argument.
operation
Defines how to modify the key's remaining credits. Use 'set' to replace current credits with a specific value or unlimited usage, 'increment' to add credits for plan upgrades or credit purchases, and 'decrement' to reduce credits for refunds or policy violations.
Clear enough to supply this argument.
value
The credit value to use with the specified operation. The meaning depends on the operation: for 'set', this becomes the new remaining credits value; for 'increment', this amount is added to current credits; for 'decrement', this amount is subtracted from current credits.
Set to null when using 'set' operation to make the key unlimited (removes usage restrictions entirely). When decrementing, if the result would be negative, remaining credits are automatically set to zero. Credits are consumed during successful key verification, and when credits reach zero, verification fails with `code=USAGE_EXCEEDED`.
Required when using 'increment' or 'decrement' operations. Optional for 'set' operation (null creates unlimited usage).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_update_credits",
"title": "Update key credits",
"description": "Update credit quotas in response to plan changes, billing cycles, or usage purchases.\n\nUse this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three operations: set, increment, or decrement credits. Set to null for unlimited usage.\n\n**Important**: Setting unlimited credits automatically clears existing refill configurations.\n\n**Required Permissions**\n\nYour credential must have one of the following permissions:\n- `api.*.update_key` (to update keys in any API)\n- `api.<api_id>.update_key` (to update keys in a specific API)\n- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#update_key` (to update keys in any keyspace)\n- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#update_key` (to update keys in a specific keyspace)\n- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#update_key` (to update a specific key)\n\n**Side Effects**\n\nCredit updates remove the key from cache immediately. Setting credits to unlimited automatically clears any existing refill settings. Changes take effect instantly but may take up to 30 seconds to propagate to all edge regions.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId",
"operation"
],
"properties": {
"keyId": {
"type": "string",
"minLength": 3,
"description": "The ID of the key to update (begins with `key_`). This is the database reference ID for the key, not the actual API key string that users authenticate with. This ID uniquely identifies which key's credits will be updated."
},
"value": {
"type": [
"integer",
"null"
],
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 0,
"description": "The credit value to use with the specified operation. The meaning depends on the operation: for 'set', this becomes the new remaining credits value; for 'increment', this amount is added to current credits; for 'decrement', this amount is subtracted from current credits.\n\nSet to null when using 'set' operation to make the key unlimited (removes usage restrictions entirely). When decrementing, if the result would be negative, remaining credits are automatically set to zero. Credits are consumed during successful key verification, and when credits reach zero, verification fails with `code=USAGE_EXCEEDED`.\n\nRequired when using 'increment' or 'decrement' operations. Optional for 'set' operation (null creates unlimited usage).\n"
},
"operation": {
"enum": [
"set",
"increment",
"decrement"
],
"type": "string",
"description": "Defines how to modify the key's remaining credits. Use 'set' to replace current credits with a specific value or unlimited usage, 'increment' to add credits for plan upgrades or credit purchases, and 'decrement' to reduce credits for refunds or policy violations.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
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 credential must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write` for the key being updated, or a broader permission that covers it.
**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.
The description explains the capability, when to use it, and what to expect.
Inputs80/100
14 of 16 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
credits › refill › amount
Number of credits to add during each refill cycle.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
credits › refill › interval
How often credits are automatically refilled.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
credits › refill › refillDay
Day of the month for monthly refills (1-31).
Only required when interval is 'monthly'.
For days beyond the month's length, refill occurs on the last day of the month.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
credits › remaining
Number of credits remaining (null for unlimited). This also clears the refilling schedule.
Clear enough to supply this argument.
enabled
Controls whether the key is currently active for verification requests.
When set to `false`, all verification attempts fail with `code=DISABLED` regardless of other settings.
Omitting this field preserves the current enabled status.
Useful for temporarily suspending access during billing issues, security incidents, or maintenance windows without losing key configuration.
Clear enough to supply this argument.
expires
Sets when this key automatically expires as a Unix timestamp in milliseconds.
Verification fails with code=EXPIRED immediately after this time passes.
Omitting this field preserves the current expiration, while setting null makes the key permanent.
Avoid setting timestamps in the past as they immediately invalidate the key.
Keys expire based on server time, not client time, which prevents timezone-related issues.
Active sessions continue until their next verification attempt after expiry.
Clear enough to supply this argument.
externalId
Links this key to a user or entity in your system for ownership tracking during verification.
Omitting this field preserves the current association, while setting null disconnects the key from any identity.
Essential for user-specific analytics, billing, and key management across multiple users.
Supports letters, numbers, underscores, dots, and hyphens for flexible identifier formats.
Clear enough to supply this argument.
keyId
Specifies which key to update using the database identifier returned from `createKey`.
Do not confuse this with the actual API key string that users include in requests.
Clear enough to supply this argument.
meta
Stores arbitrary JSON metadata returned during key verification.
Omitting this field preserves existing metadata, while setting null removes all metadata entirely.
Avoid storing sensitive data here as it's returned in verification responses.
Large metadata objects increase verification latency and should stay under 10KB total size.
Clear enough to supply this argument.
name
Sets a human-readable name for internal organization and identification.
Omitting this field leaves the current name unchanged, while setting null removes it entirely.
Avoid generic names like "API Key" when managing multiple keys per user or service.
Clear enough to supply this argument.
permissions
Not provided
Missing description. Explain what this value means and how to supply it.
ratelimits › items › autoApply
Whether this ratelimit should be automatically applied when verifying a key.
Explain the meaning of this value, not just its name.
ratelimits › items › duration
The duration for each ratelimit window in milliseconds.
This controls how long the rate limit counter accumulates before resetting. Common values include:
- 1000 (1 second): For strict per-second limits on high-frequency operations
- 60000 (1 minute): For moderate API usage control
- 3600000 (1 hour): For less frequent but costly operations
- 86400000 (24 hours): For daily quotas
Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion.
Clear enough to supply this argument.
ratelimits › items › limit
The maximum number of operations allowed within the specified time window.
When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:
- Your infrastructure capacity and scaling limitations
- Fair usage expectations for your service
- Different tier levels for various user types
- The relative cost of the operations being limited
Higher values allow more frequent access but may impact service performance.
Clear enough to supply this argument.
ratelimits › items › name
The name of this rate limit. This name is used to identify which limit to check during key verification.
Best practices for limit names:
- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'
- Be consistent with naming conventions across your application
- Create separate limits for different resource types or operation costs
- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')
You will reference this exact name when verifying keys to check against this specific limit.
Clear enough to supply this argument.
roles
Not provided
Missing description. Explain what this value means and how to supply it.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_update_key",
"title": "Update key settings",
"description": "Update key properties in response to plan changes, subscription updates, or account status changes.\n\nUse 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.\n\n**Important**: Permissions and roles are replaced entirely. Use dedicated add/remove endpoints for incremental changes.\n\n**Required Permissions**\n\nYour credential must have `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write` for the key being updated, or a broader permission that covers it.\n\n**Side Effects**\n\nIf 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.\n",
"inputSchema": {
"type": "object",
"required": [
"keyId"
],
"properties": {
"meta": {
"type": [
"object",
"null"
],
"description": "Stores arbitrary JSON metadata returned during key verification.\nOmitting this field preserves existing metadata, while setting null removes all metadata entirely.\nAvoid storing sensitive data here as it's returned in verification responses.\nLarge metadata objects increase verification latency and should stay under 10KB total size.\n",
"maxProperties": 100,
"additionalProperties": true
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 255,
"minLength": 1,
"description": "Sets a human-readable name for internal organization and identification.\nOmitting this field leaves the current name unchanged, while setting null removes it entirely.\nAvoid generic names like \"API Key\" when managing multiple keys per user or service.\n"
},
"keyId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "Specifies which key to update using the database identifier returned from `createKey`.\nDo not confuse this with the actual API key string that users include in requests.\n"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "Assigns existing roles to this key for permission management through role-based access control.\nRoles must already exist in your workspace before assignment.\nDuring verification, all permissions from assigned roles are checked against requested permissions.\nRoles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.\n"
},
"maxItems": 100
},
"credits": {
"type": [
"object",
"null"
],
"properties": {
"refill": {
"type": [
"object",
"null"
],
"required": [
"interval",
"amount"
],
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 1,
"description": "Number of credits to add during each refill cycle."
},
"interval": {
"enum": [
"daily",
"monthly"
],
"type": "string",
"description": "How often credits are automatically refilled."
},
"refillDay": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day of the month for monthly refills (1-31).\nOnly required when interval is 'monthly'.\nFor days beyond the month's length, refill occurs on the last day of the month.\n"
}
},
"description": "Configuration for automatic credit refill behavior.",
"additionalProperties": false
},
"remaining": {
"type": [
"integer",
"null"
],
"format": "int64",
"maximum": 9223372036854776000,
"minimum": 0,
"description": "Number of credits remaining (null for unlimited). This also clears the refilling schedule."
}
},
"description": "Controls usage-based limits for this key through credit consumption.\nOmitting this field preserves current credit settings, while setting null enables unlimited usage.\nCannot configure refill settings when credits is null, and refillDay requires monthly interval.\nEssential for implementing usage-based pricing and subscription quotas.\n",
"additionalProperties": false
},
"enabled": {
"type": "boolean",
"description": "Controls whether the key is currently active for verification requests.\nWhen set to `false`, all verification attempts fail with `code=DISABLED` regardless of other settings.\nOmitting this field preserves the current enabled status.\nUseful for temporarily suspending access during billing issues, security incidents, or maintenance windows without losing key configuration.\n"
},
"expires": {
"type": [
"integer",
"null"
],
"format": "int64",
"maximum": 4102444800000,
"minimum": 0,
"description": "Sets when this key automatically expires as a Unix timestamp in milliseconds.\nVerification fails with code=EXPIRED immediately after this time passes.\nOmitting this field preserves the current expiration, while setting null makes the key permanent.\n\nAvoid setting timestamps in the past as they immediately invalidate the key.\nKeys expire based on server time, not client time, which prevents timezone-related issues.\nActive sessions continue until their next verification attempt after expiry.\n"
},
"externalId": {
"type": [
"string",
"null"
],
"pattern": "^[a-zA-Z0-9_.-]+$",
"maxLength": 255,
"minLength": 1,
"description": "Links this key to a user or entity in your system for ownership tracking during verification.\nOmitting this field preserves the current association, while setting null disconnects the key from any identity.\nEssential for user-specific analytics, billing, and key management across multiple users.\nSupports letters, numbers, underscores, dots, and hyphens for flexible identifier formats.\n"
},
"ratelimits": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"required": [
"name",
"limit",
"duration",
"autoApply"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 3,
"description": "The name of this rate limit. This name is used to identify which limit to check during key verification.\n\nBest practices for limit names:\n- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'\n- Be consistent with naming conventions across your application\n- Create separate limits for different resource types or operation costs\n- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')\n\nYou will reference this exact name when verifying keys to check against this specific limit."
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "The maximum number of operations allowed within the specified time window.\n\nWhen this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:\n- Your infrastructure capacity and scaling limitations\n- Fair usage expectations for your service\n- Different tier levels for various user types\n- The relative cost of the operations being limited\n\nHigher values allow more frequent access but may impact service performance."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1000,
"description": "The duration for each ratelimit window in milliseconds.\n\nThis controls how long the rate limit counter accumulates before resetting. Common values include:\n- 1000 (1 second): For strict per-second limits on high-frequency operations\n- 60000 (1 minute): For moderate API usage control\n- 3600000 (1 hour): For less frequent but costly operations\n- 86400000 (24 hours): For daily quotas\n\nShorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion."
},
"autoApply": {
"type": "boolean",
"default": false,
"description": "Whether this ratelimit should be automatically applied when verifying a key."
}
}
},
"maxItems": 50,
"description": "Defines time-based rate limits that protect against abuse by controlling request frequency.\nOmitting this field preserves existing rate limits, while setting null removes all rate limits.\nUnlike credits which track total usage, rate limits reset automatically after each window expires.\nMultiple rate limits can control different operation types with separate thresholds and windows.\n"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "Grants specific permissions directly to this key without requiring role membership.\nWildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.\nDirect permissions supplement any permissions inherited from assigned roles.\n"
},
"maxItems": 1000
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
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**: Returns HTTP 200 for all verification outcomes — check the `valid` field in response data to determine if the key is authorized. A 429 may be returned if the workspace exceeds its API rate limit.
**Common use cases:**
- Authenticate API requests before processing
- Enforce permission-based access control
- Track usage and apply rate limits
**Required Permissions**
Your credential needs one of:
- `unkey:v1:<workspace_id>:projects/*/keyspaces/*/keys/*#verify` (verify keys in any project in your workspace)
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/*/keys/*#verify` (verify keys in a specific project)
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#verify` (verify keys in a specific keyspace)
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#verify` (verify a specific key)
Use the keyspace's project ID and keyspace ID, not its API ID. The workspace must match your credential's authorized workspace.
**Note**: If your credential lacks permission to verify this key, the response is HTTP 200 with `valid: false` and `code: NOT_FOUND`. This does not distinguish a missing key from an inaccessible key.
The description explains the capability, when to use it, and what to expect.
Inputs80/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
credits › cost
Sets how many credits to deduct for this verification request.
Use 0 for read-only operations or free tier access, higher values for premium features.
Credits are deducted after all security checks pass.
Essential for implementing usage-based pricing with different operation costs.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
key
The API key to verify, exactly as provided by your user.
Include any prefix - even small changes will cause verification to fail.
Clear enough to supply this argument.
keyspaces
Restricts verification to keys in these keyspaces, matched by exact ID.
Omit this field to verify without a keyspace restriction.
A failed keyspace check returns `NOT_FOUND` without consuming credits or rate limits.
Clear enough to supply this argument.
migrationId
Migrate keys on demand from your previous system. Reach out for migration support at [email protected]
Explain the meaning of this value, not just its name.
permissions
Checks if the key has the specified permission(s) using a query syntax.
Supports single permissions, logical operators (AND, OR), and parentheses for grouping.
Examples:
- Single permission: "documents.read"
- Multiple permissions: "documents.read AND documents.write"
- Complex queries: "(documents.read OR documents.write) AND users.view"
Verification fails if the key lacks the required permissions through direct assignment or role inheritance.
Clear enough to supply this argument.
ratelimits › items › cost
Optionally override how expensive this operation is and how many tokens are deducted from the current limit.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
ratelimits › items › duration
Optionally override the duration of the rate limit window duration.
Explain the meaning of this value, not just its name.
ratelimits › items › limit
Optionally override the maximum number of requests allowed within the specified interval.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
ratelimits › items › name
References an existing ratelimit by its name. Key Ratelimits will take precedence over identifier-based limits.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
tags
Attaches metadata tags for analytics and monitoring without affecting verification outcomes.
Enables segmentation of API usage in dashboards by endpoint, client version, region, or custom dimensions.
Use 'key=value' format for compatibility with most analytics tools and clear categorization.
Avoid including sensitive data in tags as they may appear in logs and analytics reports.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_verify_key",
"title": "Verify API key",
"description": "Verify an API key's validity and permissions for request authentication.\n\nUse this endpoint on every incoming request to your protected resources. It checks key validity, permissions, rate limits, and usage quotas in a single call.\n\n**Important**: Returns HTTP 200 for all verification outcomes — check the `valid` field in response data to determine if the key is authorized. A 429 may be returned if the workspace exceeds its API rate limit.\n\n**Common use cases:**\n- Authenticate API requests before processing\n- Enforce permission-based access control\n- Track usage and apply rate limits\n\n**Required Permissions**\n\nYour credential needs one of:\n- `unkey:v1:<workspace_id>:projects/*/keyspaces/*/keys/*#verify` (verify keys in any project in your workspace)\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/*/keys/*#verify` (verify keys in a specific project)\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#verify` (verify keys in a specific keyspace)\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#verify` (verify a specific key)\n\nUse the keyspace's project ID and keyspace ID, not its API ID. The workspace must match your credential's authorized workspace.\n\n**Note**: If your credential lacks permission to verify this key, the response is HTTP 200 with `valid: false` and `code: NOT_FOUND`. This does not distinguish a missing key from an inaccessible key.\n",
"inputSchema": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The API key to verify, exactly as provided by your user.\nInclude any prefix - even small changes will cause verification to fail.\n"
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 512,
"minLength": 1
},
"maxItems": 20,
"description": "Attaches metadata tags for analytics and monitoring without affecting verification outcomes.\nEnables segmentation of API usage in dashboards by endpoint, client version, region, or custom dimensions.\nUse 'key=value' format for compatibility with most analytics tools and clear categorization.\nAvoid including sensitive data in tags as they may appear in logs and analytics reports.\n"
},
"credits": {
"type": "object",
"required": [
"cost"
],
"properties": {
"cost": {
"type": "integer",
"format": "int64",
"maximum": 1000000000000,
"minimum": 0,
"description": "Sets how many credits to deduct for this verification request.\nUse 0 for read-only operations or free tier access, higher values for premium features.\nCredits are deducted after all security checks pass.\nEssential for implementing usage-based pricing with different operation costs.\n"
}
},
"description": "Controls credit consumption for usage-based billing and quota enforcement.\nOmitting this field uses the default cost of 1 credit per verification.\nCredits provide globally consistent usage tracking, essential for paid APIs with strict quotas.\n",
"additionalProperties": false
},
"keyspaces": {
"type": "array",
"items": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"maxItems": 5,
"minItems": 1,
"description": "Restricts verification to keys in these keyspaces, matched by exact ID.\nOmit this field to verify without a keyspace restriction.\nA failed keyspace check returns `NOT_FOUND` without consuming credits or rate limits.\n"
},
"ratelimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"cost": {
"type": "integer",
"default": 1,
"maximum": 9223372036854776000,
"minimum": 0,
"description": "Optionally override how expensive this operation is and how many tokens are deducted from the current limit."
},
"name": {
"type": "string",
"maxLength": 255,
"minLength": 3,
"description": "References an existing ratelimit by its name. Key Ratelimits will take precedence over identifier-based limits."
},
"limit": {
"type": "integer",
"maximum": 9223372036854776000,
"minimum": 0,
"description": "Optionally override the maximum number of requests allowed within the specified interval."
},
"duration": {
"type": "integer",
"maximum": 31536000000,
"minimum": 0,
"description": "Optionally override the duration of the rate limit window duration."
}
}
},
"maxItems": 50,
"description": "Enforces time-based rate limiting during verification to prevent abuse and ensure fair usage.\nOmitting this field skips rate limit checks entirely, relying only on configured key rate limits.\nMultiple rate limits can be checked simultaneously, each with different costs and temporary overrides.\nRate limit checks are optimized for performance but may allow brief bursts during high concurrency.\n"
},
"migrationId": {
"type": "string",
"maxLength": 256,
"description": "Migrate keys on demand from your previous system. Reach out for migration support at [email protected]"
},
"permissions": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "Checks if the key has the specified permission(s) using a query syntax.\nSupports single permissions, logical operators (AND, OR), and parentheses for grouping.\nExamples:\n- Single permission: \"documents.read\"\n- Multiple permissions: \"documents.read AND documents.write\"\n- Complex queries: \"(documents.read OR documents.write) AND users.view\"\nVerification fails if the key lacks the required permissions through direct assignment or role inheritance.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
Align the title with the capability actually described by this tool.
Description64/100
Find out what key this is.
**Required Permissions**
Your credential 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)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)
If your credential lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existence of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your credential has the correct permissions.
Describe the concrete operation and its scope instead of restating the tool name.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
key
The complete API key string provided by you, including any prefix.
Never log, cache, or store API keys in your system as they provide full access to user resources.
Include the full key exactly as provided - even minor modifications will cause a not found error.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_keys_whoami",
"title": "Get API key by hash",
"description": "Find out what key this is.\n\n**Required Permissions**\n\nYour credential must have one of the following permissions for basic key information:\n- `api.*.read_key` (to read keys from any API)\n- `api.<api_id>.read_key` (to read keys from a specific API)\n- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)\n- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)\n- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)\n\nIf your credential lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existence of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your credential has the correct permissions.\n",
"inputSchema": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The complete API key string provided by you, including any prefix.\nNever log, cache, or store API keys in your system as they provide full access to user resources.\nInclude the full key exactly as provided - even minor modifications will cause a not found error.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description80/100
Count the requests that the Unkey API served for your workspace per time bucket, split by status class.
The filters have the same shape as in `logs.listApiRequests`, without `requestId`. In one field, values under `is`, `contains`, `startsWith`, and `endsWith` are combined with OR. Values under `isNot` and `notContains`, and the range operators `gt`, `gte`, `lt`, and `lte`, are combined with AND. Different fields are combined with AND. Every text match is exact and case-sensitive.
`filters.time` sets the window. A missing lower bound is the start of your log retention, and a missing upper bound is now. Unkey picks the bucket width from the window. It is the distance between the `time` of two points. The first bucket starts at or before the window start and counts its whole width. Windows reach back at most 100 days, and requests outside the log retention of your workspace are not counted.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:logs/apiRequests#read`
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › method › is
Keep rows with one of these methods.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › method › isNot
Remove rows with one of these methods.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › contains
Keep rows where the field contains one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › endsWith
Keep rows where the field ends with one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › is
Keep rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › isNot
Remove rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › notContains
Remove rows where the field contains one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › startsWith
Keep rows where the field starts with one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › gt
Keep rows where the field is greater than this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › gte
Keep rows where the field is greater than or equal to this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › is
Keep rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › isNot
Remove rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › lt
Keep rows where the field is less than this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › lte
Keep rows where the field is less than or equal to this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › time › gt
Keep events after this time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › time › gte
Keep events at or after this time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › time › lt
Keep events before this time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › time › lte
Keep events at or before this time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_logs_get_api_request_metrics",
"title": "Get API request metrics",
"description": "Count the requests that the Unkey API served for your workspace per time bucket, split by status class.\n\nThe filters have the same shape as in `logs.listApiRequests`, without `requestId`. In one field, values under `is`, `contains`, `startsWith`, and `endsWith` are combined with OR. Values under `isNot` and `notContains`, and the range operators `gt`, `gte`, `lt`, and `lte`, are combined with AND. Different fields are combined with AND. Every text match is exact and case-sensitive.\n\n`filters.time` sets the window. A missing lower bound is the start of your log retention, and a missing upper bound is now. Unkey picks the bucket width from the window. It is the distance between the `time` of two points. The first bucket starts at or before the window start and counts its whole width. Windows reach back at most 100 days, and requests outside the log retention of your workspace are not counted.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:logs/apiRequests#read`\n",
"inputSchema": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"properties": {
"path": {
"type": "object",
"properties": {
"is": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field equals one of the values."
},
"isNot": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Remove rows where the field equals one of the values."
},
"contains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field contains one of the values."
},
"endsWith": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field ends with one of the values."
},
"startsWith": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field starts with one of the values."
},
"notContains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Remove rows where the field contains one of the values."
}
},
"description": "Filters a text field. Every operator is exact and case-sensitive. `%` and `_` match only themselves.\nThe positive operators (`is`, `contains`, `startsWith`, `endsWith`) are combined with OR.\nThe negated operators (`isNot`, `notContains`) are combined with AND.\n",
"additionalProperties": false
},
"time": {
"type": "object",
"properties": {
"gt": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Keep events after this time."
},
"lt": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Keep events before this time."
},
"gte": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Keep events at or after this time."
},
"lte": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Keep events at or before this time."
}
},
"description": "Filters by the time of the event, in Unix milliseconds. Every bound is combined with AND.\nRows older than the workspace's retention are never returned or counted, whatever the bounds.\n",
"additionalProperties": false
},
"method": {
"type": "object",
"properties": {
"is": {
"type": "array",
"items": {
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE",
"HEAD",
"OPTIONS"
],
"type": "string",
"description": "An HTTP method in upper case."
},
"minItems": 1,
"description": "Keep rows with one of these methods.",
"uniqueItems": true
},
"isNot": {
"type": "array",
"items": {
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE",
"HEAD",
"OPTIONS"
],
"type": "string",
"description": "An HTTP method in upper case."
},
"minItems": 1,
"description": "Remove rows with one of these methods.",
"uniqueItems": true
}
},
"description": "Filters by HTTP method.",
"additionalProperties": false
},
"status": {
"type": "object",
"properties": {
"gt": {
"type": "integer",
"format": "int64",
"description": "Keep rows where the field is greater than this value."
},
"is": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field equals one of the values."
},
"lt": {
"type": "integer",
"format": "int64",
"description": "Keep rows where the field is less than this value."
},
"gte": {
"type": "integer",
"format": "int64",
"description": "Keep rows where the field is greater than or equal to this value."
},
"lte": {
"type": "integer",
"format": "int64",
"description": "Keep rows where the field is less than or equal to this value."
},
"isNot": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"maxItems": 10,
"minItems": 1,
"description": "Remove rows where the field equals one of the values."
}
},
"description": "Filters an integer field. `is` keeps rows that equal one of its values.\n`isNot` and every bound (`gt`, `gte`, `lt`, `lte`) are combined with AND, so `{ \"is\": [200], \"gte\": 400 }` matches no rows.\n",
"additionalProperties": false
}
},
"description": "Filters for the metrics. They have the same shape as the filters of `logs.listApiRequests`, without `requestId`. A missing field does not filter. Different fields are combined with AND.\n",
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description84/100
List the requests that the Unkey API served for your workspace, newest first.
Filter by time, path, method, request ID, and status. In one field, values under `is`, `contains`, `startsWith`, and `endsWith` are combined with OR. Values under `isNot` and `notContains`, and the range operators `gt`, `gte`, `lt`, and `lte`, are combined with AND. Different fields are combined with AND. Every text match is exact and case-sensitive.
To get the next page, send the `pagination.cursor` of the previous page together with the same `filters`. A cursor does not expire, but rows older than the log retention leave the listing.
Unkey returns only requests inside the log retention of your workspace. The calls to this endpoint are not logged.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:logs/apiRequests#read`
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
The `pagination.cursor` of the previous page. Send the same `filters` with every page of one listing.
Omit the cursor to get the first page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › method › is
Keep rows with one of these methods.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › method › isNot
Remove rows with one of these methods.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › contains
Keep rows where the field contains one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › endsWith
Keep rows where the field ends with one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › is
Keep rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › isNot
Remove rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › notContains
Remove rows where the field contains one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › path › startsWith
Keep rows where the field starts with one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › requestId › is
Keep rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › requestId › isNot
Remove rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › gt
Keep rows where the field is greater than this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › gte
Keep rows where the field is greater than or equal to this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › is
Keep rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › isNot
Remove rows where the field equals one of the values.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › lt
Keep rows where the field is less than this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › status › lte
Keep rows where the field is less than or equal to this value.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › time › gt
Keep events after this time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › time › gte
Keep events at or after this time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › time › lt
Keep events before this time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › time › lte
Keep events at or before this time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
The maximum number of requests to return in one page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_logs_list_api_requests",
"title": "List API requests",
"description": "List the requests that the Unkey API served for your workspace, newest first.\n\nFilter by time, path, method, request ID, and status. In one field, values under `is`, `contains`, `startsWith`, and `endsWith` are combined with OR. Values under `isNot` and `notContains`, and the range operators `gt`, `gte`, `lt`, and `lte`, are combined with AND. Different fields are combined with AND. Every text match is exact and case-sensitive.\n\nTo get the next page, send the `pagination.cursor` of the previous page together with the same `filters`. A cursor does not expire, but rows older than the log retention leave the listing.\n\nUnkey returns only requests inside the log retention of your workspace. The calls to this endpoint are not logged.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:logs/apiRequests#read`\n",
"inputSchema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1,
"description": "The maximum number of requests to return in one page."
},
"cursor": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "The `pagination.cursor` of the previous page. Send the same `filters` with every page of one listing.\nOmit the cursor to get the first page.\n"
},
"filters": {
"type": "object",
"properties": {
"path": {
"type": "object",
"properties": {
"is": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field equals one of the values."
},
"isNot": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Remove rows where the field equals one of the values."
},
"contains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field contains one of the values."
},
"endsWith": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field ends with one of the values."
},
"startsWith": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field starts with one of the values."
},
"notContains": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "Remove rows where the field contains one of the values."
}
},
"description": "Filters a text field. Every operator is exact and case-sensitive. `%` and `_` match only themselves.\nThe positive operators (`is`, `contains`, `startsWith`, `endsWith`) are combined with OR.\nThe negated operators (`isNot`, `notContains`) are combined with AND.\n",
"additionalProperties": false
},
"time": {
"type": "object",
"properties": {
"gt": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Keep events after this time."
},
"lt": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Keep events before this time."
},
"gte": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Keep events at or after this time."
},
"lte": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Keep events at or before this time."
}
},
"description": "Filters by the time of the event, in Unix milliseconds. Every bound is combined with AND.\nRows older than the workspace's retention are never returned or counted, whatever the bounds.\n",
"additionalProperties": false
},
"method": {
"type": "object",
"properties": {
"is": {
"type": "array",
"items": {
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE",
"HEAD",
"OPTIONS"
],
"type": "string",
"description": "An HTTP method in upper case."
},
"minItems": 1,
"description": "Keep rows with one of these methods.",
"uniqueItems": true
},
"isNot": {
"type": "array",
"items": {
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE",
"HEAD",
"OPTIONS"
],
"type": "string",
"description": "An HTTP method in upper case."
},
"minItems": 1,
"description": "Remove rows with one of these methods.",
"uniqueItems": true
}
},
"description": "Filters by HTTP method.",
"additionalProperties": false
},
"status": {
"type": "object",
"properties": {
"gt": {
"type": "integer",
"format": "int64",
"description": "Keep rows where the field is greater than this value."
},
"is": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"maxItems": 10,
"minItems": 1,
"description": "Keep rows where the field equals one of the values."
},
"lt": {
"type": "integer",
"format": "int64",
"description": "Keep rows where the field is less than this value."
},
"gte": {
"type": "integer",
"format": "int64",
"description": "Keep rows where the field is greater than or equal to this value."
},
"lte": {
"type": "integer",
"format": "int64",
"description": "Keep rows where the field is less than or equal to this value."
},
"isNot": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"maxItems": 10,
"minItems": 1,
"description": "Remove rows where the field equals one of the values."
}
},
"description": "Filters an integer field. `is` keeps rows that equal one of its values.\n`isNot` and every bound (`gt`, `gte`, `lt`, `lte`) are combined with AND, so `{ \"is\": [200], \"gte\": 400 }` matches no rows.\n",
"additionalProperties": false
},
"requestId": {
"type": "object",
"properties": {
"is": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 25,
"minItems": 1,
"description": "Keep rows where the field equals one of the values."
},
"isNot": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"maxItems": 25,
"minItems": 1,
"description": "Remove rows where the field equals one of the values."
}
},
"description": "Filters a field that matches only as a whole value, such as a host or a request ID.\nMatching is exact and case-sensitive.\n",
"additionalProperties": false
}
},
"description": "Filters for the listing. A missing field does not filter. Different fields are combined with AND.\n",
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
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 slugs must be unique within the workspace. Names do not need to be unique. Once created, permissions are immediately available for assignment.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*#write`
Use your workspace ID and its default project ID. A wildcard project grant also authorizes this operation.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
description
Provides detailed documentation of what this permission grants access to.
Include information about affected resources, allowed actions, and any important limitations.
This internal documentation helps team members understand permission scope and security implications.
Not visible to end users - designed for development teams and security audits.
Consider documenting:
- What resources can be accessed
- What operations are permitted
- Any conditions or limitations
- Related permissions that might be needed
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
Creates a permission with this human-readable name that describes its purpose.
Use clear, semantic names that developers can easily understand when building authorization logic.
Consider using hierarchical naming conventions like 'resource.action' for better organization.
Examples: 'users.read', 'billing.write', 'analytics.view', 'admin.manage'
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
slug
Creates a URL-safe identifier for this permission that can be used in APIs and integrations.
Must start with a letter and contain only letters, numbers, periods, underscores, and hyphens.
Slugs are often used in REST endpoints, configuration files, and external integrations.
Should closely match the name but in a format suitable for technical usage.
Must be unique within your workspace to ensure reliable permission lookups.
Keep slugs concise but descriptive for better developer experience.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_create_permission",
"title": "Create permission",
"description": "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.\n\nUse hierarchical naming patterns like `documents.read`, `admin.users.delete`, or `billing.invoices.create` for clear organization.\n\n**Important:** Permission slugs must be unique within the workspace. Names do not need to be unique. Once created, permissions are immediately available for assignment.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*#write`\n\nUse your workspace ID and its default project ID. A wildcard project grant also authorizes this operation.\n",
"inputSchema": {
"type": "object",
"required": [
"name",
"slug"
],
"properties": {
"name": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Creates a permission with this human-readable name that describes its purpose.\nUse clear, semantic names that developers can easily understand when building authorization logic.\nConsider using hierarchical naming conventions like 'resource.action' for better organization.\n\nExamples: 'users.read', 'billing.write', 'analytics.view', 'admin.manage'\n"
},
"slug": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "Creates a URL-safe identifier for this permission that can be used in APIs and integrations.\nMust start with a letter and contain only letters, numbers, periods, underscores, and hyphens.\nSlugs are often used in REST endpoints, configuration files, and external integrations.\nShould closely match the name but in a format suitable for technical usage.\nMust be unique within your workspace to ensure reliable permission lookups.\n\nKeep slugs concise but descriptive for better developer experience.\n"
},
"description": {
"type": "string",
"maxLength": 512,
"description": "Provides detailed documentation of what this permission grants access to.\nInclude information about affected resources, allowed actions, and any important limitations.\nThis internal documentation helps team members understand permission scope and security implications.\nNot visible to end users - designed for development teams and security audits.\n\nConsider documenting:\n- What resources can be accessed\n- What operations are permitted\n- Any conditions or limitations\n- Related permissions that might be needed\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys. Permission slugs supplied in `permissions` are attached during creation. Missing permissions are created automatically.
**Important:** Role names must be unique within the workspace. Once created, roles are immediately available for assignment.
**Required Permissions**
Your root key must always have:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/roles/*#write`
When any requested permission slug does not exist, it must also have:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*#write`
Both grants must cover the authenticated workspace and its default project. Attaching existing permissions requires only role write access.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
description
Provides comprehensive documentation of what this role encompasses and what access it grants.
Include information about the intended use case, what permissions should be assigned, and any important considerations.
This internal documentation helps team members understand role boundaries and security implications.
Not visible to end users - designed for administration teams and access control audits.
Consider documenting:
- The role's intended purpose and scope
- What types of users should receive this role
- What permissions are typically associated with it
- Any security considerations or limitations
- Related roles that might be used together
Clear enough to supply this argument.
name
The unique name for this role. Must be unique within your workspace and clearly indicate the role's purpose. Use descriptive names like 'admin', 'editor', or 'Billing Manager'.
Examples: 'admin.billing', 'support.readonly', 'developer.api', 'Billing Manager'
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
permissions
Permission slugs to attach to the role. Existing permissions are reused. Missing permissions are created automatically when the root key has `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*#write` for the authenticated workspace and its default project.
Omit this field or provide an empty array to create the role without permissions.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_create_role",
"title": "Create role",
"description": "Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys. Permission slugs supplied in `permissions` are attached during creation. Missing permissions are created automatically.\n\n**Important:** Role names must be unique within the workspace. Once created, roles are immediately available for assignment.\n\n**Required Permissions**\n\nYour root key must always have:\n- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/roles/*#write`\n\nWhen any requested permission slug does not exist, it must also have:\n- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*#write`\n\nBoth grants must cover the authenticated workspace and its default project. Attaching existing permissions requires only role write access.\n",
"inputSchema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "The unique name for this role. Must be unique within your workspace and clearly indicate the role's purpose. Use descriptive names like 'admin', 'editor', or 'Billing Manager'.\n\nExamples: 'admin.billing', 'support.readonly', 'developer.api', 'Billing Manager'\n"
},
"description": {
"type": "string",
"maxLength": 512,
"description": "Provides comprehensive documentation of what this role encompasses and what access it grants.\nInclude information about the intended use case, what permissions should be assigned, and any important considerations.\nThis internal documentation helps team members understand role boundaries and security implications.\nNot visible to end users - designed for administration teams and access control audits.\n\nConsider documenting:\n- The role's intended purpose and scope\n- What types of users should receive this role\n- What permissions are typically associated with it\n- Any security considerations or limitations\n- Related roles that might be used together\n"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "Specify the permission by its slug."
},
"maxItems": 1000,
"description": "Permission slugs to attach to the role. Existing permissions are reused. Missing permissions are created automatically when the root key has `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*#write` for the authenticated workspace and its default project.\n\nOmit this field or provide an empty array to create the role without permissions.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
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:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/<permission_id>#delete`
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
permission
Specifies which permission to permanently delete from your workspace.
This can be a permission ID or a permission slug.
WARNING: Deleting a permission has immediate and irreversible consequences:
- All API keys with this permission will lose that access immediately
- All roles containing this permission will have it removed
- Any verification requests checking for this permission will fail
- This action cannot be undone
Before deletion, ensure you:
- Have updated any keys or roles that depend on this permission
- Have migrated to alternative permissions if needed
- Have notified affected users about the access changes
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_delete_permission",
"title": "Delete permission",
"description": "Remove a permission from your workspace. This also removes the permission from all API keys and roles.\n\n**Important:** This operation cannot be undone and immediately affects all API keys and roles that had this permission assigned.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/<permission_id>#delete`\n",
"inputSchema": {
"type": "object",
"required": [
"permission"
],
"properties": {
"permission": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "Specifies which permission to permanently delete from your workspace.\n\nThis can be a permission ID or a permission slug.\n\nWARNING: Deleting a permission has immediate and irreversible consequences:\n- All API keys with this permission will lose that access immediately\n- All roles containing this permission will have it removed\n- Any verification requests checking for this permission will fail\n- This action cannot be undone\n\nBefore deletion, ensure you:\n- Have updated any keys or roles that depend on this permission\n- Have migrated to alternative permissions if needed\n- Have notified affected users about the access changes\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
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 `unkey:v1:{workspaceId}:projects/{projectId}/rbac/roles/{roleId}#delete` for the role. A wildcard grant that covers the role also authorizes deletion.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
role
Unique identifier of the role to permanently delete from your workspace.
Must either be a valid role ID that begins with 'role_' or the given role name and exists within your workspace.
WARNING: Deletion is immediate and irreversible with significant consequences:
- All API keys assigned this role will lose the associated permissions
- Access to resources protected by this role's permissions will be denied
- Any authorization logic depending on this role will start failing
- Historical analytics referencing this role remain intact
Before deletion, ensure:
- You've updated any dependent authorization logic or code
- You've migrated any keys to use alternative roles or direct permissions
- You've notified relevant team members of the access changes
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_delete_role",
"title": "Delete role",
"description": "Remove a role from your workspace. This also removes the role from all assigned API keys.\n\n**Important:** This operation cannot be undone and immediately affects all API keys that had this role assigned.\n\n**Required Permissions**\n\nYour root key must have `unkey:v1:{workspaceId}:projects/{projectId}/rbac/roles/{roleId}#delete` for the role. A wildcard grant that covers the role also authorizes deletion.\n",
"inputSchema": {
"type": "object",
"required": [
"role"
],
"properties": {
"role": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "Unique identifier of the role to permanently delete from your workspace.\nMust either be a valid role ID that begins with 'role_' or the given role name and exists within your workspace.\n\nWARNING: Deletion is immediate and irreversible with significant consequences:\n- All API keys assigned this role will lose the associated permissions\n- Access to resources protected by this role's permissions will be denied\n- Any authorization logic depending on this role will start failing\n- Historical analytics referencing this role remain intact\n\nBefore deletion, ensure:\n- You've updated any dependent authorization logic or code\n- You've migrated any keys to use alternative roles or direct permissions\n- You've notified relevant team members of the access changes\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Shorten the title to an action and subject; move usage details into the description.
Description80/100
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`
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
permission
The unique identifier of the permission to retrieve. Must be a valid permission ID that begins with 'perm_' and exists within your workspace.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_get_permission",
"title": "Get permission",
"description": "Retrieve details about a specific permission including its name, description, and metadata.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `rbac.*.read_permission`\n",
"inputSchema": {
"type": "object",
"required": [
"permission"
],
"properties": {
"permission": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "The unique identifier of the permission to retrieve. Must be a valid permission ID that begins with 'perm_' and exists within your workspace.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description80/100
Retrieve details about a specific role including its assigned permissions.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_role`
Describe the returned information so the agent knows whether it will answer the request.
Inputs0/100
Resolve the mismatch between this description and its schema constraints.
role
Unique identifier of the role to permanently delete from your workspace.
Must either be a valid role ID that begins with 'role_' or the given role name and exists within your workspace.
Use this endpoint to verify role details, check its current permissions, or retrieve metadata.
Returns complete role information including all assigned permissions for comprehensive access review.
Resolve the mismatch between this description and its schema constraints.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_get_role",
"title": "Get role",
"description": "Retrieve details about a specific role including its assigned permissions.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `rbac.*.read_role`\n",
"inputSchema": {
"type": "object",
"required": [
"role"
],
"properties": {
"role": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "Unique identifier of the role to permanently delete from your workspace.\nMust either be a valid role ID that begins with 'role_' or the given role name and exists within your workspace.\n\nUse this endpoint to verify role details, check its current permissions, or retrieve metadata.\nReturns complete role information including all assigned permissions for comprehensive access review.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description80/100
Retrieve all permissions in your workspace.
Results are paginated and sorted by their id.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_permission`
Describe the returned information so the agent knows whether it will answer the request.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response to fetch the next page of permissions.
Include this value when you need to retrieve additional permissions beyond the initial response.
Each response containing more results than the requested limit includes a cursor for subsequent pages.
Leave empty or omit this field to start from the beginning of the permission list.
Cursors are temporary and may expire - always handle cases where a cursor becomes invalid.
Clear enough to supply this argument.
limit
Maximum number of permissions to return in a single response.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Free-form text to filter permissions. Returns permissions whose ID, name, slug, or description contains the search string. Matching is case-insensitive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_list_permissions",
"title": "List permissions",
"description": "Retrieve all permissions in your workspace.\nResults are paginated and sorted by their id.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `rbac.*.read_permission`\n",
"inputSchema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of permissions to return in a single response."
},
"cursor": {
"type": "string",
"maxLength": 1024,
"description": "Pagination cursor from a previous response to fetch the next page of permissions.\nInclude this value when you need to retrieve additional permissions beyond the initial response.\nEach response containing more results than the requested limit includes a cursor for subsequent pages.\n\nLeave empty or omit this field to start from the beginning of the permission list.\nCursors are temporary and may expire - always handle cases where a cursor becomes invalid.\n"
},
"search": {
"type": "string",
"maxLength": 256,
"description": "Free-form text to filter permissions. Returns permissions whose ID, name, slug, or description contains the search string. Matching is case-insensitive."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
Retrieve all roles in your workspace including their assigned permissions.
Results are paginated and sorted by their id.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_role`
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response to fetch the next page of roles.
Include this when you need to retrieve additional roles beyond the first page.
Each response containing more results will include a cursor value that can be used here.
Leave empty or omit this field to start from the beginning of the role list.
Clear enough to supply this argument.
limit
Maximum number of roles to return in a single response.
Use smaller values for faster response times and better UI performance.
Use larger values when you need to process many roles efficiently.
Results exceeding this limit will be paginated with a cursor for continuation.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Free-form text to filter roles. Returns roles whose ID, name, or description contains the search string. Matching is case-insensitive.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_list_roles",
"title": "List roles",
"description": "Retrieve all roles in your workspace including their assigned permissions.\nResults are paginated and sorted by their id.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `rbac.*.read_role`\n",
"inputSchema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of roles to return in a single response.\nUse smaller values for faster response times and better UI performance.\nUse larger values when you need to process many roles efficiently.\nResults exceeding this limit will be paginated with a cursor for continuation.\n"
},
"cursor": {
"type": "string",
"maxLength": 1024,
"description": "Pagination cursor from a previous response to fetch the next page of roles.\nInclude this when you need to retrieve additional roles beyond the first page.\nEach response containing more results will include a cursor value that can be used here.\nLeave empty or omit this field to start from the beginning of the role list.\n"
},
"search": {
"type": "string",
"maxLength": 256,
"description": "Free-form text to filter roles. Returns roles whose ID, name, or description contains the search string. Matching is case-insensitive."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Atomically replaces all permissions directly assigned to a role. An empty `permissions` array removes every permission from the role. Permissions that do not exist are created when the caller has permission to create them.
**Required Permissions**
Your root key must have:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/roles/<role_id>#write`
When any requested permission slug does not exist, it must also have:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*#write`
Use the role's workspace, project, and role IDs in these permissions.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
permissions
The complete set of permission slugs to assign directly to the role. Missing permissions are created when authorized. An empty array clears all direct permissions.
Clear enough to supply this argument.
role
The role whose directly assigned permissions will be replaced.
Accepts either the generated role ID or the unique role name.
Clear enough to supply this argument.
roleId
Deprecated. Use `role` instead.
Accepts either the generated role ID or the unique role name.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_set_role_permissions",
"title": "Set role permissions",
"description": "Atomically replaces all permissions directly assigned to a role. An empty `permissions` array removes every permission from the role. Permissions that do not exist are created when the caller has permission to create them.\n\n**Required Permissions**\n\nYour root key must have:\n- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/roles/<role_id>#write`\n\nWhen any requested permission slug does not exist, it must also have:\n- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/*#write`\n\nUse the role's workspace, project, and role IDs in these permissions.\n",
"inputSchema": {
"type": "object",
"oneOf": [
{
"required": [
"role"
]
},
{
"required": [
"roleId"
]
}
],
"required": [
"permissions"
],
"properties": {
"role": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "The role whose directly assigned permissions will be replaced.\nAccepts either the generated role ID or the unique role name.\n"
},
"roleId": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"deprecated": true,
"description": "Deprecated. Use `role` instead.\nAccepts either the generated role ID or the unique role name.\n"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1
},
"maxItems": 1000,
"description": "The complete set of permission slugs to assign directly to the role. Missing permissions are created when authorized. An empty array clears all direct permissions."
}
},
"description": "Provide exactly one of `role` or the deprecated `roleId`.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Shorten the title to an action and subject; move usage details into the description.
Description94/100
Update the name, slug, or description of a permission, identified by its ID or slug.
Omitted fields keep their current values. A request with no fields to update returns the stored permission without a write.
**Important**: Keys and roles reference the permission by ID, so they keep the permission after a slug change. Key verification can return the old slug for a short time while caches refresh. A slug that another permission in your workspace already uses returns 409.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/<permission_id>#write`
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
description
New description for the permission.
Omit this field to keep the current description. Send null or an empty string to remove it.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
New human-readable name for the permission.
Omit this field to keep the current name.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
permission
The permission to update. Pass the permission ID (`perm_...`) or its current slug.
Clear enough to supply this argument.
slug
New slug for the permission. Keys and roles that have this permission get the new slug in verification responses.
The slug must be unique in your workspace.
Omit this field to keep the current slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_update_permission",
"title": "Update permission",
"description": "Update the name, slug, or description of a permission, identified by its ID or slug.\n\nOmitted fields keep their current values. A request with no fields to update returns the stored permission without a write.\n\n**Important**: Keys and roles reference the permission by ID, so they keep the permission after a slug change. Key verification can return the old slug for a short time while caches refresh. A slug that another permission in your workspace already uses returns 409.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/<permission_id>#write`\n",
"inputSchema": {
"type": "object",
"required": [
"permission"
],
"properties": {
"name": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "New human-readable name for the permission.\nOmit this field to keep the current name.\n"
},
"slug": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "New slug for the permission. Keys and roles that have this permission get the new slug in verification responses.\nThe slug must be unique in your workspace.\nOmit this field to keep the current slug.\n"
},
"permission": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1,
"description": "The permission to update. Pass the permission ID (`perm_...`) or its current slug.\n"
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 512,
"description": "New description for the permission.\nOmit this field to keep the current description. Send null or an empty string to remove it.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Shorten the title to an action and subject; move usage details into the description.
Description93/100
Update the name or description of a role, identified by its ID or name.
Omitted fields keep their current values. A request with no fields to update returns the stored role without a write.
This endpoint does not change the role's permissions or keys. Use `permissions.setRolePermissions`, `keys.addRoles`, and `keys.removeRoles` for those.
**Important**: Keys keep the role after a rename. Requests that name the role, such as `keys.addRoles`, must use the new name. Key verification can return the old name for a short time while caches refresh. A name that another role in your workspace already uses returns 409.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/roles/<role_id>#write`
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
description
New description for the role.
Omit this field to keep the current description. Send null or an empty string to remove it.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
New name for the role. The name must be unique in your workspace.
Omit this field to keep the current name.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
role
The role to update. Pass the role ID (`role_...`) or its current name.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_permissions_update_role",
"title": "Update role",
"description": "Update the name or description of a role, identified by its ID or name.\n\nOmitted fields keep their current values. A request with no fields to update returns the stored role without a write.\n\nThis endpoint does not change the role's permissions or keys. Use `permissions.setRolePermissions`, `keys.addRoles`, and `keys.removeRoles` for those.\n\n**Important**: Keys keep the role after a rename. Requests that name the role, such as `keys.addRoles`, must use the new name. Key verification can return the old name for a short time while caches refresh. A name that another role in your workspace already uses returns 409.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:projects/<project_id>/rbac/roles/<role_id>#write`\n",
"inputSchema": {
"type": "object",
"required": [
"role"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "New name for the role. The name must be unique in your workspace.\nOmit this field to keep the current name.\n"
},
"role": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "The role to update. Pass the role ID (`role_...`) or its current name.\n"
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 512,
"description": "New description for the role.\nOmit this field to keep the current description. Send null or an empty string to remove it.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Attach a custom domain to a portal and start verifying it.
The domain is created in the `pending` state and does not serve the portal until
verification succeeds. The response returns `dnsRecords`: create every entry exactly as
given. Verification runs in the background; poll `portal.getDomain` for the result.
A name already attached to one of your portals or environments returns a 409.
Requires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/*#write`.
Use `portals/*/domains/*#write` to attach domains to any portal in the project.
Without the permission this returns **404**, not 403, unless the key can read
the portal or its domains.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Fully qualified domain name to attach to the portal, without a scheme, port, or path.
Must be unique across your workspace: a name already attached to a portal or to an
environment cannot be attached again.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_create_domain",
"title": "Create portal domain",
"description": "Attach a custom domain to a portal and start verifying it.\n\nThe domain is created in the `pending` state and does not serve the portal until\nverification succeeds. The response returns `dnsRecords`: create every entry exactly as\ngiven. Verification runs in the background; poll `portal.getDomain` for the result.\n\nA name already attached to one of your portals or environments returns a 409.\n\nRequires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/*#write`.\nUse `portals/*/domains/*#write` to attach domains to any portal in the project.\nWithout the permission this returns **404**, not 403, unless the key can read\nthe portal or its domains.\n",
"inputSchema": {
"type": "object",
"required": [
"portal",
"domain"
],
"properties": {
"domain": {
"type": "string",
"maxLength": 253,
"minLength": 4,
"description": "Fully qualified domain name to attach to the portal, without a scheme, port, or path.\nMust be unique across your workspace: a name already attached to a portal or to an\nenvironment cannot be attached again.\n"
},
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Create a portal for one app or keyspace in your workspace.
Unreleased and subject to change without notice.
Send exactly one of `keyspaceId` or `appId`. That resource must belong to your
workspace, and it can back only one portal, so a second portal for the same
resource is a **409**.
`displayName` is what your end users see. It is yours to set and change
independently of the resource the portal serves.
**Required Permissions**
Your root key must have `unkey:v1:<workspace_id>:projects/<project_id>/portals/*#write`
for the project that owns the app or keyspace. A grant scoped to a specific
portal ID does not authorize creation, because the ID does not exist yet.
You must also have read permission on the resource the portal serves:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>#read` for an app.
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>#read` for a keyspace.
Broader grants that cover these resources and actions also authorize the request.
A missing permission returns **403**. An app or keyspace outside your workspace
returns **404**, the same as a resource that does not exist.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
appId
The id of the app this portal serves keys for. Must belong to your workspace.
A portal serves exactly one resource, so `appId` and `keyspaceId` are mutually
exclusive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
displayName
Human-readable name your end users see in the portal header and page
titles. Unlike `slug` it is not part of any URL, so it can be changed
freely.
Clear enough to supply this argument.
enabled
Whether sessions can be minted for this portal immediately. Defaults to
true; send false to create it dormant and enable it later.
Clear enough to supply this argument.
keyspaceId
The id of the keyspace this portal serves keys for. Must belong to your
workspace.
A portal serves exactly one resource, so `keyspaceId` and `appId` are
mutually exclusive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
logoUrl
Absolute `https://` URL of the logo shown in the portal header.
Loaded by your end users' browsers, so the host you name receives their IP
and user agent on every page view.
Clear enough to supply this argument.
primaryColor
Six-digit hex colour used for primary actions and accents in the portal.
Clear enough to supply this argument.
slug
URL-safe handle for this portal, unique within your workspace. Lowercase
alphanumerics and single hyphens, 3-64 characters, not starting or ending
with a hyphen.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_create_portal",
"title": "Create portal",
"description": "Create a portal for one app or keyspace in your workspace.\n\nUnreleased and subject to change without notice.\n\nSend exactly one of `keyspaceId` or `appId`. That resource must belong to your\nworkspace, and it can back only one portal, so a second portal for the same\nresource is a **409**.\n\n`displayName` is what your end users see. It is yours to set and change\nindependently of the resource the portal serves.\n\n**Required Permissions**\n\nYour root key must have `unkey:v1:<workspace_id>:projects/<project_id>/portals/*#write`\nfor the project that owns the app or keyspace. A grant scoped to a specific\nportal ID does not authorize creation, because the ID does not exist yet.\n\nYou must also have read permission on the resource the portal serves:\n\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>#read` for an app.\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>#read` for a keyspace.\n\nBroader grants that cover these resources and actions also authorize the request.\nA missing permission returns **403**. An app or keyspace outside your workspace\nreturns **404**, the same as a resource that does not exist.\n",
"inputSchema": {
"type": "object",
"oneOf": [
{
"required": [
"keyspaceId"
]
},
{
"required": [
"appId"
]
}
],
"required": [
"slug",
"displayName"
],
"properties": {
"slug": {
"type": "string",
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
"maxLength": 64,
"minLength": 3,
"description": "URL-safe handle for this portal, unique within your workspace. Lowercase\nalphanumerics and single hyphens, 3-64 characters, not starting or ending\nwith a hyphen.\n"
},
"appId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 1,
"description": "The id of the app this portal serves keys for. Must belong to your workspace.\n\nA portal serves exactly one resource, so `appId` and `keyspaceId` are mutually\nexclusive.\n"
},
"enabled": {
"type": "boolean",
"default": true,
"description": "Whether sessions can be minted for this portal immediately. Defaults to\ntrue; send false to create it dormant and enable it later.\n"
},
"logoUrl": {
"type": "string",
"format": "uri",
"pattern": "^https://",
"maxLength": 500,
"minLength": 1,
"description": "Absolute `https://` URL of the logo shown in the portal header.\n\nLoaded by your end users' browsers, so the host you name receives their IP\nand user agent on every page view.\n"
},
"keyspaceId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 1,
"description": "The id of the keyspace this portal serves keys for. Must belong to your\nworkspace.\n\nA portal serves exactly one resource, so `keyspaceId` and `appId` are\nmutually exclusive.\n"
},
"displayName": {
"type": "string",
"pattern": "^\\S(.*\\S)?$",
"maxLength": 64,
"minLength": 1,
"description": "Human-readable name your end users see in the portal header and page\ntitles. Unlike `slug` it is not part of any URL, so it can be changed\nfreely.\n"
},
"primaryColor": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "Six-digit hex colour used for primary actions and accents in the portal.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Create a portal session for an end user and get the URL to redirect them to.
The URL carries a single-use exchange code valid for 15 minutes, which the portal
redeems exactly once for a 24-hour access token via `portal.exchangeCode`.
**Required Permissions**
Authorization runs in two stages, and both must pass.
First, your root key must have
`unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/sessions/*#write`.
Write permission on the portal itself does not grant permission to mint sessions.
Second, a session can never carry a capability your root key does not itself
hold. Each requested scope additionally requires the equivalent permission on
every keyspace the portal resolves to:
- `keys:read` requires `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#read`
and `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>#read`.
- `keys:reroll` requires `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write`,
including when the keyspace stores encrypted keys.
- `keys:create` requires `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write`,
the same permission creating a key with `keys.createKey` requires.
- `analytics:read` requires `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/logs#read`.
Broader URN grants that cover these resources and actions are also accepted.
A grant on one concrete key cannot satisfy the `keys/*` requirement.
Requesting a scope you do not hold
returns 403 for the whole request rather than minting a reduced session, so a
missing grant is visible instead of surfacing later as a broken portal.
Missing the portal permission itself returns **404** when your root key
cannot read the portal or its sessions, so a caller who cannot see a portal
is not told whether it exists. A root key that can read the portal but lacks
the permission gets **403**.
Your root key must also be associated with a workspace that has an enabled portal.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
externalId
The end user's identifier in the customer's system.
Accepts arbitrary string values (user IDs, emails, UUIDs, etc.).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
hostname
A verified custom domain of this portal to build the session URL on, so
end users stay on your domain. The domain must be verified on this
portal; any other value is rejected.
When omitted, the URL uses Unkey's portal host.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyCreation › maxKeys
The most live keys the end user may hold in the keyspace. Keys you issue
to the end user outside the portal count toward it. Disabled keys count;
expired and deleted keys do not.
Clear enough to supply this argument.
keyCreation › maxLifetime
The longest a created key may live, in milliseconds. At least one hour
and at most ten years. When omitted, the end user may create keys that
never expire.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyCreation › permissions › allowed
Permission slugs the end user may opt into.
Clear enough to supply this argument.
keyCreation › permissions › required
Permission slugs attached to every created key.
Clear enough to supply this argument.
keyCreation › ratelimits › items › autoApply
Whether the rate limit applies to every verification of the key automatically.
Explain what happens when this optional value is omitted.
keyCreation › ratelimits › items › duration
The window length, in milliseconds.
Clear enough to supply this argument.
keyCreation › ratelimits › items › limit
The most operations allowed per window.
Clear enough to supply this argument.
keyCreation › ratelimits › items › name
The name verifications use to check this rate limit.
Clear enough to supply this argument.
keyCreation › roles › allowed
Role names the end user may opt into.
Clear enough to supply this argument.
keyCreation › roles › required
Role names attached to every created key.
Clear enough to supply this argument.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
returnUrl
Absolute URL the end user is sent back to when they leave the portal, or
when their session expires mid-visit. Set per session rather than per
portal, so one portal can serve several entry points and return each user
to the page they came from.
When omitted, the portal shows no return link.
Clear enough to supply this argument.
scopes
The capabilities granted to the end user in the Portal, from a fixed
vocabulary. All capabilities are scoped to this end user: key capabilities
(`keys:*`) apply only to keys the end user owns within the keyspace
configured on the portal. An end user can never see another identity's
keys.
Rerolling, key creation, and usage analytics are all reached from the
keys page, so `keys:reroll`, `keys:create`, and `analytics:read` each
require `keys:read` in the same session; requesting any of them without it
is rejected.
`keys:create` lets the end user create keys for themselves, bounded by the
`keyCreation` policy, which it requires. It is not available on a portal
mapped to an app. Created keys never carry credits, so do not grant it if
you bill on credits. Created keys are ordinary keys in your keyspace: they
keep working after the session ends, until they expire or you revoke them.
Each scope requires the equivalent permission on your own root key. See
Required Permissions on this operation.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_create_session",
"title": "Create portal session",
"description": "Create a portal session for an end user and get the URL to redirect them to.\n\nThe URL carries a single-use exchange code valid for 15 minutes, which the portal\nredeems exactly once for a 24-hour access token via `portal.exchangeCode`.\n\n**Required Permissions**\n\nAuthorization runs in two stages, and both must pass.\n\nFirst, your root key must have\n`unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/sessions/*#write`.\nWrite permission on the portal itself does not grant permission to mint sessions.\n\nSecond, a session can never carry a capability your root key does not itself\nhold. Each requested scope additionally requires the equivalent permission on\nevery keyspace the portal resolves to:\n- `keys:read` requires `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#read`\n and `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>#read`.\n- `keys:reroll` requires `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write`,\n including when the keyspace stores encrypted keys.\n- `keys:create` requires `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write`,\n the same permission creating a key with `keys.createKey` requires.\n- `analytics:read` requires `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/logs#read`.\n\nBroader URN grants that cover these resources and actions are also accepted.\nA grant on one concrete key cannot satisfy the `keys/*` requirement.\nRequesting a scope you do not hold\nreturns 403 for the whole request rather than minting a reduced session, so a\nmissing grant is visible instead of surfacing later as a broken portal.\n\nMissing the portal permission itself returns **404** when your root key\ncannot read the portal or its sessions, so a caller who cannot see a portal\nis not told whether it exists. A root key that can read the portal but lacks\nthe permission gets **403**.\n\nYour root key must also be associated with a workspace that has an enabled portal.\n",
"inputSchema": {
"type": "object",
"required": [
"portal",
"externalId",
"scopes"
],
"properties": {
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"scopes": {
"type": "array",
"items": {
"enum": [
"keys:read",
"keys:reroll",
"keys:create",
"analytics:read"
],
"type": "string"
},
"minItems": 1,
"description": "The capabilities granted to the end user in the Portal, from a fixed\nvocabulary. All capabilities are scoped to this end user: key capabilities\n(`keys:*`) apply only to keys the end user owns within the keyspace\nconfigured on the portal. An end user can never see another identity's\nkeys.\n\nRerolling, key creation, and usage analytics are all reached from the\nkeys page, so `keys:reroll`, `keys:create`, and `analytics:read` each\nrequire `keys:read` in the same session; requesting any of them without it\nis rejected.\n\n`keys:create` lets the end user create keys for themselves, bounded by the\n`keyCreation` policy, which it requires. It is not available on a portal\nmapped to an app. Created keys never carry credits, so do not grant it if\nyou bill on credits. Created keys are ordinary keys in your keyspace: they\nkeep working after the session ends, until they expire or you revoke them.\n\nEach scope requires the equivalent permission on your own root key. See\nRequired Permissions on this operation.\n"
},
"hostname": {
"type": "string",
"maxLength": 255,
"description": "A verified custom domain of this portal to build the session URL on, so\nend users stay on your domain. The domain must be verified on this\nportal; any other value is rejected.\n\nWhen omitted, the URL uses Unkey's portal host.\n"
},
"returnUrl": {
"type": "string",
"format": "uri",
"maxLength": 500,
"description": "Absolute URL the end user is sent back to when they leave the portal, or\nwhen their session expires mid-visit. Set per session rather than per\nportal, so one portal can serve several entry points and return each user\nto the page they came from.\n\nWhen omitted, the portal shows no return link.\n"
},
"externalId": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "The end user's identifier in the customer's system.\nAccepts arbitrary string values (user IDs, emails, UUIDs, etc.).\n"
},
"keyCreation": {
"type": "object",
"required": [
"maxKeys"
],
"properties": {
"roles": {
"type": "object",
"properties": {
"allowed": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128,
"minLength": 1
},
"maxItems": 100,
"description": "Role names the end user may opt into."
},
"required": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128,
"minLength": 1
},
"maxItems": 100,
"description": "Role names attached to every created key."
}
},
"description": "Roles created keys must or may carry. Every role must already exist in the\nportal's project.\n",
"additionalProperties": false
},
"maxKeys": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "The most live keys the end user may hold in the keyspace. Keys you issue\nto the end user outside the portal count toward it. Disabled keys count;\nexpired and deleted keys do not.\n"
},
"ratelimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"limit",
"duration"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 3,
"description": "The name verifications use to check this rate limit."
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "The most operations allowed per window."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1000,
"description": "The window length, in milliseconds."
},
"autoApply": {
"type": "boolean",
"default": false,
"description": "Whether the rate limit applies to every verification of the key automatically."
}
},
"additionalProperties": false
},
"maxItems": 50,
"description": "Rate limits every created key receives. Names must be unique within the\npolicy. The end user may lower a limit or lengthen a duration when\ncreating a key, never the reverse.\n"
},
"maxLifetime": {
"type": "integer",
"format": "int64",
"maximum": 315360000000,
"minimum": 3600000,
"description": "The longest a created key may live, in milliseconds. At least one hour\nand at most ten years. When omitted, the end user may create keys that\nnever expire.\n"
},
"permissions": {
"type": "object",
"properties": {
"allowed": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1
},
"maxItems": 1000,
"description": "Permission slugs the end user may opt into."
},
"required": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
"maxLength": 128,
"minLength": 1
},
"maxItems": 1000,
"description": "Permission slugs attached to every created key."
}
},
"description": "Permissions created keys must or may carry. Every slug must already exist in\nthe portal's project.\n",
"additionalProperties": false
}
},
"description": "What the end user may create through the portal. Required with the\n`keys:create` scope and rejected without it. The policy is fixed for the\nsession's lifetime.\n\nCreated keys never carry credits, so do not grant `keys:create` if you bill\non credits.\n\nCreated keys are recoverable when the keyspace stores encrypted keys, and\nnot recoverable otherwise. This differs from `keys.createKey`, where\nrecoverability is opt-in per key.\n",
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Detach a custom domain from a portal. A verified domain stops serving the portal.
Requires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/<domain_id>#delete`.
Use `portals/<portal_id>/domains/*#delete` to delete any domain on the portal.
Without the permission this returns **404**, not 403, unless the key can read
the portal or the domain.
The description explains the capability, when to use it, and what to expect.
Inputs82/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domainId
The portal domain ID that `portal.createDomain` returned.
Clear enough to supply this argument.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_delete_domain",
"title": "Delete portal domain",
"description": "Detach a custom domain from a portal. A verified domain stops serving the portal.\n\nRequires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/<domain_id>#delete`.\nUse `portals/<portal_id>/domains/*#delete` to delete any domain on the portal.\nWithout the permission this returns **404**, not 403, unless the key can read\nthe portal or the domain.\n",
"inputSchema": {
"type": "object",
"required": [
"portal",
"domainId"
],
"properties": {
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"domainId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "The portal domain ID that `portal.createDomain` returned."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Delete a portal and revoke the sessions it minted.
Unreleased and subject to change without notice.
Its end users lose access rather than keeping it until their tokens expire.
Revocation is not instantaneous: session lookups are cached briefly, so a
request already in flight may still succeed.
The app or keyspace it served is untouched, and its slug becomes free for a
new portal.
Its custom domains are deleted with it: they stop serving and their DNS
records can be removed. Their certificates are not revoked.
**Required Permissions**
Your root key must have `delete` permission on
`unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>`.
A broader grant, such as `unkey:v1:<workspace_id>:**#delete`, also permits deletion.
A root key that cannot read the portal gets **404**. One that can read it
but lacks the permission gets **403**.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_delete_portal",
"title": "Delete portal",
"description": "Delete a portal and revoke the sessions it minted.\n\nUnreleased and subject to change without notice.\n\nIts end users lose access rather than keeping it until their tokens expire.\nRevocation is not instantaneous: session lookups are cached briefly, so a\nrequest already in flight may still succeed.\n\nThe app or keyspace it served is untouched, and its slug becomes free for a\nnew portal.\n\nIts custom domains are deleted with it: they stop serving and their DNS\nrecords can be removed. Their certificates are not revoked.\n\n**Required Permissions**\n\nYour root key must have `delete` permission on\n`unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>`.\nA broader grant, such as `unkey:v1:<workspace_id>:**#delete`, also permits deletion.\n\nA root key that cannot read the portal gets **404**. One that can read it\nbut lacks the permission gets **403**.\n",
"inputSchema": {
"type": "object",
"required": [
"portal"
],
"properties": {
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Read one custom domain attached to a portal, with its verification status and DNS records.
Requires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/<domain_id>#read`.
Use `portals/<portal_id>/domains/*#read` to read every domain on the portal.
Without the permission this returns **404**, not 403, unless the key can read
the portal itself.
The description explains the capability, when to use it, and what to expect.
Inputs87/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domainId
The portal domain ID that `portal.createDomain` returned.
Clear enough to supply this argument.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_get_domain",
"title": "Get portal domain",
"description": "Read one custom domain attached to a portal, with its verification status and DNS records.\n\nRequires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/<domain_id>#read`.\nUse `portals/<portal_id>/domains/*#read` to read every domain on the portal.\nWithout the permission this returns **404**, not 403, unless the key can read\nthe portal itself.\n",
"inputSchema": {
"type": "object",
"required": [
"portal",
"domainId"
],
"properties": {
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"domainId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "The portal domain ID that `portal.createDomain` returned."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description78/100
Read one portal, by its id or slug, or by the resource it serves.
Unreleased and subject to change without notice.
Send exactly one of `portal`, `keyspaceId`, or `appId`. Sending more than one
is a **400**.
**Required Permissions**
Your root key must have one of:
- `portal.*.read_portal` (to read any portal in the workspace)
- `portal.<portal_id>.read_portal` (to read a specific portal)
Without the permission this returns **404**, not 403.
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
appId
The id of the app this portal serves keys for. Must belong to your workspace.
A portal serves exactly one resource, so `appId` and `keyspaceId` are mutually
exclusive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyspaceId
The id of the keyspace this portal serves keys for. Must belong to your
workspace.
A portal serves exactly one resource, so `keyspaceId` and `appId` are
mutually exclusive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_get_portal",
"title": "Get portal",
"description": "Read one portal, by its id or slug, or by the resource it serves.\n\nUnreleased and subject to change without notice.\n\nSend exactly one of `portal`, `keyspaceId`, or `appId`. Sending more than one\nis a **400**.\n\n**Required Permissions**\n\nYour root key must have one of:\n- `portal.*.read_portal` (to read any portal in the workspace)\n- `portal.<portal_id>.read_portal` (to read a specific portal)\n\nWithout the permission this returns **404**, not 403.\n",
"inputSchema": {
"type": "object",
"oneOf": [
{
"required": [
"portal"
]
},
{
"required": [
"keyspaceId"
]
},
{
"required": [
"appId"
]
}
],
"properties": {
"appId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 1,
"description": "The id of the app this portal serves keys for. Must belong to your workspace.\n\nA portal serves exactly one resource, so `appId` and `keyspaceId` are mutually\nexclusive.\n"
},
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"keyspaceId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 1,
"description": "The id of the keyspace this portal serves keys for. Must belong to your\nworkspace.\n\nA portal serves exactly one resource, so `keyspaceId` and `appId` are\nmutually exclusive.\n"
}
},
"description": "Name the portal directly with `portal`, or name the resource it serves with\n`keyspaceId` or `appId`. Exactly one of the three is required; sending more\nthan one is a bad request.\n",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
List the custom domains attached to a portal, with their verification status and DNS records.
Requires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/*#read`.
Without the permission this returns **404**, not 403, unless the key can read
the portal itself.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_list_domains",
"title": "List portal domains",
"description": "List the custom domains attached to a portal, with their verification status and DNS records.\n\nRequires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/*#read`.\nWithout the permission this returns **404**, not 403, unless the key can read\nthe portal itself.\n",
"inputSchema": {
"type": "object",
"required": [
"portal"
],
"properties": {
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
List the end users holding a revocable session on a portal, with each
end user's sessions.
Unreleased and subject to change without notice.
A session is revocable until it expires or is revoked. That includes
sessions whose portal URL was created but not opened yet. Pass an end
user's `externalId` to `portal.revokeSession` to end their sessions.
**Required Permissions**
Your root key must have `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/sessions/*`
with `#read` or `#write`. Reading the portal itself is not enough.
Without the permission this returns **404**, not 403.
Describe the returned information so the agent knows whether it will answer the request.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response to fetch the next page.
Use when `hasMore: true` in the previous response.
Clear enough to supply this argument.
limit
Maximum number of end users to return per request.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Returns only end users whose `externalId` starts with this string.
Matching is case-sensitive, and `%` and `_` match literally.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_list_sessions",
"title": "List portal sessions",
"description": "List the end users holding a revocable session on a portal, with each\nend user's sessions.\n\nUnreleased and subject to change without notice.\n\nA session is revocable until it expires or is revoked. That includes\nsessions whose portal URL was created but not opened yet. Pass an end\nuser's `externalId` to `portal.revokeSession` to end their sessions.\n\n**Required Permissions**\n\nYour root key must have `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/sessions/*`\nwith `#read` or `#write`. Reading the portal itself is not enough.\n\nWithout the permission this returns **404**, not 403.\n",
"inputSchema": {
"type": "object",
"required": [
"portal"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of end users to return per request."
},
"cursor": {
"type": "string",
"description": "Pagination cursor from a previous response to fetch the next page.\nUse when `hasMore: true` in the previous response.\n"
},
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"search": {
"type": "string",
"maxLength": 256,
"description": "Returns only end users whose `externalId` starts with this string.\nMatching is case-sensitive, and `%` and `_` match literally.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Revoke every live session an end user holds on a portal.
Unreleased and subject to change without notice.
Sessions that were created but not yet opened are revoked too, so their
portal URLs stop working. Revocation is not instantaneous: session lookups
are cached briefly, so a request already in flight may still succeed.
Revoking ends existing sessions only. To keep the end user out, also stop
calling `portal.createSession` for them.
Calling this again for the same end user is safe and revokes nothing.
**Required Permissions**
Your root key must have
`unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/sessions/*#write`
or a broader grant that includes it. Dashboard roles can grant this permission.
Unlike `portal.createSession`, a dashboard session with this permission can
also call this endpoint.
A root key that cannot read the portal's sessions gets **404**. One that can
read them but lacks the permission gets **403**.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
externalId
The end user's identifier in your system, as passed to
`portal.createSession`. Every live session this end user holds on the
portal is revoked.
Clear enough to supply this argument.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_revoke_session",
"title": "Revoke portal sessions",
"description": "Revoke every live session an end user holds on a portal.\n\nUnreleased and subject to change without notice.\n\nSessions that were created but not yet opened are revoked too, so their\nportal URLs stop working. Revocation is not instantaneous: session lookups\nare cached briefly, so a request already in flight may still succeed.\n\nRevoking ends existing sessions only. To keep the end user out, also stop\ncalling `portal.createSession` for them.\n\nCalling this again for the same end user is safe and revokes nothing.\n\n**Required Permissions**\n\nYour root key must have\n`unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/sessions/*#write`\nor a broader grant that includes it. Dashboard roles can grant this permission.\nUnlike `portal.createSession`, a dashboard session with this permission can\nalso call this endpoint.\n\nA root key that cannot read the portal's sessions gets **404**. One that can\nread them but lacks the permission gets **403**.\n",
"inputSchema": {
"type": "object",
"required": [
"portal",
"externalId"
],
"properties": {
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"externalId": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "The end user's identifier in your system, as passed to\n`portal.createSession`. Every live session this end user holds on the\nportal is revoked.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Change a portal's slug, display name, the resource it serves, its enabled
state, or its branding.
Unreleased and subject to change without notice.
Only the fields you send change. Omitting a field leaves it as it is, and for
branding, sending null clears it. Send at most one of `keyspaceId` or `appId`.
Two changes affect your end users immediately:
- Re-pointing at a different resource revokes the portal's live sessions,
because a session carries the scope it was minted with.
- Disabling stops new sessions and revokes the live ones. Re-enabling does
not restore them.
**Required Permissions**
Your root key must have `write` permission on
`unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>`.
A broader grant, such as `unkey:v1:<workspace_id>:**#write`, also permits updates.
To change the mapped resource, your root key must also have `read` permission
on the target:
- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>#read`
for a keyspace.
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>#read` for an app.
A root key that cannot read the portal gets **404**. One that can read it
but lacks the permission gets **403**.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
appId
Re-point the portal at a different app. Omit to leave the resource it
serves alone.
Re-pointing revokes the portal's live sessions, for the same reason as
`keyspaceId`.
The same project restriction applies, and it is easy to hit when switching
between an app and a keyspace: keyspaces are created in the workspace's
default project, while an app belongs to the project you created it in.
Clear enough to supply this argument.
displayName
New human-readable name shown to your end users. Omit to leave unchanged.
Clear enough to supply this argument.
enabled
Whether new sessions can be minted. Omit to leave unchanged.
Disabling also revokes the portal's live sessions. Re-enabling does not
restore them.
Clear enough to supply this argument.
keyspaceId
Re-point the portal at a different keyspace. Omit to leave the resource it
serves alone.
Re-pointing revokes the portal's live sessions, because a session carries
the keyspace scope it was minted with and would otherwise keep reaching the
resource the portal no longer serves.
The new keyspace must belong to the same project as the portal's current
resource. A portal cannot move between projects, because its permissions
are addressed under the project it belongs to. Re-pointing across projects
returns 412; create a portal in the target project instead.
Clear enough to supply this argument.
logoUrl
Absolute `https://` URL of the portal logo. Omit to leave unchanged, or set
null to remove the logo.
Clear enough to supply this argument.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Clear enough to supply this argument.
primaryColor
Six-digit hex colour for primary actions. Omit to leave unchanged, or set
null to fall back to default styling.
Clear enough to supply this argument.
slug
New handle for this portal. Omit to leave unchanged.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_update_portal",
"title": "Update portal",
"description": "Change a portal's slug, display name, the resource it serves, its enabled\nstate, or its branding.\n\nUnreleased and subject to change without notice.\n\nOnly the fields you send change. Omitting a field leaves it as it is, and for\nbranding, sending null clears it. Send at most one of `keyspaceId` or `appId`.\n\nTwo changes affect your end users immediately:\n- Re-pointing at a different resource revokes the portal's live sessions,\n because a session carries the scope it was minted with.\n- Disabling stops new sessions and revokes the live ones. Re-enabling does\n not restore them.\n\n**Required Permissions**\n\nYour root key must have `write` permission on\n`unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>`.\nA broader grant, such as `unkey:v1:<workspace_id>:**#write`, also permits updates.\n\nTo change the mapped resource, your root key must also have `read` permission\non the target:\n- `unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>#read`\n for a keyspace.\n- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>#read` for an app.\n\nA root key that cannot read the portal gets **404**. One that can read it\nbut lacks the permission gets **403**.\n",
"inputSchema": {
"type": "object",
"required": [
"portal"
],
"properties": {
"slug": {
"type": "string",
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
"maxLength": 64,
"minLength": 3,
"description": "New handle for this portal. Omit to leave unchanged.\n"
},
"appId": {
"allOf": [
{
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 1,
"description": "The id of the app this portal serves keys for. Must belong to your workspace.\n\nA portal serves exactly one resource, so `appId` and `keyspaceId` are mutually\nexclusive.\n"
}
],
"description": "Re-point the portal at a different app. Omit to leave the resource it\nserves alone.\n\nRe-pointing revokes the portal's live sessions, for the same reason as\n`keyspaceId`.\n\nThe same project restriction applies, and it is easy to hit when switching\nbetween an app and a keyspace: keyspaces are created in the workspace's\ndefault project, while an app belongs to the project you created it in.\n"
},
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"enabled": {
"type": "boolean",
"description": "Whether new sessions can be minted. Omit to leave unchanged.\n\nDisabling also revokes the portal's live sessions. Re-enabling does not\nrestore them.\n"
},
"logoUrl": {
"type": [
"string",
"null"
],
"format": "uri",
"pattern": "^https://",
"maxLength": 500,
"minLength": 1,
"description": "Absolute `https://` URL of the portal logo. Omit to leave unchanged, or set\nnull to remove the logo.\n"
},
"keyspaceId": {
"allOf": [
{
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 1,
"description": "The id of the keyspace this portal serves keys for. Must belong to your\nworkspace.\n\nA portal serves exactly one resource, so `keyspaceId` and `appId` are\nmutually exclusive.\n"
}
],
"description": "Re-point the portal at a different keyspace. Omit to leave the resource it\nserves alone.\n\nRe-pointing revokes the portal's live sessions, because a session carries\nthe keyspace scope it was minted with and would otherwise keep reaching the\nresource the portal no longer serves.\n\nThe new keyspace must belong to the same project as the portal's current\nresource. A portal cannot move between projects, because its permissions\nare addressed under the project it belongs to. Re-pointing across projects\nreturns 412; create a portal in the target project instead.\n"
},
"displayName": {
"type": "string",
"pattern": "^\\S(.*\\S)?$",
"maxLength": 64,
"minLength": 1,
"description": "New human-readable name shown to your end users. Omit to leave unchanged.\n"
},
"primaryColor": {
"type": [
"string",
"null"
],
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "Six-digit hex colour for primary actions. Omit to leave unchanged, or set\nnull to fall back to default styling.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Shorten the title to an action and subject; move usage details into the description.
Description98/100
Restart verification for a portal domain.
Call this after you correct the DNS records of a domain that shows `failed`, or to give a
`pending` domain a new 24-hour verification period. The endpoint returns when Unkey accepts
the retry. Poll `portal.getDomain` for the result.
A domain that is already `verified` returns a 202 and starts nothing.
Requires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/<domain_id>#write`.
Use `portals/<portal_id>/domains/*#write` to manage every domain on the portal.
Without the permission this returns **404**, not 403, unless the key can read
the portal or the domain.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domainId
The portal domain ID that `portal.createDomain` returned.
Clear enough to supply this argument.
portal
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_portal_verify_domain",
"title": "Verify portal domain",
"description": "Restart verification for a portal domain.\n\nCall this after you correct the DNS records of a domain that shows `failed`, or to give a\n`pending` domain a new 24-hour verification period. The endpoint returns when Unkey accepts\nthe retry. Poll `portal.getDomain` for the result.\n\nA domain that is already `verified` returns a 202 and starts nothing.\n\nRequires `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/domains/<domain_id>#write`.\nUse `portals/<portal_id>/domains/*#write` to manage every domain on the portal.\nWithout the permission this returns **404**, not 403, unless the key can read\nthe portal or the domain.\n",
"inputSchema": {
"type": "object",
"required": [
"portal",
"domainId"
],
"properties": {
"portal": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"domainId": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 255,
"minLength": 3,
"description": "The portal domain ID that `portal.createDomain` returned."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Create a project to group deployments and applications under a workspace-scoped slug.
The slug you provide is the stable, caller-defined handle used to reference this project in subsequent operations (get, update, delete). It must be unique within your workspace.
**Important**: The slug cannot collide with an existing project in your workspace. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have the following permission:
- `project.*.create_project` (to create projects in your workspace)
The description explains the capability, when to use it, and what to expect.
Inputs34/100
Resolve the mismatch between this description and its schema constraints.
name
Human-readable name for this project.
Use a descriptive name like 'Payments Service' to identify its purpose.
Clear enough to supply this argument.
slug
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Resolve the mismatch between this description and its schema constraints.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_projects_create_project",
"title": "Create project",
"description": "Create a project to group deployments and applications under a workspace-scoped slug.\n\nThe slug you provide is the stable, caller-defined handle used to reference this project in subsequent operations (get, update, delete). It must be unique within your workspace.\n\n**Important**: The slug cannot collide with an existing project in your workspace. A duplicate slug returns a 409 conflict.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `project.*.create_project` (to create projects in your workspace)\n",
"inputSchema": {
"type": "object",
"required": [
"name",
"slug"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Human-readable name for this project.\nUse a descriptive name like 'Payments Service' to identify its purpose.\n"
},
"slug": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Delete an existing project in your workspace, identified by its id.
Deletion is asynchronous and eventually consistent. The project and all of its associated resources (apps, environments, deployments, custom domains) are torn down by a background workflow. A successful response indicates the deletion was enqueued, not that every resource has already been removed.
Projects with delete protection enabled cannot be deleted until protection is disabled.
**Required Permissions**
Your root key must have one of the following permissions:
- `unkey:v1:<workspace_id>:projects/*#delete` (to delete any project in the workspace)
- `unkey:v1:<workspace_id>:projects/<project_id>#delete` (to delete a specific project)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_projects_delete_project",
"title": "Delete project",
"description": "Delete an existing project in your workspace, identified by its id.\n\nDeletion is asynchronous and eventually consistent. The project and all of its associated resources (apps, environments, deployments, custom domains) are torn down by a background workflow. A successful response indicates the deletion was enqueued, not that every resource has already been removed.\n\nProjects with delete protection enabled cannot be deleted until protection is disabled.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `unkey:v1:<workspace_id>:projects/*#delete` (to delete any project in the workspace)\n- `unkey:v1:<workspace_id>:projects/<project_id>#delete` (to delete a specific project)\n",
"inputSchema": {
"type": "object",
"required": [
"project"
],
"properties": {
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Shorten the title to an action and subject; move usage details into the description.
Description84/100
Retrieve a single project in your workspace by its id.
Use this to fetch project details after creation, verify a project exists before performing operations, or resolve a project's metadata from its id.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.read_project` (to read any project)
- `project.<project_id>.read_project` (to read a specific project)
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_projects_get_project",
"title": "Get project",
"description": "Retrieve a single project in your workspace by its id.\n\nUse this to fetch project details after creation, verify a project exists before performing operations, or resolve a project's metadata from its id.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `project.*.read_project` (to read any project)\n- `project.<project_id>.read_project` (to read a specific project)\n",
"inputSchema": {
"type": "object",
"required": [
"project"
],
"properties": {
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Retrieve a paginated list of projects in your workspace.
Use this to build project management dashboards or to enumerate projects for administrative purposes. Results are ordered by project id and returned in pages. When `hasMore` is true, pass the returned `cursor` to fetch the next page.
**Required Permissions**
Your root key must have the following permission:
- `project.*.read_project` (to read projects in your workspace)
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response to fetch the next page.
Use when `hasMore: true` in the previous response.
Clear enough to supply this argument.
limit
Maximum number of projects to return per request.
Balance between response size and number of pagination calls needed.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Free-form text to filter projects. Returns projects whose ID, name, or slug contains the search string. Matching is case-insensitive.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_projects_list_projects",
"title": "List projects",
"description": "Retrieve a paginated list of projects in your workspace.\n\nUse this to build project management dashboards or to enumerate projects for administrative purposes. Results are ordered by project id and returned in pages. When `hasMore` is true, pass the returned `cursor` to fetch the next page.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `project.*.read_project` (to read projects in your workspace)\n",
"inputSchema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of projects to return per request.\nBalance between response size and number of pagination calls needed.\n"
},
"cursor": {
"type": "string",
"description": "Pagination cursor from a previous response to fetch the next page.\nUse when `hasMore: true` in the previous response.\n"
},
"search": {
"type": "string",
"maxLength": 256,
"description": "Free-form text to filter projects. Returns projects whose ID, name, or slug contains the search string. Matching is case-insensitive."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description82/100
Update an existing project in your workspace, identified by its id.
The project name, slug, and delete protection setting can be changed. Omitted fields are left unchanged. Changing the slug affects the deployment domains generated for this project.
**Required Permissions**
Your root key must have one of the following permissions:
- `unkey:v1:<workspace_id>:projects/*#write` (to update any project in the workspace)
- `unkey:v1:<workspace_id>:projects/<project_id>#write` (to update a specific project)
The description explains the capability, when to use it, and what to expect.
Inputs60/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
deleteProtection
Enable or disable delete protection for the project.
Omit this field to leave the current setting unchanged.
Clear enough to supply this argument.
name
New human-readable name for the project.
Omit this field to leave the current name unchanged.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
project
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
slug
Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_projects_update_project",
"title": "Update project",
"description": "Update an existing project in your workspace, identified by its id.\n\nThe project name, slug, and delete protection setting can be changed. Omitted fields are left unchanged. Changing the slug affects the deployment domains generated for this project.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `unkey:v1:<workspace_id>:projects/*#write` (to update any project in the workspace)\n- `unkey:v1:<workspace_id>:projects/<project_id>#write` (to update a specific project)\n",
"inputSchema": {
"type": "object",
"required": [
"project"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "New human-readable name for the project.\nOmit this field to leave the current name unchanged.\n"
},
"slug": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"project": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"maxLength": 255,
"minLength": 3,
"description": "Identifies a resource by either its unique ID or its slug.\nAccepts a prefixed ID (such as 'proj_' or 'app_') or a slug.\n"
},
"deleteProtection": {
"type": "boolean",
"description": "Enable or disable delete protection for the project.\nOmit this field to leave the current setting unchanged.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Create a rate limit namespace before you rate limit against it.
`ratelimit.limit` also creates a namespace the first time you use its name, when your root key can create namespaces. Use this endpoint when you want the namespace to exist up front, for example to set overrides before the first request.
**Important**: Names are unique within your workspace, deleted namespaces included. A name that is in use or was deleted returns 409.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#write`
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Input documentation gives an agent enough context to populate the arguments.
name
The name of the namespace, unique within your workspace. Names are case-sensitive.
Pass it as `namespace` to `ratelimit.limit` and the override endpoints.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_create_namespace",
"title": "Create ratelimit namespace",
"description": "Create a rate limit namespace before you rate limit against it.\n\n`ratelimit.limit` also creates a namespace the first time you use its name, when your root key can create namespaces. Use this endpoint when you want the namespace to exist up front, for example to set overrides before the first request.\n\n**Important**: Names are unique within your workspace, deleted namespaces included. A name that is in use or was deleted returns 409.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#write`\n",
"inputSchema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The name of the namespace, unique within your workspace. Names are case-sensitive.\nPass it as `namespace` to `ratelimit.limit` and the override endpoints.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Delete a rate limit namespace and all of its overrides, identified by the namespace ID or name.
**Important**: A deleted name cannot be reused. `ratelimit.limit` and `ratelimit.multiLimit` return 410 for it instead of creating a new namespace, so a deleted namespace does not turn into unlimited traffic. Other API nodes can take up to a minute to see the deletion.
**Required Permissions**
Your root key must have one of the following permissions:
- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#delete` (to delete any namespace)
- `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#delete` (to delete a specific namespace)
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Input documentation gives an agent enough context to populate the arguments.
namespace
The namespace to delete. Pass the namespace ID (`rlns_...`) or its name.
Clear enough to supply this argument.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_delete_namespace",
"title": "Delete ratelimit namespace",
"description": "Delete a rate limit namespace and all of its overrides, identified by the namespace ID or name.\n\n**Important**: A deleted name cannot be reused. `ratelimit.limit` and `ratelimit.multiLimit` return 410 for it instead of creating a new namespace, so a deleted namespace does not turn into unlimited traffic. Other API nodes can take up to a minute to see the deletion.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#delete` (to delete any namespace)\n- `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#delete` (to delete a specific namespace)\n",
"inputSchema": {
"type": "object",
"required": [
"namespace"
],
"properties": {
"namespace": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The namespace to delete. Pass the namespace ID (`rlns_...`) or its name.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
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 `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>/overrides/<override_id>#delete`, or a wildcard URN permission that includes this override and action. Without read access to the override, insufficient permissions return 404. With read access but no delete permission, the response is 403.
The description explains the capability, when to use it, and what to expect.
Inputs63/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
identifier
The exact identifier pattern of the override to delete. This must match exactly as it was specified when creating the override.
Important notes:
- This is case-sensitive and must match exactly
- Include any wildcards (*) that were part of the original pattern
- For example, if the override was created for 'premium_*', you must use 'premium_*' here, not a specific ID
After deletion, any identifiers previously affected by this override will immediately revert to using the default rate limit for the namespace.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
namespace
The id or name of the namespace containing the override.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_delete_override",
"title": "Delete ratelimit override",
"description": "Permanently remove a rate limit override. Affected identifiers immediately revert to the namespace default.\n\nUse this to remove temporary overrides, reset identifiers to standard limits, or clean up outdated rules.\n\n**Important:** Deletion is immediate and permanent. The override cannot be recovered and must be recreated if needed again.\n\n**Permissions:** Requires `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>/overrides/<override_id>#delete`, or a wildcard URN permission that includes this override and action. Without read access to the override, insufficient permissions return 404. With read access but no delete permission, the response is 403.\n",
"inputSchema": {
"type": "object",
"required": [
"namespace",
"identifier"
],
"properties": {
"namespace": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The id or name of the namespace containing the override."
},
"identifier": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The exact identifier pattern of the override to delete. This must match exactly as it was specified when creating the override.\n\nImportant notes:\n- This is case-sensitive and must match exactly\n- Include any wildcards (*) that were part of the original pattern\n- For example, if the override was created for 'premium_*', you must use 'premium_*' here, not a specific ID\n\nAfter deletion, any identifiers previously affected by this override will immediately revert to using the default rate limit for the namespace."
}
},
"description": "Deletes an existing rate limit override. This permanently removes a custom rate limit rule, reverting affected identifiers back to the default rate limits for the namespace.\n\nUse this endpoint when you need to:\n- Remove special rate limit rules that are no longer needed\n- Reset entities back to standard rate limits\n- Clean up temporary overrides\n- Remove outdated tiering or custom limit rules\n- Fix misconfigured overrides\n\nOnce deleted, the override cannot be recovered, and the operation takes effect immediately.",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
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`
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
identifier
The exact identifier pattern for the override you want to retrieve. This must match exactly as it was specified when creating the override.
Important notes:
- This is case-sensitive and must match exactly
- Include any wildcards (*) that were part of the original pattern
- For example, if the override was created for 'premium_*', you must use 'premium_*' here, not a specific ID like 'premium_user1'
This field is used to look up the specific override configuration for this pattern.
Clear enough to supply this argument.
namespace
The id or name of the namespace containing the override.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_get_override",
"title": "Get ratelimit override",
"description": "Retrieve the configuration of a specific rate limit override by its identifier.\n\nUse this to inspect override configurations, audit rate limiting policies, or debug rate limiting behavior.\n\n**Important:** The identifier must match exactly as specified when creating the override, including wildcard patterns.\n\n**Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`\n",
"inputSchema": {
"type": "object",
"required": [
"namespace",
"identifier"
],
"properties": {
"namespace": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The id or name of the namespace containing the override."
},
"identifier": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The exact identifier pattern for the override you want to retrieve. This must match exactly as it was specified when creating the override.\n\nImportant notes:\n- This is case-sensitive and must match exactly\n- Include any wildcards (*) that were part of the original pattern\n- For example, if the override was created for 'premium_*', you must use 'premium_*' here, not a specific ID like 'premium_user1'\n\nThis field is used to look up the specific override configuration for this pattern."
}
},
"description": "Gets the configuration of an existing rate limit override. Use this to retrieve details about custom rate limit rules that have been created for specific identifiers within a namespace.\n\nThis endpoint is useful for:\n- Verifying override configurations\n- Checking current limits for specific entities\n- Auditing rate limit policies\n- Debugging rate limiting behavior\n- Retrieving override settings for modification",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
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.
**Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded — check the `success` field in the response to determine if the request should be allowed. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
**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)
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Explain the meaning of this value, not just its name.
cost
Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting.
Use higher values for resource-intensive operations and 0 for tracking without limiting.
When accumulated cost exceeds the limit within the duration window, subsequent requests are rejected.
Essential for implementing fair usage policies and preventing resource abuse through expensive operations.
Clear enough to supply this argument.
duration
Sets the rate limit window duration in milliseconds after which the counter resets.
Shorter durations enable faster recovery but may be less effective against sustained abuse.
Common values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours).
Balance user experience with protection needs when choosing window sizes.
Clear enough to supply this argument.
identifier
Defines the scope of rate limiting by identifying the entity being limited.
Use user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits.
Accepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats.
The same identifier can be used across different namespaces to apply multiple rate limit types.
Choose identifiers that provide appropriate granularity for your rate limiting strategy.
Clear enough to supply this argument.
limit
Sets the maximum operations allowed within the duration window before requests are rejected.
When this limit is reached, subsequent requests fail with `RATE_LIMITED` until the window resets.
Balance user experience with resource protection when setting limits for different user tiers.
Consider system capacity, business requirements, and fair usage policies in limit determination.
Clear enough to supply this argument.
namespace
The id or name of the namespace.
Explain the meaning of this value, not just its name.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_limit",
"title": "Apply rate limiting",
"description": "Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.).\n\nUse 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.\n\n**Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded — check the `success` field in the response to determine if the request should be allowed. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `ratelimit.*.limit` (to check limits in any namespace)\n- `ratelimit.<namespace_id>.limit` (to check limits in a specific namespace)\n",
"inputSchema": {
"type": "object",
"required": [
"namespace",
"identifier",
"limit",
"duration"
],
"properties": {
"cost": {
"type": "integer",
"format": "int64",
"default": 1,
"minimum": 0,
"description": "Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting.\nUse higher values for resource-intensive operations and 0 for tracking without limiting.\nWhen accumulated cost exceeds the limit within the duration window, subsequent requests are rejected.\nEssential for implementing fair usage policies and preventing resource abuse through expensive operations.\n"
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Sets the maximum operations allowed within the duration window before requests are rejected.\nWhen this limit is reached, subsequent requests fail with `RATE_LIMITED` until the window resets.\nBalance user experience with resource protection when setting limits for different user tiers.\nConsider system capacity, business requirements, and fair usage policies in limit determination.\n"
},
"duration": {
"type": "integer",
"format": "int64",
"maximum": 2592000000,
"minimum": 1000,
"description": "Sets the rate limit window duration in milliseconds after which the counter resets.\nShorter durations enable faster recovery but may be less effective against sustained abuse.\nCommon values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours).\nBalance user experience with protection needs when choosing window sizes.\n"
},
"namespace": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The id or name of the namespace."
},
"identifier": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Defines the scope of rate limiting by identifying the entity being limited.\nUse user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits.\nAccepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats.\nThe same identifier can be used across different namespaces to apply multiple rate limit types.\nChoose identifiers that provide appropriate granularity for your rate limiting strategy.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Retrieve a paginated list of the rate limit namespaces in your workspace.
Use this to find the namespaces your services rate limit against, for example to build an admin view or to look up a namespace ID. Results are ordered newest first and returned in pages. When `hasMore` is true, pass the returned `cursor` to fetch the next page.
Deleted namespaces are not returned. The list contains only the namespaces your root key can read.
**Required Permissions**
Your root key must have one of the following permissions:
- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#read` (to read any namespace)
- `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#read` (to read a specific namespace)
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response to fetch the next page.
Use when `hasMore: true` in the previous response. Omit this field to start from the first page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of namespaces to return per request.
Omit this field to receive up to 100 namespaces.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Free-form text to filter namespaces. Returns namespaces whose ID or name contains the search string. Matching is case-insensitive.
Omit this field to list every namespace.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_list_namespaces",
"title": "List ratelimit namespaces",
"description": "Retrieve a paginated list of the rate limit namespaces in your workspace.\n\nUse this to find the namespaces your services rate limit against, for example to build an admin view or to look up a namespace ID. Results are ordered newest first and returned in pages. When `hasMore` is true, pass the returned `cursor` to fetch the next page.\n\nDeleted namespaces are not returned. The list contains only the namespaces your root key can read.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#read` (to read any namespace)\n- `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#read` (to read a specific namespace)\n",
"inputSchema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of namespaces to return per request.\nOmit this field to receive up to 100 namespaces.\n"
},
"cursor": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "Pagination cursor from a previous response to fetch the next page.\nUse when `hasMore: true` in the previous response. Omit this field to start from the first page.\n"
},
"search": {
"type": "string",
"maxLength": 256,
"description": "Free-form text to filter namespaces. Returns namespaces whose ID or name contains the search string. Matching is case-insensitive.\nOmit this field to list every namespace.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
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`
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Pagination cursor from a previous response. Include this when fetching subsequent pages of results. Each response containing more results than the requested limit will include a cursor value in the pagination object that can be used here.
Clear enough to supply this argument.
limit
Maximum number of override entries to return in a single response. Use this to control response size and loading performance.
- Lower values (10-20): Better for UI displays and faster response times
- Higher values (50-100): Better for data exports or bulk operations
- Default (10): Suitable for most dashboard views
Results exceeding this limit will be paginated, with a cursor provided for fetching subsequent pages.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
namespace
The id or name of the rate limit namespace to list overrides for.
Clear enough to supply this argument.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_list_overrides",
"title": "List ratelimit overrides",
"description": "Retrieve a paginated list of all rate limit overrides in a namespace.\n\nUse this to audit rate limiting policies, build admin dashboards, or manage override configurations.\n\n**Important:** Results are paginated. Use the cursor parameter to retrieve additional pages when more results are available.\n\n**Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`\n",
"inputSchema": {
"type": "object",
"required": [
"namespace"
],
"properties": {
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of override entries to return in a single response. Use this to control response size and loading performance.\n\n- Lower values (10-20): Better for UI displays and faster response times\n- Higher values (50-100): Better for data exports or bulk operations\n- Default (10): Suitable for most dashboard views\n\nResults exceeding this limit will be paginated, with a cursor provided for fetching subsequent pages."
},
"cursor": {
"type": "string",
"description": "Pagination cursor from a previous response. Include this when fetching subsequent pages of results. Each response containing more results than the requested limit will include a cursor value in the pagination object that can be used here."
},
"namespace": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The id or name of the rate limit namespace to list overrides for."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.).
Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level `passed` indicator showing if all checks succeeded.
**Response Codes**: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the `passed` field to see if all limits passed, or the `success` field in each individual result. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
**Required Permissions**
Your root key must have `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#limit` for every namespace in the request. Use `*` for the namespace ID to cover all namespaces in a project.
To create missing namespaces automatically, your root key must also have `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/*#write` for the workspace's default project. The `#limit` permission must cover each created namespace.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
body › items › cost
Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting.
Use higher values for resource-intensive operations and 0 for tracking without limiting.
When accumulated cost exceeds the limit within the duration window, subsequent requests are rejected.
Essential for implementing fair usage policies and preventing resource abuse through expensive operations.
Clear enough to supply this argument.
body › items › duration
Sets the rate limit window duration in milliseconds after which the counter resets.
Shorter durations enable faster recovery but may be less effective against sustained abuse.
Common values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours).
Balance user experience with protection needs when choosing window sizes.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
body › items › identifier
Defines the scope of rate limiting by identifying the entity being limited.
Use user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits.
Accepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats.
The same identifier can be used across different namespaces to apply multiple rate limit types.
Choose identifiers that provide appropriate granularity for your rate limiting strategy.
Clear enough to supply this argument.
body › items › limit
Sets the maximum operations allowed within the duration window before requests are rejected.
When this limit is reached, subsequent requests fail with `RATE_LIMITED` until the window resets.
Balance user experience with resource protection when setting limits for different user tiers.
Consider system capacity, business requirements, and fair usage policies in limit determination.
Clear enough to supply this argument.
body › items › namespace
The id or name of the namespace.
Explain the meaning of this value, not just its name.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_multi_limit",
"title": "Apply multiple rate limit checks",
"description": "Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.).\n\nUse this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level `passed` indicator showing if all checks succeeded.\n\n**Response Codes**: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the `passed` field to see if all limits passed, or the `success` field in each individual result. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.\n\n**Required Permissions**\n\nYour root key must have `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#limit` for every namespace in the request. Use `*` for the namespace ID to cover all namespaces in a project.\n\nTo create missing namespaces automatically, your root key must also have `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/*#write` for the workspace's default project. The `#limit` permission must cover each created namespace.\n",
"inputSchema": {
"type": "object",
"required": [
"body"
],
"properties": {
"body": {
"type": "array",
"items": {
"type": "object",
"required": [
"namespace",
"identifier",
"limit",
"duration"
],
"properties": {
"cost": {
"type": "integer",
"format": "int64",
"default": 1,
"minimum": 0,
"description": "Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting.\nUse higher values for resource-intensive operations and 0 for tracking without limiting.\nWhen accumulated cost exceeds the limit within the duration window, subsequent requests are rejected.\nEssential for implementing fair usage policies and preventing resource abuse through expensive operations.\n"
},
"limit": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Sets the maximum operations allowed within the duration window before requests are rejected.\nWhen this limit is reached, subsequent requests fail with `RATE_LIMITED` until the window resets.\nBalance user experience with resource protection when setting limits for different user tiers.\nConsider system capacity, business requirements, and fair usage policies in limit determination.\n"
},
"duration": {
"type": "integer",
"format": "int64",
"maximum": 2592000000,
"minimum": 1000,
"description": "Sets the rate limit window duration in milliseconds after which the counter resets.\nShorter durations enable faster recovery but may be less effective against sustained abuse.\nCommon values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours).\nBalance user experience with protection needs when choosing window sizes.\n"
},
"namespace": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The id or name of the namespace."
},
"identifier": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Defines the scope of rate limiting by identifying the entity being limited.\nUse user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits.\nAccepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats.\nThe same identifier can be used across different namespaces to apply multiple rate limit types.\nChoose identifiers that provide appropriate granularity for your rate limiting strategy.\n"
}
},
"additionalProperties": false
},
"maxItems": 100,
"minItems": 1,
"description": "Array of rate limit checks to perform. Each check must have a different combination of namespace, identifier and duration. A repeated combination returns a 400 error with `invalid_input` before any namespace is created."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
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 `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>/overrides/*#write` to create overrides. To update an override, you can replace `*` with its override ID.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
duration
The duration in milliseconds for the rate limit window. This defines how long the rate limit counter accumulates before resetting to zero.
Considerations:
- This can differ from the default duration for the namespace
- Longer durations create stricter limits that take longer to reset
- Shorter durations allow more frequent bursts of activity
- Common values: 60000 (1 minute), 3600000 (1 hour), 86400000 (1 day)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
identifier
Identifier of the entity receiving this custom rate limit. This can be:
- A specific user ID for individual custom limits
- An IP address for location-based rules
- An email domain for organization-wide policies
- Any other string that identifies the target entity
Wildcards (*) can be used to create pattern-matching rules that apply to multiple identifiers. For example:
- 'premium_*' would match all identifiers starting with 'premium_'
- '*_admin' would match all identifiers ending with '_admin'
- '*suspicious*' would match any identifier containing 'suspicious'
More detailed information on wildcard pattern rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
The maximum number of requests allowed for this override. This defines the custom quota for the specified identifier(s).
Special values:
- Higher than default: For premium or trusted entities
- Lower than default: For suspicious or abusive entities
- 0: To completely block access (useful for ban implementation)
This limit entirely replaces the default limit for matching identifiers.
Clear enough to supply this argument.
namespace
The ID or name of the rate limit namespace.
Explain the meaning of this value, not just its name.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_set_override",
"title": "Set ratelimit override",
"description": "Create or update a custom rate limit for specific identifiers, bypassing the namespace default.\n\nUse this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling.\n\n**Important:** Overrides take effect immediately and completely replace the default limit for matching identifiers. Use wildcard patterns (e.g., `premium_*`) to match multiple identifiers.\n\n**Permissions:** Requires `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>/overrides/*#write` to create overrides. To update an override, you can replace `*` with its override ID.\n",
"inputSchema": {
"type": "object",
"required": [
"namespace",
"identifier",
"limit",
"duration"
],
"properties": {
"limit": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The maximum number of requests allowed for this override. This defines the custom quota for the specified identifier(s).\n\nSpecial values:\n- Higher than default: For premium or trusted entities\n- Lower than default: For suspicious or abusive entities\n- 0: To completely block access (useful for ban implementation)\n\nThis limit entirely replaces the default limit for matching identifiers."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 1000,
"description": "The duration in milliseconds for the rate limit window. This defines how long the rate limit counter accumulates before resetting to zero.\n\nConsiderations:\n- This can differ from the default duration for the namespace\n- Longer durations create stricter limits that take longer to reset\n- Shorter durations allow more frequent bursts of activity\n- Common values: 60000 (1 minute), 3600000 (1 hour), 86400000 (1 day)"
},
"namespace": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The ID or name of the rate limit namespace."
},
"identifier": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Identifier of the entity receiving this custom rate limit. This can be:\n\n- A specific user ID for individual custom limits\n- An IP address for location-based rules\n- An email domain for organization-wide policies\n- Any other string that identifies the target entity\n\nWildcards (*) can be used to create pattern-matching rules that apply to multiple identifiers. For example:\n- 'premium_*' would match all identifiers starting with 'premium_'\n- '*_admin' would match all identifiers ending with '_admin'\n- '*suspicious*' would match any identifier containing 'suspicious'\n\nMore detailed information on wildcard pattern rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules"
}
},
"description": "Sets a new or overwrites an existing rate limit override. Overrides allow you to apply special rate limit rules to specific identifiers, providing custom limits that differ from the default.\n\nOverrides are useful for:\n- Granting higher limits to premium users or trusted partners\n- Implementing stricter limits for suspicious or abusive users\n- Creating tiered access levels with different quotas\n- Implementing temporary rate limit adjustments\n- Prioritizing important clients with higher limits",
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Rename a rate limit namespace, identified by its ID or current name.
Renaming to the current name returns the namespace without a write.
**Important**: Overrides stay with the namespace. Requests that pass the namespace by name, such as `ratelimit.limit`, must use the new name. A `ratelimit.limit` call with the old name can create a new, empty namespace with that name. A name that is in use or was deleted returns 409. Other API nodes can take up to a minute to see the new name.
**Required Permissions**
Your root key must have one of the following permissions:
- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#write` (to rename any namespace)
- `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#write` (to rename a specific namespace)
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
The new name of the namespace, unique within your workspace. Names are case-sensitive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
namespace
The namespace to rename. Pass the namespace ID (`rlns_...`) or its current name.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_ratelimit_update_namespace",
"title": "Update ratelimit namespace",
"description": "Rename a rate limit namespace, identified by its ID or current name.\n\nRenaming to the current name returns the namespace without a write.\n\n**Important**: Overrides stay with the namespace. Requests that pass the namespace by name, such as `ratelimit.limit`, must use the new name. A `ratelimit.limit` call with the old name can create a new, empty namespace with that name. A name that is in use or was deleted returns 409. Other API nodes can take up to a minute to see the new name.\n\n**Required Permissions**\n\nYour root key must have one of the following permissions:\n- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#write` (to rename any namespace)\n- `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#write` (to rename a specific namespace)\n",
"inputSchema": {
"type": "object",
"required": [
"namespace",
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The new name of the namespace, unique within your workspace. Names are case-sensitive.\n"
},
"namespace": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "The namespace to rename. Pass the namespace ID (`rlns_...`) or its current name.\n"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Get feature flags for the workspace associated with your credentials.
Each flag is keyed by its slug and includes its current value, description,
and whether it can be enabled or disabled. A workspace-specific value takes
precedence over the flag's default. If no flags are available, `data` is an
empty object.
This endpoint takes no request body.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:flags#read`
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
No input fields.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_workspace_get_flags",
"title": "Get workspace flags",
"description": "Get feature flags for the workspace associated with your credentials.\n\nEach flag is keyed by its slug and includes its current value, description,\nand whether it can be enabled or disabled. A workspace-specific value takes\nprecedence over the flag's default. If no flags are available, `data` is an\nempty object.\n\nThis endpoint takes no request body.\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:flags#read`\n",
"inputSchema": {
"type": "object"
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Get every limit of your workspace, with the current value against each
limit that has one.
Use this before an operation that a limit can reject, for example to see how
many custom domains or log drains remain, or how much CPU, memory, and disk
a new deployment can still reserve.
The request takes no parameters. Each limit has a `limit`, which is `null`
when unlimited, and a `current` value when the limit has one. Billable
operations count the current calendar month in UTC. The Compute limits are
present only when the workspace has a Compute plan.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:limits#read`
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
No input fields.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_workspace_get_limits",
"title": "Get workspace limits",
"description": "Get every limit of your workspace, with the current value against each\nlimit that has one.\n\nUse this before an operation that a limit can reject, for example to see how\nmany custom domains or log drains remain, or how much CPU, memory, and disk\na new deployment can still reserve.\n\nThe request takes no parameters. Each limit has a `limit`, which is `null`\nwhen unlimited, and a `current` value when the limit has one. Billable\noperations count the current calendar month in UTC. The Compute limits are\npresent only when the workspace has a Compute plan.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:limits#read`\n",
"inputSchema": {
"type": "object"
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Get the usage of your workspace for one calendar month (UTC): billable API
operations, compute usage per environment, and active keys per app.
Use this to track usage during the month or to look back at a past
month. The response has no prices. Your invoice is the source of truth.
Compute usage can be up to 15 minutes late, and it can change for up to 7
days.
Send `{}` for the current month to date, or
`{"period": {"year": 2026, "month": 9}}` for a full past month. The month
must start within the last 90 days.
**Required Permissions**
Your root key must have this permission:
- `unkey:v1:<workspace_id>:usage#read`
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
period › month
The month, from 1 (January) to 12 (December).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
period › year
The year, for example 2026.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations50/100
Declare destructiveHint, openWorldHint based on the tool’s actual behavior.
{
"readOnlyHint": true,
"idempotentHint": false
}
Output schema0/100
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_workspace_get_usage",
"title": "Get workspace usage",
"description": "Get the usage of your workspace for one calendar month (UTC): billable API\noperations, compute usage per environment, and active keys per app.\n\nUse this to track usage during the month or to look back at a past\nmonth. The response has no prices. Your invoice is the source of truth.\nCompute usage can be up to 15 minutes late, and it can change for up to 7\ndays.\n\nSend `{}` for the current month to date, or\n`{\"period\": {\"year\": 2026, \"month\": 9}}` for a full past month. The month\nmust start within the last 90 days.\n\n**Required Permissions**\n\nYour root key must have this permission:\n- `unkey:v1:<workspace_id>:usage#read`\n",
"inputSchema": {
"type": "object",
"properties": {
"period": {
"type": "object",
"required": [
"year",
"month"
],
"properties": {
"year": {
"type": "integer",
"description": "The year, for example 2026."
},
"month": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "The month, from 1 (January) to 12 (December)."
}
},
"description": "The calendar month (UTC) to read. Omit it for the current month to date. A\npast month returns the full month. It cannot be in the future, and it must\nstart within the last 90 days, because compute usage is kept for 90 days.\n",
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"idempotentHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description75/100
Enable or disable a flag for your workspace. Use `workspace.getFlags` to
find flag slugs and check whether they can be enabled or disabled.
**Required Permissions**
Your root key must have the following permission:
- `unkey:v1:<workspace_id>:flags#write`
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
enabled
Set to true to enable the flag or false to disable it, regardless of the flag's default.
Clear enough to supply this argument.
slug
Lowercase snake_case slug of the flag to update, as returned by `workspace.getFlags`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare openWorldHint based on the tool’s actual behavior.
No output schema is declared. Add one for structured results so clients can interpret returned fields.
Not declared
Original tool metadata
{
"name": "unkey_v2_workspace_update_flag",
"title": "Update a workspace flag",
"description": "Enable or disable a flag for your workspace. Use `workspace.getFlags` to\nfind flag slugs and check whether they can be enabled or disabled.\n\n**Required Permissions**\n\nYour root key must have the following permission:\n- `unkey:v1:<workspace_id>:flags#write`\n",
"inputSchema": {
"type": "object",
"required": [
"slug",
"enabled"
],
"properties": {
"slug": {
"type": "string",
"pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
"maxLength": 128,
"minLength": 1,
"description": "Lowercase snake_case slug of the flag to update, as returned by `workspace.getFlags`."
},
"enabled": {
"type": "boolean",
"description": "Set to true to enable the flag or false to disable it, regardless of the flag's default."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}
Loading score analytics…
Put your MCP to the test
A few tasks worth trying with this server, chosen from its reviewed tools. These have not been run.
01List projectsRetrieve a paginated list of projects in your workspace.
02Get workspace limitsGet every limit of your workspace, with the current value against each
03List domainsList your custom domains with their verification status and DNS records.
04Get workspace flagsGet feature flags for the workspace associated with your credentials.
05List API requestsList the requests that the Unkey API served for your workspace, newest first.
Want to run these tasks against your MCP server with us?
Unkey setup, tools, quality score, publishing readiness, and alternatives.
How do I add Unkey to Claude, ChatGPT, or Cursor?
Add Unkey to Claude, ChatGPT, or Cursor by connecting its remote MCP URL in each client's MCP settings. In Claude, add a custom connector. In ChatGPT, add an MCP app. In Cursor, add an MCP server under Settings. The MCP URL is https://mcp.unkey.com/.
Is Unkey MCP ready for ChatGPT and Claude?
As of November 21, 2026, Unkey scores 94/100 on Manufact's MCP publishing checklist. The scan does not yet meet ChatGPT publishing checks and meets Claude publishing checks. Passing these checks does not guarantee marketplace approval.
How clear is Unkey's MCP tool documentation?
As of November 21, 2026, Unkey scores 77/100 in Manufact's review of tool titles, descriptions, input and output schemas, and behavior annotations. The review covers 102 of 102 discovered tools. The quality score measures documentation clarity; runtime behavior and marketplace readiness require separate checks.
What are the best alternatives to Unkey?
As of November 21, 2026, alternatives to Unkey in developer-tools on the Manufact MCP leaderboard include Speko, Manufact, AgentMail, Context, and AgentPhone.
How can Unkey improve its MCP documentation?
unkey_v2_permissions_get_role is the lowest-scoring reviewed tool at 52/100. Resolve the mismatch between this description and its schema constraints. Open its review for feedback and a copyable fix prompt, then rerun the documentation review after updating your tool metadata.
Not your MCP?
Review any public or OAuth MCP server for protocol compatibility, tool documentation, and ChatGPT and Claude publishing readiness. No account required.