# List public keys

List registered extended public keys with filtering and pagination.

Endpoint: GET /public_keys
Version: 0.27.5
Security: Auth

## Query parameters:

  - `limit` (integer)
    Maximum number of items to return.

  - `page` (integer)
    Page number for pagination.

  - `search` (string)
    Filter public keys by label (partial match, case-insensitive).

  - `sort_by` (string)
    Field to sort results by. Use `-` prefix for descending order.

## Response 200 fields (application/json):

  - `items` (array, required)
    List of public keys.

  - `items.id` (string, required)
    Unique identifier (UUID v4).
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `items.value` (string, required)
    BIP32/SLIP-0132 extended public key in Base58Check format.

  - `items.label` (string, required)
    User-friendly label for the public key.
    Example: Main Bitcoin Wallet

  - `items.derivation_path` (string, required)
    HD derivation path in BIP-44 format. Supports both account-level (`m/purpose'/coin_type'/account'`)
and change-level (`m/purpose'/coin_type'/account'/change`) paths.
Account-level paths (depth-3) represent HD wallet accounts and cannot derive addresses directly —
use the children endpoint to create change-level child keys first.

  - `items.children` (array)
    Child keys derived from this account-level key. Present only for account-level keys (depth-3).
Each child represents an external (change=0) or internal (change=1) chain.

  - `items.created_at` (string, required)
    Timestamp when the resource was created.
    Example: 2024-01-15T10:30:00Z

  - `items.updated_at` (string, required)
    Timestamp when the resource was last updated.
    Example: 2024-01-15T10:30:00Z

  - `meta` (object, required)
    Pagination metadata returned on every list response. `page` and `limit` echo the values used to build this page (defaults are applied when the request omits them). `total` and `total_pages` reflect the full result set after any filters are applied.
    Example: {"limit":20,"page":1,"total":42,"total_pages":3}

  - `meta.limit` (integer, required)
    Page size used to build this response.

  - `meta.page` (integer, required)
    Index of the page returned, starting at 1.

  - `meta.total` (integer, required)
    Total number of items matching the request across all pages.

  - `meta.total_pages` (integer, required)
    Total number of pages available at the current `limit`.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: https://docs.vilna.io/apis/problems/internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /errors?id=XXXXXX-xxxxx

  - `code` (string, required)
    Stable machine-readable error code (`{domain}.{reason}`) for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: resource.not_found

  - `fields` (array)
    List of invalid fields in the request

  - `fields.name` (string, required)
    The name of the invalid field
    Example: meta

  - `fields.reason` (string, required)
    Why this field is invalid
    Example: Exceeded maximum data size — must not exceed 1000 characters

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: https://docs.vilna.io/apis/problems/internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /errors?id=XXXXXX-xxxxx

  - `code` (string, required)
    Stable machine-readable error code (`{domain}.{reason}`) for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: resource.not_found

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: https://docs.vilna.io/apis/problems/internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /errors?id=XXXXXX-xxxxx

  - `code` (string, required)
    Stable machine-readable error code (`{domain}.{reason}`) for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: resource.not_found

## Response default fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: https://docs.vilna.io/apis/problems/internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /errors?id=XXXXXX-xxxxx

  - `code` (string, required)
    Stable machine-readable error code (`{domain}.{reason}`) for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: resource.not_found