Inboxy Service API

openapi: 3.2.0
info:
  title: inboxy Service API
  version: 0.3.0
  summary: Read + manage your inboxy.net inbox programmatically.
  description: 'REST surface over the inboxy alias inbox. Mint aliases, list/search/read

    messages, fetch attachments, manage your API keys, and emit user-initiated

    mail under one of your aliases.


    Mail-emitting paths (`POST /v1/messages/{id}/reply`, `POST /v1/mail/send`,

    `POST /v1/mail/invite`) are recipient-locked and alias-locked server-side:

    the `From:` is always one of the caller''s `@inboxy.net` aliases, the

    recipient is validated against per-user caps and the abuse rules in

    `packages/reply`, and every external message carries the mandatory

    inboxy attribution footer. There is no arbitrary-`From:` send path.


    All endpoints require a bearer API key created from the inboxy.net web UI

    at `/account/keys` (mint is gated by step-up and lives only on the web — there

    is no API-channel mint). Pass it as `Authorization: Bearer ik_…`.


    The signed-token attachment download URLs (`/v1/attachments/{token}/download`,

    `/v1/messages/raw/{token}/download`) are public-by-token — they intentionally

    bypass bearer auth and are not listed here. Obtain them via the JSON

    endpoints below.'
  contact:
    name: inboxy
    url: https://inboxy.net
  license:
    name: Proprietary
servers:
- url: https://api.inboxy.net
  description: Production
security:
- bearerAuth: []
tags:
- name: Service
  description: Health, discovery.
paths:
  /v1/health:
    get:
      tags:
      - Service
      summary: Liveness probe
      description: Cheap path (default) returns worker liveness only — safe for uptime monitors to poll. Pass `?deep=1` to additionally probe D1 + R2 with one bounded read each; the response then includes per-component `checks` and downgrades `status` to `degraded` when any component fails.
      security: []
      parameters:
      - name: deep
        in: query
        description: Set to `1` to run downstream binding probes. Adds D1 + R2 latency per call.
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: 'Liveness OK; `status: degraded` if a deep probe failed.'
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - env
                - public_origin
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                    - degraded
                  env:
                    type: string
                  public_origin:
                    type: string
                  checks:
                    type: object
                    description: Present only on `?deep=1`. One entry per probed binding.
                    additionalProperties:
                      type: string
                      enum:
                      - ok
                      - degraded
      operationId: getV1Health
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ik_…
      description: Static API key. Three scopes — `read` (everything except mutations), `manage` (mutations other than sending) and `send` (`/v1/mail/send`, replies, invites). Mint at https://inboxy.net/account/keys (the web UI gates mint with step-up; there is no API-channel mint).