pricklymails-com API Keys API
Create, list, update, and revoke API keys, and inspect the key in use.
Create, list, update, and revoke API keys, and inspect the key in use.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/pricklymails-com:pricklymails-com-api-keys-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Pricklymails Com API Keys API
version: 0.9.0
contact:
email: support@pricklymails.com
license:
name: Proprietary
description: 'Operations tagged api-keys across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: API Keys
description: Create, list, update, and revoke API keys, and inspect the key in use.
paths:
/api/keys:
get:
tags:
- API Keys
summary: Lists every API key owned by the authenticated user, newest first
operationId: list_api_keys
responses:
'200':
description: The caller's API keys, newest first.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiKeyResponse'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `api_keys:read` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
post:
tags:
- API Keys
summary: Creates an API key for the authenticated account and returns the full key in…
description: The full key is returned only by this call; every later read returns metadata only. The number of active keys is capped by the account's plan, and the plan also decides which checks may be enabled. The per-key rate limit is set from the plan and cannot be chosen in the request.
operationId: create_api_key
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyRequest'
required: true
responses:
'201':
description: Key created; `raw_key` is shown once.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyCreatedResponse'
'400':
description: Invalid name, environment, scopes, or checks.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: Plan key limit reached, a check is not allowed for the plan, or the key or agent token lacks the `api_keys:create` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
/api/keys/me:
get:
tags:
- API Keys
summary: Returns metadata about the API key that authenticated the request
description: Authenticate with the API key as a bearer token. Use it to confirm that a freshly issued key works before calling billable verification endpoints.
operationId: get_current_key
responses:
'200':
description: Metadata for the authenticating key.
content:
application/json:
schema:
$ref: '#/components/schemas/CurrentKeyResponse'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
/api/keys/{uuid}:
get:
tags:
- API Keys
summary: Returns a single API key owned by the authenticated user
operationId: get_api_key
parameters:
- name: uuid
in: path
description: Public UUID of the API key.
required: true
schema:
type: string
responses:
'200':
description: The requested API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'400':
description: Malformed uuid.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `api_keys:read` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'404':
description: No key with that uuid owned by the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
delete:
tags:
- API Keys
summary: Revokes an API key so it can no longer authenticate
description: 'Idempotent: revoking an already revoked key returns it unchanged, with its original `revoked_at`.'
operationId: revoke_api_key
parameters:
- name: uuid
in: path
description: Public UUID of the API key.
required: true
schema:
type: string
responses:
'200':
description: The revoked API key (idempotent on repeat calls).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'400':
description: Malformed uuid.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `api_keys:revoke` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'404':
description: No key with that uuid owned by the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
patch:
tags:
- API Keys
summary: Updates the display name and enabled checks of an API key
description: 'Omitted fields keep their current values. The rate limit cannot be edited: it follows the account''s plan and is realigned whenever the plan changes.'
operationId: update_api_key
parameters:
- name: uuid
in: path
description: Public UUID of the API key.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateApiKeyRequest'
required: true
responses:
'200':
description: The updated API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'400':
description: Invalid name or checks.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: A requested check is not allowed for the plan, or the agent token lacks the `api_keys:read` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'404':
description: No key with that uuid owned by the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
components:
schemas:
CurrentKeyResponse:
type: object
description: JSON response body for `GET /api/keys/me`.
required:
- uuid
- prefix
- name
- environment
- is_active
- scopes
- enabled_checks
properties:
enabled_checks:
type: array
items:
type: string
description: Verification checks enabled for the key, for example `"syntax"`, `"mx"` or `"smtp"`.
environment:
type: string
description: 'Environment of the key, matching its prefix: `"live"` or `"test"`.'
is_active:
type: boolean
description: Whether the key is currently active (not revoked, not expired).
name:
type: string
description: Display name of the key.
prefix:
type: string
description: Visible prefix (for example `pm_live_abc12345`).
scopes:
type: array
items:
type: string
description: Scopes granted to the key, for example `"email:verify:single"`.
uuid:
type: string
description: Public UUID of the API key.
CreateApiKeyRequest:
type: object
description: '`POST /api/keys` request body.
The per-key rate limit is not accepted: it is set from the account''s plan.'
required:
- name
properties:
enabled_checks:
type:
- array
- 'null'
items:
type: string
description: 'Verification checks to enable: `"syntax"`, `"mx"`, `"smtp"`, `"disposable"`, `"role"`, `"free"` or `"catchall"`.
Defaults to `syntax`, `mx` and `smtp` when absent. Some checks require a higher plan.'
environment:
type:
- string
- 'null'
description: 'Environment of the key: `"live"` or `"test"`. Defaults to `"live"` when absent.'
name:
type: string
description: Display name shown in the dashboard.
scopes:
type:
- array
- 'null'
items:
type: string
description: 'Scopes to grant, for example `"email:verify:single"`.
Defaults to `email:verify:single`, `email:verify:bulk` and `results:read` when absent.'
ApiErrorBody:
type: object
description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
required:
- error
properties:
error:
$ref: '#/components/schemas/ApiErrorDetail'
description: Error detail.
UpdateApiKeyRequest:
type: object
description: '`PATCH /api/keys/{uuid}` request body.
The rate limit is not editable: it follows the account''s plan.'
properties:
enabled_checks:
type:
- array
- 'null'
items:
type: string
description: New set of enabled checks, with the same values as on creation. Left unchanged when absent.
name:
type:
- string
- 'null'
description: New display name. Left unchanged when absent.
ApiKeyCreatedResponse:
type: object
description: '`POST /api/keys` response body.
The `raw_key` field is the only place the full key is ever returned; it cannot be retrieved again.'
required:
- key
- raw_key
properties:
key:
$ref: '#/components/schemas/ApiKeyResponse'
description: Metadata of the new key.
raw_key:
type: string
description: The full API key. It is returned only once, so store it securely.
ApiErrorDetail:
type: object
description: Detail of an error response.
required:
- code
properties:
code:
type: string
description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
message:
type:
- string
- 'null'
description: 'Present on most error kinds and equal to `code`; the API returns no localized text.
Absent for error kinds that carry no extra detail.'
ApiKeyResponse:
type: object
description: Metadata of an API key, returned when listing, reading, updating or revoking keys.
required:
- uuid
- prefix
- name
- environment
- scopes
- enabled_checks
- rate_limit
- is_active
- request_count
- created_at
properties:
created_at:
type: string
description: RFC 3339 creation timestamp.
enabled_checks:
type: array
items:
type: string
description: Verification checks enabled for the key.
environment:
type: string
description: 'Environment of the key: `"live"` or `"test"`.'
expires_at:
type:
- string
- 'null'
description: RFC 3339 expiry timestamp, or `null` when the key does not expire.
is_active:
type: boolean
description: Whether the key can currently authenticate (not revoked and not expired).
last_used_at:
type:
- string
- 'null'
description: RFC 3339 timestamp of the last request made with the key, or `null` when it was never used.
name:
type: string
description: Display name of the key.
prefix:
type: string
description: Visible prefix of the key (for example `pm_live_abc12345`).
rate_limit:
$ref: '#/components/schemas/RateLimitDto'
description: Request budget of the key.
request_count:
type: integer
format: int64
description: Total number of requests made with the key.
minimum: 0
revoked_at:
type:
- string
- 'null'
description: RFC 3339 timestamp of the revocation, or `null` when the key is not revoked.
scopes:
type: array
items:
type: string
description: Scopes granted to the key.
uuid:
type: string
description: Public UUID of the key.
RateLimitDto:
type: object
description: Request budget of an API key.
required:
- per_minute
properties:
per_minute:
type: integer
format: int32
description: Maximum number of requests the key may make per minute.
minimum: 0
securitySchemes:
bearer_api_key:
type: http
scheme: bearer
description: A `pm_live_*` or `pm_test_*` API key.
jwt:
type: http
scheme: bearer
description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml