Skip to content
ApiqDevelopers
API v1.64.0Open console
API referenceidentity

Pause api key

POST/v1/keys/{keyPrefix}:pause
Accepts bearer

Pause an API key by hand, with a reason

An Owner or Admin pauses a key by hand with a reason (1 to 500 characters, audited).Show moreAn Owner or Admin pauses a key by hand with a reason (1 to 500 characters, audited). From the next request every call with the key is 423 PERMISSION_DENIED details.reason KEY_PAUSED, nextAction stop (components/responses/KeyPaused); holds and orders already made are untouched and holds expire on their TTL. The key's state is PAUSED (status stays ACTIVE), pausedReason is the reason and pausedEvidence carries rule MANUAL. Emits key.paused (webhook and notification). Human session only (an API key is 403 PERMISSION_DENIED details.reason ACCESS_TOKEN_REQUIRED, as every /v1/keys route); Owner or Admin, else 403 PERMISSION_DENIED details.reason OWNER_OR_ADMIN_ONLY. A key that is not ACTIVE (already PAUSED, REVOKED or EXPIRED) is 409 CONFLICT details.reason KEY_NOT_ACTIVE. MCP: excluded, never a tool.

Path parameters

  • keyPrefixstringRequired

Request bodyApiKeyStateChange

  • reasonstringRequired
  • categorystringOptional
    false_positive | fixed | limits_changed | other (x-extensible-enum); a resume within 10 minutes with false_positive feeds the false-positive pause metric

Responses

  • 200The key in its new stateApiKeyMetadata
  • 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
  • 401
    UNAUTHENTICATED — missing or expired token.Show moreUNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
    ApiErrorResponse
  • 403PERMISSION_DENIED — OWNER_OR_ADMIN_ONLY (a Member or Developer), or ACCESS_TOKEN_REQUIRED (an API key or a service token; an agent never pauses a key over REST or MCP)ApiErrorResponse
  • 404NOT_FOUND — unknown or expired ref (unguessable refs, 15)ApiErrorResponse
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 409CONFLICT KEY_NOT_ACTIVE — the key is already PAUSED, or REVOKED or EXPIREDApiErrorResponse
  • 413
    VALIDATION — the request body is larger than the surface's limit.Show moreVALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
    ApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 415
    VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show moreVALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501NOT_IMPLEMENTED AGENT_KEYS_UNAVAILABLE — scoped agent keys are off on this deploymentApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400VALIDATION
message.intent.checkOut must be after message.intent.checkIn
not retryable
400UNKNOWN_DOMAIN
Unknown domain 'HOTELS'. Did you mean HTL?
not retryable
401UNAUTHENTICATED
The bearer token is expired. Re-authenticate and retry.
not retryable
403PERMISSION_DENIED
Only an Owner or an Admin can pause a key.
not retryable
404NOT_FOUND
searchRef SR-F-7b31d0a9 is unknown or has expired; re-search
not retryable
405VALIDATION
This method is not served.
not retryable
409CONFLICT
This key is already paused.
not retryable
413VALIDATION
The request body is larger than this API accepts (262144 bytes).
not retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
415VALIDATION
Send application/json.
not retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
Scoped agent keys are not available on this deployment.
not retryable