REST API
========

The ApiCrate REST API provides direct HTTP access to all services.
Base URL: ``https://api.apicrate.io``

Base URL
--------

All endpoints are served under:

.. code-block:: text

   https://api.apicrate.io/api/v1/

Authentication
--------------

Every request must include one of:

- ``X-API-Key`` header with your API key
- ``Authorization: Bearer <jwt>`` header with a JWT token

See :doc:`/authentication` for details on obtaining and managing keys.

.. code-block:: bash

   # API key
   curl -H "X-API-Key: ac_usr_..." https://api.apicrate.io/api/v1/ip/me

   # JWT
   curl -H "Authorization: Bearer eyJ..." https://api.apicrate.io/api/v1/ip/me

Common Features
---------------

Field Filtering
^^^^^^^^^^^^^^^

Most endpoints support a ``fields`` query parameter to return only specific
fields in the response:

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     "https://api.apicrate.io/api/v1/countries/US?fields=name,capital"

Pagination
^^^^^^^^^^

List endpoints accept ``limit`` and ``offset`` query parameters:

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     "https://api.apicrate.io/api/v1/countries?limit=10&offset=20"

Rate Limiting
^^^^^^^^^^^^^

Every response includes quota headers:

- ``X-Quota-Limit`` -- credits available in your current window
- ``X-Quota-Remaining`` -- requests left in current window
- ``X-Quota-Reset`` -- Unix timestamp when your quota window resets

When the quota is exceeded the API returns HTTP 429.

Response Format
^^^^^^^^^^^^^^^

All responses are JSON with ``Content-Type: application/json``.

Endpoints
---------

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Domain
     - Endpoints
     - Description
   * - :doc:`user-agents`
     - 3
     - Parse User-Agent strings into browser, OS, and device data
   * - :doc:`ip`
     - 3
     - Geolocate IPs to country, city, ISP; detect VPN/proxy/Tor
   * - :doc:`countries`
     - 6
     - ISO 3166 country and subdivision lookup
   * - :doc:`postal`
     - 9
     - Postal code lookup, validation, and spatial queries
   * - :doc:`timezones`
     - 4
     - Timezone info, conversion, and difference calculation
   * - :doc:`hashing`
     - 7
     - Cryptographic digest and password KDF hashing
   * - :doc:`bible`
     - 11
     - Bible verse retrieval, search, and navigation
   * - :doc:`email`
     - 2
     - Email validation and fraud risk scoring

.. toctree::
   :maxdepth: 1
   :hidden:

   user-agents
   ip
   countries
   postal
   timezones
   hashing
   bible
   email
   openapi