pricklymails-com API Keys API

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