> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myproceeds.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Health check

> Unauthenticated liveness + readiness probe — no API key required.
Returns `200` with `status: ok` when the API is serving and its
database is reachable, or `503` with `status: degraded` when a
dependency check fails. Intended for uptime monitors and load balancers.




## OpenAPI

````yaml /openapi.yaml get /v1/health
openapi: 3.0.3
info:
  title: myproceeds API
  version: 1.1.0
  description: |
    Public REST API for the myproceeds (x402) commerce platform.

    Tenants use this API to programmatically manage their Services and
    Paywalls. Authentication is via API keys generated from the dashboard.

    ## Authentication

    Send the API key in one of two ways:

      Authorization: Bearer mpk_<64 hex chars>
      X-Api-Key: mpk_<64 hex chars>

    Key format: `mpk_` prefix followed by 64 lowercase hex characters
    (32 random bytes). The raw key is only shown once at creation and
    cannot be recovered later.

    ## Scopes

    Each key carries a set of scopes that determine which endpoints it
    can call:

      - `services:read`     — read services
      - `services:write`    — create/update/delete services (implies read)
      - `paywalls:read`     — read paywalls
      - `paywalls:write`    — create/update/delete paywalls (implies read)
      - `transactions:read` — read payment transactions
      - `events:read`       — read analytics events

    Use `GET /v1/me` to validate a key and inspect the tenant and scopes
    it carries.

    ## Secret handling

    Secret material — service `authConfig` values and paywall custom header
    values — is always masked as `"***"` in API responses. Field names (keys)
    are returned so you can see what is configured; the plaintext values are
    never exposed by the public API.

    ## Rate limits

    Each API key may make up to 1000 requests per 60-second window.
    When exceeded the API responds with `429 Too Many Requests` and a
    `Retry-After` header indicating seconds to wait.

    ## Response envelope

    Successful responses return:

      { "data": ..., "meta": { "requestId": "...", "timestamp": "..." } }

    Lists additionally include `meta.pagination`:

      { "total": N, "limit": L, "offset": O, "hasMore": bool }

    Errors return a `meta.requestId` you can quote to support, which
    correlates with the server log line:

      { "error": "message", "code": "MACHINE_CODE", "details": ...,
        "meta": { "requestId": "...", "timestamp": "..." } }
servers:
  - url: https://api.myproceeds.xyz
    description: Current environment
security:
  - ApiKeyAuth: []
tags:
  - name: Identity
    description: >-
      API-key authenticated endpoint to validate a key and read its
      tenant/scopes
  - name: Services
    description: API-key authenticated CRUD for tenant services
  - name: Paywalls
    description: API-key authenticated CRUD for tenant paywalls
  - name: Data
    description: API-key authenticated read-only access to transactions and analytics
  - name: System
    description: Unauthenticated service health endpoints
paths:
  /v1/health:
    get:
      tags:
        - System
      summary: Health check
      description: |
        Unauthenticated liveness + readiness probe — no API key required.
        Returns `200` with `status: ok` when the API is serving and its
        database is reachable, or `503` with `status: degraded` when a
        dependency check fails. Intended for uptime monitors and load balancers.
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Health'
        '503':
          description: A dependency check failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Health'
      security: []
components:
  schemas:
    Envelope:
      type: object
      required:
        - data
        - meta
      properties:
        data: {}
        meta:
          $ref: '#/components/schemas/Meta'
    Health:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - degraded
        checks:
          type: object
          properties:
            database:
              type: string
              enum:
                - ok
                - error
    Meta:
      type: object
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: |
        API key in format `mpk_<64 hex chars>`. Can alternatively be sent as
        `Authorization: Bearer mpk_...`.

````